/**
 * Task Pool Controller — HTTP handlers for Task Pool API
 *
 * Endpoints:
 * - GET  /api/task-pool       — list all claimable WorkItems
 * - POST /api/task-pool/claim — agent claims next available item
 * - POST /api/task-pool/release/:workItemId — release item back to pool
 * - GET  /api/task-pool/stats — pool statistics snapshot
 *
 * @module controllers/task-pool/task-pool.controller
 */
import type { Request, Response } from 'express';
/**
 * Check a request body for cross-team routing hints and apply the
 * {@link ServiceContractGate} when present. Opt-in: if the body doesn't
 * carry both `fromTeamId` and `toTeamId` the gate is skipped, preserving
 * backward compatibility with existing delegate flows.
 *
 * Accepted body shapes (either works):
 *   { fromTeamId, toTeamId, requestType }
 *   { metadata: { fromTeamId, toTeamId, requestType } }
 *
 * `requestType` defaults to the WorkItem's `title`/`description` when the
 * caller hasn't supplied a more specific phrase. An explicit boolean
 * `forceCrossTeam: true` bypasses the gate (used for declared emergencies —
 * still logged).
 *
 * @param body - Raw request body (already validated as an object)
 * @returns `null` when the request should proceed; otherwise a gate
 *          rejection decision ready to surface as 403.
 */
export declare function maybeEnforceContract(body: Record<string, unknown>): Promise<null | {
    status: number;
    payload: Record<string, unknown>;
}>;
/**
 * Adds a WorkItem to the Task Pool.
 *
 * HTTP entry point for the V3 pull-mode task path. Used by delegate-task
 * and other orchestration shell skills to queue execution-ready WorkItems.
 *
 * Accepts two body shapes:
 *
 * 1. **Minimal `CreateWorkItemInput`** (preferred) — `{type, owner, title,
 *    target?, description?, briefMarkdown?, priority?, requestId?, ...}`.
 *    The server fills `id` (uuid), `status` (`'queued'` or `'blocked'`
 *    if `dependsOn` set), `createdAt`, `retryCount=0`, `maxRetries`,
 *    `inputTokens=0`, `outputTokens=0`, `cost=0`.
 *
 * 2. **Legacy full `WorkItem`** — body carries `id` AND `status` AND
 *    `createdAt`. The server passes through unchanged (subject to the
 *    same shape validation as before). Preserved for callers that
 *    construct WIs locally with deterministic ids (e.g. break-down-request,
 *    decomposition pipelines that need to record id-references upfront).
 *
 * **Why both shapes.** 2026-05-12 dogfood: orc-side `delegate-task` shell
 * skill and 3 sibling skills (`agent/core/create-task`,
 * `team-leader/decompose-goal`, `team-leader/delegate-task`) all send
 * the minimal shape. They were silently 400'd by the strict validator
 * because they omit `id` / `status` / `createdAt` / `retryCount` etc.
 * Result: every orc delegation failed — `task-pool/add` returned
 * `WorkItem.id is required and must be a string`, the skill exited 1,
 * the orc thought it had delegated but no WI ever entered the pool.
 *
 * Fix the endpoint, not 4 skills — the canonical creation primitive
 * `createWorkItem(input)` already exists for internal callers; the
 * HTTP surface should expose the same shape.
 *
 * @param req - Express request with WorkItem body
 * @param res - Express response
 */
export declare function addItem(req: Request, res: Response): Promise<void>;
/**
 * Returns all claimable (queued, unclaimed) WorkItems in the pool.
 *
 * Supports optional query filters:
 * - types: comma-separated WorkItemType values
 * - owner: WorkItemOwner value
 * - target: target agent session name
 * - missionId: filter by mission
 *
 * @param req - Express request
 * @param res - Express response
 */
