@teamscala/service-boot 0.23.322 → 0.23.324

package/src/fn-routers/task-sync-router.d.ts

@@ -1,402 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- * @indivisible-unit
- *
- * CLI-AGNOSTIC task-sync CORE — the bridge between a lane's native task list
- * (Claude Code TodoWrite, OpenCode todowrite, future CLIs) and the `work_items`
- * table, which is the single source of truth for "what work does this lane
- * have." Detailed contract + the per-CLI adapter split: apps/agent-fleet.md
- * (task-sync section).
- *
- * Design (operator requirement): work_items is the source; each CLI's task list
- * is a WRITE-THROUGH PROJECTION, never a peer. One source + write-through
- * projection cannot diverge by construction — no two-way sync, no conflict
- * resolution. The lane↔task binding is SYMMETRIC: a lane is a lane whether the
- * pane is an orchestrator or a supervised agent (both have tasks).
- *
- * Mapping: an operator request = a kind='task' work_item; the lane's todo items
- * = kind='subtask' rows under it via parent_id. The task carries the lane
- * identity in kind_data.lane = { pane, session, cli_kind, role } so any surface
- * (fleet UI, another lane) can resolve "who owns this work" and push changes
- * back. Binding is by pane identity (the stable $TMUX_PANE), not by fleet run —
- * so it works before/without the fleet_agent_runs.work_item_id join (that column
- * is a UI convenience for the unified lane+task+subtask view, not a dependency).
- *
- * These procedures are the ONLY CLI-agnostic surface an adapter calls:
- *   bindLane           — bind (create-or-confirm) a lane's task. SessionStart.
- *   upsertFromTaskList — write a lane's current task list through to subtasks (AGENT→DB leg, OpenCode whole-list).
- *   upsertFromTaskHook — apply a per-item Claude Code PostToolUse:TaskCreate/Update/Delete (AGENT→DB leg, Claude per-item).
- *   readTaskList       — read a lane's current subtasks as a normalized list (DB→AGENT backstop).
- *   applyExternalChange — record an out-of-band subtask change + notify the owning lane (DB→AGENT realtime leg).
- * A CLI with no native task surface (Codex today — upstream_issue openai-codex-2966)
- * has NO adapter: it degrades to work_items-only. The work is still tracked and
- * visible in the projects UI; the lane simply has no live projection. That is a
- * legitimate end state, not a gap to paper over with a fake adapter.
- */
-import { type Context } from "./auth-router.ts";
-import * as v from "valibot";
-/** A lane's native task-list item, normalized. Every CLI adapter maps to this. */
-export interface TaskListItem {
-    content: string;
-    status: "pending" | "in_progress" | "completed";
-    /** CLI-native stable id when the CLI provides one (TodoWrite has none; opencode todo row id). */
-    mark?: string;
-}
-/**
- * Input contract for upsertFromTaskList. oRPC does NOT parse the JSON body into
- * `input` for a schema-less procedure (see the bindLane comment in this file) —
- * so without an explicit `.input()` schema, `input.lane_session` is ALWAYS
- * undefined and the procedure throws "requires lane_session" unconditionally.
- * Measured 2026-07-29: every pi/opencode whole-list `task_list` publish 400'd
- * for exactly this reason (the per-item upsertFromTaskHook path worked because
- * it unwraps `raw.json ?? raw`). Declaring the schema is the documented remedy
- * and the pattern every other `authed.input(...)` procedure in service-boot
- * already follows. The pi adapter (scala-hooks.ts syncTaskList) already sends
- * `{ lane_session, task_list, source }` — it was always valid; the server never
- * read it.
- */
-export declare const upsertFromTaskListInput: v.ObjectSchema<{
-    readonly lane_session: v.StringSchema<undefined>;
-    readonly task_list: v.ArraySchema<v.ObjectSchema<{
-        readonly content: v.StringSchema<undefined>;
-        readonly status: v.PicklistSchema<["pending", "in_progress", "completed"], undefined>;
-        readonly mark: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    }, undefined>, undefined>;
-    readonly source: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-}, undefined>;
-/** Who a lane IS — symmetric across orchestrator/agent roles and across CLIs. */
-export interface LaneIdentity {
-    /** "tmux:%42" — authoritative pane identity ($TMUX_PANE). */
-    pane: string;
-    session?: string;
-    /** pane-inventory inferCliKind: claude-code | opencode | codex | unknown. */
-    cli_kind?: string;
-    /** agent | orchestrator — both have tasks; the model does not assume a supervised agent. */
-    role?: string;
-    /**
-     * Optional. work_items.organisation_id is NOT NULL; when the caller omits it
-     * (auto-bind at SessionStart — an adopted or channel-dispatched lane has no
-     * client org), bindLane defaults to the platform org via resolveBindOrg.
-     */
-    organisation_id?: string;
-}
-export interface WorkItem {
-    id: string;
-    kind: string;
-    parent_id: string | null;
-    organisation_id: string;
-    title: string;
-    status: string | null;
-    position: string | null;
-    completed: boolean | null;
-    kind_data: Record<string, unknown>;
-}
-export type Prisma = {
-    work_items: {
-        findFirst: (a: unknown) => Promise<WorkItem | null>;
-        findMany: (a: unknown) => Promise<WorkItem[]>;
-        create: (a: unknown) => Promise<WorkItem>;
-        update: (a: unknown) => Promise<WorkItem>;
-        deleteMany: (a: unknown) => Promise<{
-            count: number;
-        }>;
-    };
-    comments?: {
-        findFirst: (a: unknown) => Promise<CommentRow | null>;
-    };
-};
-/** A `comments` row — only the fields readAssignedBrief touches. */
-export interface CommentRow {
-    content: string;
-    created_at: Date;
-}
-/**
- * A dispatched run already points at its fleet_tasks row. Task-sync may fill
- * the convenience join for an adopted lane, but must never replace that
- * dispatch identity with the lane's work_items projection id.
- */
-export declare function untrackedRunForPane(pane: string): {
-    pane: string;
-    state: {
-        not: string;
-    };
-    tracked_task_id: null;
-};
-/**
- * Resolve the org a lane's task is created under. Explicit when the lane knows
- * its org (a dispatched fleet lane carries one); defaults to the platform org
- * otherwise — an adopted or channel-dispatched pane has no client org, and the
- * platform org is the home for fleet/internal lane tasks (where the operator's
- * PM view reads), so auto-bind at SessionStart seeds the task there.
- */
-export declare function resolveBindOrg(explicit?: string): string;
-/**
- * Record a task-sync hook DISCARD to event_log so it is observable + queryable,
- * not silently swallowed by the hook command's `>/dev/null 2>&1 || true`. The
- * endpoint records it server-side regardless of what the hook does with stdout.
- * Fire-and-forget per event-log-is-the-only-durable-event-log. The headline
- * discard is "no-task-bound" (lane has no bound parent task — exactly the gap
- * that SessionStart auto-bind closes; once binding is automatic this becomes a
- * rare safety signal rather than the default outcome).
- */
-export declare function recordTaskSyncDiscard(reason: string, pane: string | null, extra?: Record<string, unknown>): void;
-/**
- * Record a discard AND return the soft {applied:false} body in one step — every
- * no-op path in upsertFromTaskHook goes through here so none can silently drop
- * an event. The returned shape matches the prior `{applied:false, reason,...}`.
- */
-export declare function discardApplied(reason: string, pane: string | null, extra?: Record<string, unknown>): {
-    applied: false;
-    reason: string;
-} & Record<string, unknown>;
-/**
- * Trim a task subject at the first tool-call marker.
- *
- * A subject arriving as `Cut judge false positives</subject>\n<parameter
- * name="description">Live gate blocks ~half...` is not a title with odd
- * punctuation — it is the raw tool call, and it renders on the dashboard as a
- * wall of XML where the operator expects a task name (observed live 2026-07-25,
- * 3 rows). The malformation happens upstream in the CLI's hook payload, which
- * this service does not control, so the defence belongs at the WRITE boundary:
- * `work_items` is the single source of truth for every surface, and once a
- * corrupted title lands there every reader shows it.
- *
- * Truncating rather than rejecting is deliberate: the text BEFORE the marker is
- * the real subject and is worth keeping. Dropping the row instead would lose a
- * task the lane genuinely created.
- */
-export declare function sanitizeTaskSubject(raw: string): string;
-export declare function classifyTaskHookEvent(evt: {
-    hook_event_name?: unknown;
-    task_subject?: unknown;
-}): "completed" | "created" | "tool";
-export declare const taskSyncRouter: {
-    /**
-     * Bind (create-or-confirm) the task a lane owns. Called from a SessionStart
-     * adapter so the lane has a durable task row before its first todo write.
-     * Idempotent: re-binding updates the identity (role/cli_kind can change) but
-     * never orphans existing subtasks. After binding, links the lane's
-     * fleet_agent_runs row (matched by pane) to the task via tracked_task_id —
-     * the join the operator's lane-labels monitor + the unified fleet view read.
-     */
-    bindLane: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
-        headers: Headers;
-        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
-        prisma: any;
-        user: import("./auth-router.ts").User;
-        orgId: string | null | undefined;
-    }>, v.OptionalSchema<v.ObjectSchema<{
-        readonly lane: v.OptionalSchema<v.ObjectSchema<{
-            readonly pane: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            readonly session: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            readonly cli_kind: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            readonly role: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            readonly organisation_id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-        }, undefined>, undefined>;
-        readonly title: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-        readonly parent_id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    }, undefined>, undefined>, import("@orpc/contract").Schema<{
-        task_id: string;
-        created: boolean;
-    }, {
-        task_id: string;
-        created: boolean;
-    }>, Record<never, never>, Record<never, never>>;
-    /**
-     * AGENT→DB leg. Write a lane's CURRENT task list through to subtasks. The
-     * list is authoritative for this lane (it's what the CLI just rendered), so
-     * this is a full reconcile: create/update/delete to match. Matching is by
-     * stable mark when the CLI provides one, else by content. Does NOT dispatch
-     * a change notification — the lane that authored the list already has it.
-     */
-    upsertFromTaskList: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
-        headers: Headers;
-        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
-        prisma: any;
-        user: import("./auth-router.ts").User;
-        orgId: string | null | undefined;
-    }>, v.ObjectSchema<{
-        readonly lane_session: v.StringSchema<undefined>;
-        readonly task_list: v.ArraySchema<v.ObjectSchema<{
-            readonly content: v.StringSchema<undefined>;
-            readonly status: v.PicklistSchema<["pending", "in_progress", "completed"], undefined>;
-            readonly mark: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-        }, undefined>, undefined>;
-        readonly source: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    }, undefined>, import("@orpc/contract").Schema<{
-        task_id: string;
-        created: number;
-        updated: number;
-        deleted: number;
-        total: number;
-    }, {
-        task_id: string;
-        created: number;
-        updated: number;
-        deleted: number;
-        total: number;
-    }>, Record<never, never>, Record<never, never>>;
-    /**
-     * Claude Code PostToolUse:TaskCreate/TaskUpdate hook entry. Claude Code's
-     * todo tool is the per-item Task* family (TaskCreate/TaskUpdate) — TodoWrite
-     * was REMOVED in recent Claude Code; the hook matcher keys on
-     * TaskCreate/TaskUpdate, never TodoWrite. The hook command posts the RAW hook
-     * event (stdin) + an x-lane-pane header (tmux:$TMUX_PANE). Fired as a
-     * PostToolUse:TaskCreate/Update hook (NOT a "TaskCreated" event — that is
-     * not a real Claude Code hook event + never fired); this procedure
-     * applies the per-item change (TaskCreate → new subtask keyed by the harness
-     * task id; TaskUpdate → status/title flip on the matching subtask). Server-
-     * side extraction keeps the hook command a trivial jq|curl. Accepts the event
-     * raw (input.tool_name) OR oRPC-enveloped (input.json.tool_name). Session-
-     * less: fn.taskSync is page-gate-exempt; localhost pane shell authenticates
-     * as super-admin via resolveUser. Soft-returns on any no-op (never throws).
-     */
-    upsertFromTaskHook: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
-        headers: Headers;
-        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
-        prisma: any;
-        user: import("./auth-router.ts").User;
-        orgId: string | null | undefined;
-    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
-        applied: boolean;
-        op: string;
-        taskId: string;
-    } | ({
-        applied: false;
-        reason: string;
-    } & Record<string, unknown>), {
-        applied: boolean;
-        op: string;
-        taskId: string;
-    } | ({
-        applied: false;
-        reason: string;
-    } & Record<string, unknown>)>, Record<never, never>, Record<never, never>>;
-    /**
-     * DB→AGENT backstop read. Returns the lane's current subtasks in the
-     * normalized shape every CLI adapter maps to its native list. Called by the
-     * SessionStart/UserPromptSubmit adapters so a pane never opens or continues
-     * on stale tasks, and by a lane after it receives a "your tasks changed"
-     * channel notification.
-     */
-    readTaskList: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
-        headers: Headers;
-        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
-        prisma: any;
-        user: import("./auth-router.ts").User;
-        orgId: string | null | undefined;
-    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
-        task_id: null;
-        task_title: null;
-        subtasks: never[];
-    } | {
-        task_id: string;
-        task_title: string;
-        subtasks: TaskListItem[];
-    }, {
-        task_id: null;
-        task_title: null;
-        subtasks: never[];
-    } | {
-        task_id: string;
-        task_title: string;
-        subtasks: TaskListItem[];
-    }>, Record<never, never>, Record<never, never>>;
-    /**
-     * DB→AGENT self-brief leg. A spawned lane PULLS its own brief — nothing is
-     * pasted, typed, passed as an argument or sent over a channel
-     * (`action-emission-architecture.md` "The lane PULLS its brief"). The lane's
-     * CLI extension reads its own session id on load, calls this procedure, and
-     * reads the brief from the task's LATEST comment. The comment — not the
-     * description, not a stale comment — is the brief for THIS run: every spawn
-     * writes a NEW comment, so "what was this lane told" always has exactly one
-     * answer (`assignment-as-dispatch`). Handler lives in task-sync-brief.ts
-     * (router is at its line budget); mounted here so fn.taskSync surfaces it.
-     */
-    readAssignedBrief: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
-        headers: Headers;
-        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
-        prisma: any;
-        user: import("./auth-router.ts").User;
-        orgId: string | null | undefined;
-    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
-        work_item_id: string | null;
-        brief: string | null;
-        comment_created_at: string | null;
-        status: import("./task-sync-brief.ts").BriefReadStatus;
-    }, {
-        work_item_id: string | null;
-        brief: string | null;
-        comment_created_at: string | null;
-        status: import("./task-sync-brief.ts").BriefReadStatus;
-    }>, Record<never, never>, Record<never, never>>;
-    /** SPAWNER→DB brief mint: `spawn_agent_tab` turns an initialPrompt into the task row (brief = first comment) the lane self-briefs from; returns the work_item_id that rides the spawn payload. Handler in task-sync-assign.ts. */
-    createBriefTask: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
-        headers: Headers;
-        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
-        prisma: any;
-        user: import("./auth-router.ts").User;
-        orgId: string | null | undefined;
-    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
-        work_item_id: string;
-    }, {
-        work_item_id: string;
-    }>, Record<never, never>, Record<never, never>>;
-    /**
-     * DB→AGENT realtime leg (explicit dispatch path). Record an out-of-band
-     * change to a subtask's status (operator toggles it in the projects UI,
-     * another lane edits a shared task) and notify the OWNING lane's pane that
-     * its projection is stale. The pane's adapter re-reads (readTaskList) and
-     * updates its native list. Symmetric counterpart to upsertFromTaskList:
-     * there the lane is the originator (no self-echo); here the lane is the
-     * recipient.
-     *
-     * COMPLETION STEP (not MVP): this procedure is the explicit trigger. For
-     * FULL coverage — every work_items subtask write, including the projects
-     * UI's generated CRUD — a Postgres trigger + LISTEN subscriber on
-     * scala-channel fires the same publish, so an operator edit reaches the
-     * lane with no explicit call. Tracked in apps/agent-fleet.md task-sync.
-     */
-    applyExternalChange: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
-        headers: Headers;
-        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
-        prisma: any;
-        user: import("./auth-router.ts").User;
-        orgId: string | null | undefined;
-    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
-        task_id: string;
-        lane_pane: string | null;
-        notified: boolean;
-    }, {
-        task_id: string;
-        lane_pane: string | null;
-        notified: boolean;
-    }>, Record<never, never>, Record<never, never>>;
-};
-/**
- * The Claude Code per-item task lifecycle applied to a lane's work_items
- * subtasks — the AGENT→DB leg for the Task* tool family (TaskCreate /
- * TaskUpdate / TaskDelete) and the dedicated TaskCreated / TaskCompleted events.
- *
- * Extracted verbatim from the upsertFromTaskHook ORPC handler so the FULL
- * lifecycle — created, in_progress, completed, deleted — is unit-testable with a
- * mock prisma (same testability split as claim-orchestrator-session, and the
- * router-handlers-only-execute half of planReconcile). The ORPC handler is now a
- * thin `authed` wrapper that delegates here; this function takes the exact
- * `(input, context)` the handler would have bound, so behaviour is unchanged.
- *
- * `task-projection-converges`: every state a task reaches must write through, or
- * the projection is an append-only log and the operator cannot see what a lane is
- * doing. The matcher covering TaskCreate|TaskUpdate|TaskDelete is what makes all
- * four states reach this handler; this body is what applies them.
- */
-export declare function upsertFromTaskHookHandler(input: unknown, context: Context): Promise<{
-    applied: boolean;
-    op: string;
-    taskId: string;
-} | ({
-    applied: false;
-    reason: string;
-} & Record<string, unknown>)>;