Task Creation API (/api/task)

Relevant source files

The following files were used as context for generating this wiki page:

• app/api/task/route.ts
• components/TaskForm.tsx
• app/task/page.tsx
• README.md
• middleware.ts
• lib/agents.ts (Referenced via imports in route.ts and TaskForm.tsx)

The Task Creation API is a core backend component of the GeNCorE Command Center that enables users to assign specific tasks to AI agents. It acts as a bridge between the web interface and GitHub, converting user-submitted descriptions into GitHub Issues within a target repository.

This API is primarily consumed by the /task page via the TaskForm component. Its scope includes validating agent identities, formatting task descriptions into standardized Issue bodies, and managing the integration with the GitHub REST API using secure environment variables.

API Endpoint Specification

The endpoint is implemented as a Next.js App Router POST handler. It requires a JSON payload containing the identifier of the targeted AI agent and a detailed description of the task to be performed.

POST /api/task

Parameter	Type	Description
agent	string	The ID of the agent (e.g., "copilot", "claude", "codex").
description	string	The detailed instructions for the agent.

Sources: app/api/task/route.ts:14-34, README.md:21

Response Schema

On success, the API returns a 201 Created status with the GitHub Issue object. On failure, it returns relevant error messages such as 400 Bad Request for missing fields or 500 Internal Server Error for configuration issues.

Sources: app/api/task/route.ts:77-94, components/TaskForm.tsx:44-63

Architecture and Data Flow

The task creation process follows a structured flow from the client-side UI to the GitHub API. The backend route utilizes the GITHUB_TOKEN to authenticate requests and targets the repository defined by NEXT_PUBLIC_REPO_OWNER and NEXT_PUBLIC_REPO_NAME.

Sequence of Task Creation

The following diagram illustrates the lifecycle of a task creation request:

The diagram shows the interaction between the frontend, the authentication middleware, the task route, and external GitHub services.
Sources: app/api/task/route.ts:7-75, middleware.ts:31-62, components/TaskForm.tsx:28-63

Logic and Implementation Details

Request Validation

The API performs several checks before communicating with GitHub:

1. Environment Variables: Ensures GITHUB_TOKEN is present in the environment.
2. Input Integrity: Validates that agent and description are not null or empty.
3. Agent Verification: Checks the agent ID against AGENT_IDS to ensure the target exists.

Sources: app/api/task/route.ts:9-40

Issue Formatting

The API constructs a standardized GitHub Issue body. It includes a header specifying the agent, the user's description, and a footer timestamping the creation via the GeNCorE Command Center.

const issueBody = [
  `## Zlecenie dla ${agentConfig.label}`,
  '',
  description.trim(),
  '',
  '---',
  `*Zadanie utworzone przez GeNCorE Command Center · ${new Date().toLocaleString('pl-PL')}*`,
].join('\n')

Sources: app/api/task/route.ts:44-51

GitHub Integration Mapping

Each task is assigned to a specific GitHub user and labeled based on the AGENTS_BY_ID configuration.

GitHub Field	Value Source
title	Agent Emoji + Label + Description Slice (80 chars)
labels	agentConfig.issueLabel
assignees	[agentConfig.githubLogin]

Sources: app/api/task/route.ts:65-69

Security and Authorization

The Task Creation API is protected by several security layers defined in the system architecture:

• Middleware Protection: All requests to /api/task must pass through middleware.ts, which verifies an auth cookie containing an HMAC-SHA256 hash of the ADMIN_TOKEN.
• Token Isolation: The GITHUB_TOKEN is kept server-side and is never exposed to the frontend.
• Input Sanitization: The description is trimmed, and the agent ID is validated against a strict allowlist (AGENT_IDS).

Sources: middleware.ts:47-62, README.md:92-105, app/api/task/route.ts:37-40

Client-Side Integration

The TaskForm component handles the submission state and local history storage. Upon a successful API response, the task is saved to the browser's localStorage (under the key gencore_tasks) to maintain a history for the user.

Flow of client-side logic after interacting with the API.
Sources: components/TaskForm.tsx:28-68, app/task/page.tsx:30-50

Conclusion

The /api/task route provides a robust interface for converting high-level instructions into actionable GitHub Issues. By automating agent assignment and labeling, it ensures that tasks are correctly routed to the appropriate AI entities within the GitHub ecosystem, while maintaining a secure and audited history within the GeNCorE dashboard.