export declare function listAvailable(req: Request, res: Response): Promise<void>;
/**
 * Agent claims a WorkItem from the pool.
 *
 * Two modes:
 * - **Next-available (FIFO)** — omit `workItemId`. Claims the next queued
 *   item matching `filters` for the agent.
 * - **Targeted** — pass `workItemId`. Claims that specific queued item
 *   (#679: previously impossible — the endpoint only ever handed out the
 *   next-available item, so a specific stuck `queued` WI could not be
 *   targeted for claim, forcing operators to repeatedly claim-and-release
 *   to drain it). The service-layer `claimSpecificItem` still enforces the
 *   agent-liveness and target-respect gates, so a targeted claim of a WI
 *   owned by a different agent (or for a dead session) is refused.
 *
 * Request body:
 * ```json
 * {
 *   "agentId": "crewly-product-leo-member-n",
 *   "workItemId": "wi-123",                       // optional — targeted claim
 *   "filters": { "types": ["delegate"], "owner": "agent" }  // ignored if workItemId set
 * }
 * ```
 *
 * @param req - Express request with agentId (and optional workItemId) in body
 * @param res - Express response with claimed item and claim, or 404
 */
export declare function claimItem(req: Request, res: Response): Promise<void>;
/**
 * Releases a claimed WorkItem back to the pool.
 *
 * Request body:
 * ```json
 * { "reason": "agent busy" }
 * ```
 *
 * @param req - Express request with workItemId param
 * @param res - Express response
 */
export declare function releaseItem(req: Request, res: Response): Promise<void>;
/**
 * Marks a running WorkItem as completed ('done').
 *
 * ## Canonical body shape (STRICT)
 *
 * ```json
 * {
 *   "agentId": "crewly-product-leo-member-n",
 *   "result": { "summary": "what I produced …", "prNumber": 525, "...": "..." },
 *   "tokenUsage": { "inputTokens": 0, "outputTokens": 0, "totalCost": 0 }
 * }
 * ```
 *
 * Validation rules (in order — first failure short-circuits):
 * 1. `workItemId` URL param — required (path; never empty).
 * 2. `agentId` body field — required, non-empty string. Identifies the
 *    completing agent for token attribution and audit trail.
 * 3. `result.summary` body field — required, non-empty string after trim.
 *    Enforces the Request Contract's Done Definition: workers report
 *    what they produced (artifact, decision, verified result), not just
 *    "done".
 *
 * Any field beyond `summary` inside `result` (e.g. `prNumber`, `links`)
 * is preserved into `WorkItem.output` via spread merge, so downstream
 * verifiers can read the proof-of-work without digging through chat logs.
 *
 * ## Hygiene #4 (PR ?) — strict-shape lock
 *
 * Prior to Hygiene #4, three skill callers (`config/skills/agent/core/{
 * report-status,complete-task}/execute.sh`, `config/skills/orchestrator/
 * complete-task/execute.sh`) and two TS callers (`tool-registry.ts`
 * §complete_task + §report_status auto-complete) emitted top-level
 * `{summary}` instead of the canonical `{agentId, result:{summary}}`.
 * That shape failed both validators (missing agentId + result.summary),
 * forcing every worker into a direct-curl workaround that Quinn
 * surfaced on the #499 verify-WI dogfood.
 *
 * Decision (locked T+9min on Hygiene #4 by Quinn): keep the controller
 * STRICT — fix all 5 callsites in the same PR rather than ship a
 * backward-compat resolver. Rationale: all 5 callers are in-tree, OSS
 * is the only consumer (Crewly Pro extends via Plugin System and does
 * NOT fork core skill or task-pool callers per workspace CLAUDE.md),
 * and a compat layer would add permanent ambiguity for zero downstream
 * benefit.
 *
 * @param req - Express request with `workItemId` param + canonical body
 * @param res - Express response
 */
export declare function completeItem(req: Request, res: Response): Promise<void>;
/**
 * Marks a WorkItem as blocked.
 *
 * Request body:
 * ```json
 * { "agentId": "crewly-product-leo-member-n", "reason": "waiting for X" }
 * ```
 *
 * @param req - Express request with workItemId param
 * @param res - Express response
 */
export declare function blockItem(req: Request, res: Response): Promise<void>;
/**
 * Marks a running WorkItem as failed.
 *
 * Request body:
 * ```json
 * { "agentId": "crewly-product-leo-member-n", "error": "something went wrong" }
 * ```
 *
 * @param req - Express request with workItemId param
 * @param res - Express response
 */
export declare function failItemHandler(req: Request, res: Response): Promise<void>;
/**
 * Cleanly cancel a WorkItem that is `queued`, `blocked`, or `scheduled`
 * (i.e. has not been claimed yet). Closes the #609 gap where no
 * non-destructive API existed for retiring a stuck queued WI — the only
 * options were `complete` (requires running) or `DELETE ?force=1` (hard
 * delete with no audit trail).
 *
 * Request body: `{ "reason": "short human-readable why" }`
 *   `reason` is required. It's persisted on `cancelReason` and surfaces
 *   in the activity timeline so the cancellation isn't an opaque event.
 *
 * Responses:
 *   - 200 `{ success: true, workItemId, cancelledFrom }`
 *   - 400 `{ success: false, error: 'reason is required' }`
 *   - 400 `{ success: false, error: 'WorkItem status must be queued|blocked|scheduled', currentStatus }`
 *   - 404 `{ success: false, error: 'WorkItem not found' }`
 */
export declare function cancelQueuedItem(req: Request, res: Response): Promise<void>;
/**
 * Returns pool statistics: total, claimed, available, avg wait time, breakdowns.
 *
 * @param req - Express request
 * @param res - Express response with PoolSnapshot
 */
export declare function getStats(req: Request, res: Response): Promise<void>;
/**
 * Processes a heartbeat from an agent for their active claim.
 *
 * Request body:
 * ```json
 * { "claimId": "uuid", "agentId": "crewly-product-leo-member-n" }
 * ```
 *
 * @param req - Express request with claimId and agentId in body
 * @param res - Express response
 */
export declare function heartbeat(req: Request, res: Response): Promise<void>;
/**
 * Extends the lease duration for an active claim.
 *
 * Request body:
 * ```json
 * { "claimId": "uuid", "agentId": "crewly-product-leo-member-n" }
 * ```
 *
 * @param req - Express request with claimId and agentId in body
 * @param res - Express response
 */
export declare function extendLease(req: Request, res: Response): Promise<void>;
/**
 * Scans for claims with expired leases. Returns two lists:
 * - expiring: lease expired, within grace period
 * - graceExceeded: past grace period, should be revoked
 *
 * Used by the Reconciler and for debugging.
 *
 * @param req - Express request
 * @param res - Express response
 */
export declare function scanExpired(req: Request, res: Response): Promise<void>;
/**
 * Revokes a claim and releases the work item back to the pool.
 * Typically called by the Reconciler when grace period is exceeded.
 *
 * Request body:
 * ```json
 * { "reason": "grace period exceeded" }
 * ```
 *
 * @param req - Express request with claimId param
 * @param res - Express response
 */
export declare function revokeAndRelease(req: Request, res: Response): Promise<void>;
/**
 * Returns WorkItems currently in the pool — including cancelled,
 * done_by_worker, failed, etc. — so admin / cleanup tooling can audit the
 * full state without filtering by claimability.
 *
 * Distinct from `/api/task-pool` (and its `/all` alias) which return ONLY
 * the available subset (queued + unclaimed). The existing alias was
 * naming-confusing for cleanup workflows; rather than rename and break
 * downstream consumers, this endpoint adds the audit-shaped surface that
 * the bulk-DELETE script needs.
 *
 * Optional query filters (#679): callers may narrow by `status` (a single
 * value or comma-separated list) and/or `target` (exact session match).
 * These were previously IGNORED — the endpoint always returned every item.
 * The `complete-task` skill resolves the WorkItem to complete via
 * `GET /api/task-pool/items?status=running&target=<session>` and takes the
 * first result; with no server-side filtering it received an arbitrary item
 * (another agent's WI, or an already-terminal one), so the worker's
 * completion landed on the WRONG WorkItem and was rejected with 409 —
 * leaving the worker unable to close its own task. Honoring the filters
 * makes that resolution correct (and returns an empty list when the session
 * has no matching item, instead of a misleading first-of-everything).
 *
 * Response: `{ success: true, data: WorkItem[], count }`.
 *
 * @param req - Express request (optional `?status=`, `?target=` query)
 * @param res - Express response
 */
export declare function listAllItems(req: Request, res: Response): Promise<void>;
/**
 * Removes a WorkItem from the pool entirely. Powers the bulk-cleanup
 * script and any future operator workflow that needs to drop stale or
 * misplanned items.
 *
 * Request:
 *   DELETE /api/task-pool/:workItemId[?force=1]
 *
 * Response shapes:
 *   - 200 `{ success: true, removed: true,  workItem: WorkItem,  hadActiveClaim }`
 *   - 200 `{ success: true, removed: false, reason: 'not_found' }`
 *     (idempotent — repeated calls on a missing id do not error)
 *   - 409 `{ success: false, error: '...', code: 'work_item_claimed',
 *           workItemId, claimId, claimedBy }`
 *     (active claim + no force; pass `?force=1` to override)
 *   - 400 `{ success: false, error: 'workItemId param is required' }`
 *
 * @param req - Express request with `workItemId` route param and
 *   optional `?force=1` query flag.
 * @param res - Express response
 */
export declare function deleteItem(req: Request, res: Response): Promise<void>;
/**
 * Fetches a single WorkItem by id.
 *
 * Replaces `POST /task-management/read-task` and `POST /task-management/get-output`.
 * Both v1 endpoints walked the project's `.crewly/tasks/` filesystem to load
 * the `.md` body and `<id>.output.json`. With v1 retired, the entire
 * task body, brief, and worker output live on the WorkItem itself —
 * one fetch returns everything.
 *
 * @param req - Express request, `:workItemId` route param
 * @param res - 200 `{ success, data: WorkItem }` | 404 if not found
 */
export declare function getItem(req: Request, res: Response): Promise<void>;
/**
 * Stores worker-supplied structured output on a WorkItem.
 *
 * Replaces v1's `<taskId>.output.json` filesystem write. The TL
 * `verify-output` skill reads this back via `GET /api/task-pool/items/:id`.
 *
 * Body: `{ output: Record<string, unknown> }` — output may be any JSON shape;
 * the schema is task-specific.
 *
 * @param req - Express request, `:workItemId` route param + body.output
 * @param res - 200 `{ success, data: WorkItem }` | 404 | 400
 */
export declare function setItemOutput(req: Request, res: Response): Promise<void>;
/**
 * Reassigns a WorkItem to a different agent.
 *
 * Replaces `POST /task-management/handoff` (which moved the `.md` file
 * between agent task directories). With v1 retired, handoff is a single
 * `target` field flip on the WorkItem plus an audit-trail note.
 *
 * Body: `{ newTarget: string, fromAgent?: string, reason?: string }`.
 *
 * @param req - Express request
 * @param res - 200 `{ success, data: WorkItem }` | 404 | 400 | 409 (terminal)
 */
export declare function handoffItem(req: Request, res: Response): Promise<void>;
/**
 * Appends a working-state note to a WorkItem.
 *
 * Replaces `POST /task-management/sync` and `POST /task-management/save-working-notes`,
 * both of which appended progress lines to the `.md` task body. With v1
 * retired, notes accumulate under `WorkItem.metadata.notes[]`.
 *
 * Body: `{ author: string, note: string }`.
 *
 * @param req - Express request
 * @param res - 200 `{ success, data: WorkItem }` | 404 | 400
 */
export declare function appendItemNote(req: Request, res: Response): Promise<void>;
//# sourceMappingURL=task-pool.controller.d.ts.map