@mclawnet/shared 0.1.7 → 0.1.9

package/dist/protocol/agent.d.ts

@@ -1,4 +1,6 @@
 import type { SessionProcessState } from "../types/session.js";
+import type { SandboxLevel } from "../sandbox.js";
+import type { AgentManifestPayload, BackendKind } from "../model-catalog.js";
 export interface AgentAuthRequired {
     type: "auth_required";
 }
@@ -10,12 +12,6 @@ export interface AgentAck {
     type: "ack";
     ts: number;
 }
-export interface AgentSessionCreate {
-    type: "session.create";
-    sessionId: string;
-    workDir?: string;
-    resumeId?: string;
-}
 export interface AgentSessionClose {
     type: "session.close";
     sessionId: string;
@@ -34,7 +30,7 @@ export interface AgentClaudeExecute {
     sessionId: string;
     content: string;
     workDir?: string;
-    claudeSessionId?: string;
+    backendSessionId?: string;
     useBrainCore?: boolean;
 }
 export interface AgentFsListDir {
@@ -55,7 +51,7 @@ export interface AgentLoadSessionHistory {
     type: "load_session_history";
     requestId: string;
     workDir: string;
-    claudeSessionId: string;
+    backendSessionId: string;
     /** Pagination: return messages with seq < before. Omit/0 = newest tail. */
     before?: number;
     /** Max messages returned. Default 50, max 200. */
@@ -83,6 +79,7 @@ export interface AgentSwarmExecute {
     targetInstance?: string;
     crewConfig?: {
         templateName?: string;
+        displayName?: string;
         roles?: Array<{
             roleName: string;
             count?: number;
@@ -144,7 +141,7 @@ export interface SwarmResumeControl {
     agentId?: string;
     swarmId: string;
 }
-export type AgentServerMessage = AgentAuthRequired | AgentRegistered | AgentAck | AgentSessionCreate | AgentSessionClose | AgentClaudeInput | AgentClaudeExecute | AgentFsListDir | AgentListFolders | AgentListHistorySessions | AgentLoadSessionHistory | AgentProxyOpen | AgentProxyData | AgentProxyClose | AgentSwarmExecute | AgentListRoles | AgentListTemplates | AgentAbortExecution | AgentSessionForceRestart | AgentGenericRequest | SwarmSpawnControl | SwarmResumeControl | ProjectsListRequest | ProjectsGetRequest | ProjectsTasksRequest | ProjectsTaskRequest | ProjectsSwarmsRequest | ProjectsSwarmRequest | ProjectsInboxesRequest | ProjectsInboxRequest | ProjectsSwarmSessionIdRequest | ProjectsFilesListRequest | ProjectsFileReadRequest | ProjectsFileWriteRequest;
+export type AgentServerMessage = AgentAuthRequired | AgentRegistered | AgentAck | AgentSessionClose | AgentClaudeInput | AgentClaudeExecute | SessionCreate | SessionInput | SessionUpdateSticky | HubPermissionDecision | AgentFsListDir | AgentListFolders | AgentListHistorySessions | AgentLoadSessionHistory | AgentProxyOpen | AgentProxyData | AgentProxyClose | AgentSwarmExecute | AgentListRoles | AgentListTemplates | AgentAbortExecution | AgentSessionForceRestart | AgentGenericRequest | SwarmSpawnControl | SwarmResumeControl | ProjectsListRequest | ProjectsGetRequest | ProjectsTasksRequest | ProjectsTaskRequest | ProjectsSwarmsRequest | ProjectsSwarmRequest | ProjectsInboxesRequest | ProjectsInboxRequest | ProjectsSwarmSessionIdRequest | ProjectsFilesListRequest | ProjectsFileReadRequest | ProjectsFileWriteRequest | ProjectsEnsureProjectRequest | WorkdirMkdirRequest | ProjectsSwarmAddRoleRequest | ProjectsShipmentGetRequest | ProjectsShipmentActionRequest | ProjectsShipmentDiffRequest | ProjectsShipmentsListRequest | ProjectsAlwaysOnGetRequest | ProjectsAlwaysOnSetRequest | ProjectsAlwaysOnTickNowRequest;
 export interface AgentAuth {
     type: "auth";
     token: string;
@@ -159,12 +156,19 @@ export interface AgentHeartbeat {
 export interface AgentSessionCreated {
     type: "session.created";
     sessionId: string;
-    claudeSessionId: string;
+    backendSessionId: string;
 }
 export interface AgentSessionError {
     type: "session.error";
     sessionId: string;
     error: string;
+    /**
+     * (N3) Optional structured error code. When the underlying error is a
+     * typed Error subclass with a `code` property (e.g. RespawnRequiredError
+     * with code: "RESPAWN_REQUIRED"), agent forwards it so hub/UI can branch
+     * without parsing the message string.
+     */
+    code?: string;
 }
 export interface AgentClaudeOutput {
     type: "claude.output";
@@ -174,7 +178,7 @@ export interface AgentClaudeOutput {
 export interface AgentClaudeTurnComplete {
     type: "claude.turn_complete";
     sessionId: string;
-    claudeSessionId?: string;
+    backendSessionId?: string;
     cost?: number;
     duration?: number;
     contextUsage?: {
@@ -184,14 +188,33 @@ export interface AgentClaudeTurnComplete {
 }
 /**
  * Agent → Hub: Claude CLI emitted its `system/init` frame, meaning the
- * backend session is now bound to a real claudeSessionId. Hub uses this to
+ * backend session is now bound to a real backendSessionId. Hub uses this to
  * persist the ID immediately (instead of waiting for turn_complete which
  * never fires if the turn crashes mid-flight).
  */
 export interface AgentClaudeSessionStarted {
     type: "claude.session_started";
     sessionId: string;
-    claudeSessionId: string;
+    backendSessionId: string;
+}
+export interface AgentPermissionRequest {
+    type: "agent.permission_request";
+    sessionId: string;
+    requestId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    reason?: string;
+    backendType?: "claude" | "codex";
+    meta?: Record<string, unknown>;
+    turnId?: string;
+    agentId?: string;
+}
+export interface HubPermissionDecision {
+    type: "client.permission_decision";
+    sessionId: string;
+    requestId: string;
+    decision: "allow" | "allow_session" | "deny" | "abort";
+    reason?: string;
 }
 export interface AgentFsListDirResult {
     type: "fs.list_dir_result";
@@ -270,9 +293,59 @@ export interface AgentSwarmStatus {
         status: string;
         currentTask?: string;
         color?: string;
+        /**
+         * Per-role backend (claude | codex). Must round-trip through the hub
+         * into the DB's `crewConfig.roles` because continuation/recreation
+         * paths spawn roles from that stored value; missing it silently
+         * downgrades codex roles to claude after agent restart.
+         */
+        backend?: "claude" | "codex";
+        /**
+         * Per-role sandbox level. Same round-trip requirement as backend —
+         * omitting from the wire payload causes recreation paths to silently
+         * downgrade to the default workspace-write sandbox.
+         */
+        sandbox?: SandboxLevel;
     }>;
     plan?: unknown;
 }
+/**
+ * M6.2.1: shipment snapshot pushed from agent → hub for live UI display.
+ * Mirrors `ShipmentResult` from @mclawnet/swarm but duplicated here so the
+ * shared protocol package doesn't take a dep on swarm (same pattern as
+ * `ProjectSummaryWire`).
+ */
+export interface ShipmentSnapshot {
+    strategy: "pr" | "diff-only" | "skipped";
+    /** ISO timestamp; optional for back-compat with test fixtures. */
+    createdAt?: string;
+    title?: string;
+    summary?: string;
+    prUrl?: string;
+    branchName?: string;
+    diffPath?: string;
+    reportPath?: string;
+    prAttemptError?: string;
+    error?: string;
+    /**
+     * ISO timestamp stamped by mergeShipment() when the user marks the PR as
+     * merged in the UI. M6.3 surfaces this in the Shipments history list as the
+     * "Merged" filter and visual badge — strategy stays "pr" forever, mergedAt
+     * is the only signal that the merge actually happened on GitHub.
+     */
+    mergedAt?: string;
+}
+/**
+ * M6.2.1: agent → hub push when a swarm's shipment pipeline finishes
+ * (success or fallback). Hub caches and fans out as `swarm_shipment` to all
+ * browser watchers of `sessionId` so the M6.2 UI can render shipment status
+ * live without polling.
+ */
+export interface AgentSwarmShipment {
+    type: "swarm.shipment";
+    sessionId: string;
+    shipment: ShipmentSnapshot;
+}
 export interface AgentRolesListResult {
     type: "roles_list_result";
     sessionId: string;
@@ -315,7 +388,7 @@ export interface AgentSessionDied {
     sessionId: string;
     reason?: string;
     /**
-     * (PR-C) Last-known claudeSessionId of the dead session, when available.
+     * (PR-C) Last-known backendSessionId of the dead session, when available.
      *
      * Hub uses this to decide what to keep in db when reconciling the
      * session.died event: db's `claude_session_id` is preserved (so the user
@@ -323,7 +396,7 @@ export interface AgentSessionDied {
      * because pre-PR-C agents don't send it and not every dead session ever
      * reached `system/init`.
      */
-    claudeSessionId?: string;
+    backendSessionId?: string;
 }
 /** Agent → Hub: push available skill list to browsers */
 export interface AgentSkillListUpdate {
@@ -337,7 +410,91 @@ export interface AgentSessionStateReport {
     type: "session.state";
     sessionId: string;
     processState: SessionProcessState;
-    claudeSessionId?: string;
+    backendSessionId?: string;
+}
+/**
+ * Agent → Hub: report installed backends and their capabilities.
+ * Sent once right after `registered`; can be re-sent on manifest refresh.
+ */
+export interface AgentManifest {
+    type: "agent.manifest";
+    payload: AgentManifestPayload;
+}
+/**
+ * Agent → Hub: workspace prepared for a chat session (N5).
+ * Sent right after WorkspaceManager.prepare resolves. Hub forwards to
+ * browser watchers so ChatHeader can show a "worktree: <path>" badge.
+ */
+export interface AgentSessionWorktreeReady {
+    type: "session.worktree_ready";
+    sessionId: string;
+    /** Absolute path on the agent host. */
+    cwd: string;
+    /** "git-worktree" | "snapshot-copy" */
+    strategy: "git-worktree" | "snapshot-copy";
+    /** Populated for git-worktree only — null for snapshot fallback. */
+    branchName?: string | null;
+    /**
+     * (PR-A review fix I3) The repo HEAD branch at worktree create time —
+     * GitWorktreeProvider already computes this from `git rev-parse
+     * --abbrev-ref HEAD`. Persisted so worktree.ship can target it as the PR
+     * base instead of guessing "main". Null for snapshot-copy strategy.
+     */
+    baseBranch?: string | null;
+    /** The original project root (== ChatCreateConversation.workDir). */
+    projectRoot: string;
+}
+/**
+ * Agent → Hub: workspace lifecycle ended (session closed). Sent on close,
+ * not abort — agent never auto-deletes the worktree (keep=true).
+ * Browser uses this to prompt the user: "Worktree retained at <path>;
+ * review/merge/delete manually."
+ */
+export interface AgentSessionWorktreeClosed {
+    type: "session.worktree_closed";
+    sessionId: string;
+    cwd: string;
+    branchName?: string | null;
+    /**
+     * (PR1 follow-up) Optional context fields so the UI's Banner reducer
+     * doesn't depend on the in-memory `session` row still being present.
+     * Hub fills these in when synthesizing the frame from a DELETE
+     * /api/sessions request (the row is about to be dropped, so the
+     * store can't read them back). Agent-emitted frames may omit them;
+     * reducer falls back to `session?.workDir` / `session?.worktreeBaseBranch`.
+     */
+    baseBranch?: string | null;
+    projectRoot?: string | null;
+}
+/**
+ * (PR-A) Agent → Hub: emitted after a successful `worktree.ship` generic RPC.
+ * Hub persists `result` to chat_sessions.shipment_result_json and fans the
+ * frame out to subscribed browser sessions so the UI can update the banner /
+ * shipment-history view immediately without re-querying.
+ *
+ * Sent in addition to the generic.response that completes the RPC — the
+ * response carries the same payload back to the originating browser, but
+ * other tabs / devices need this push to stay in sync.
+ */
+export interface AgentSessionShipmentUpdated {
+    type: "session.shipment_updated";
+    sessionId: string;
+    /** Free-form result shape — UI reads `strategy` ("pr"|"diff-only") and
+     *  branches on it for display. Persisted as JSONB. */
+    result: Record<string, unknown>;
+}
+/**
+ * (PR-A) Agent → Hub: emitted after a successful `worktree.delete` generic
+ * RPC. Hub clears chat_sessions.worktree_path / worktree_branch /
+ * worktree_strategy (since the on-disk worktree no longer exists) and fans
+ * the frame out so any open Banner / Header on other tabs dismisses /
+ * stops showing the (now stale) badge.
+ */
+export interface AgentSessionWorktreeDeleted {
+    type: "session.worktree_deleted";
+    sessionId: string;
+    /** Echoed so receivers can correlate; not strictly required. */
+    cwd?: string;
 }
 /** Hub -> Agent: generic request (browser-initiated) */
 export interface AgentGenericRequest {
@@ -364,7 +521,7 @@ export interface AgentGenericPush {
     event: string;
     data: Record<string, unknown>;
 }
-export type AgentClientMessage = AgentAuth | AgentHeartbeat | AgentSessionCreated | AgentSessionError | AgentClaudeOutput | AgentClaudeTurnComplete | AgentClaudeSessionStarted | AgentFsListDirResult | AgentFoldersListResult | AgentHistorySessionsResult | AgentSessionHistoryResult | AgentProxyOpened | AgentProxyData | AgentProxyClose | AgentSwarmOutput | AgentSwarmTurnComplete | AgentSwarmStatus | AgentRolesListResult | AgentTemplatesListResult | AgentExecutionAborted | AgentSessionDied | AgentSkillListUpdate | AgentSessionStateReport | AgentGenericResponse | AgentGenericPush | ProjectsListResult | ProjectsGetResult | ProjectsTasksResult | ProjectsTaskResult | ProjectsSwarmsResult | ProjectsSwarmResult | ProjectsInboxesResult | ProjectsInboxResult | ProjectsSwarmSessionIdResult | ProjectsFilesListResult | ProjectsFileReadResult | ProjectsFileWriteResult;
+export type AgentClientMessage = AgentAuth | AgentHeartbeat | AgentSessionCreated | AgentSessionError | AgentClaudeOutput | AgentClaudeTurnComplete | AgentClaudeSessionStarted | AgentPermissionRequest | AgentFsListDirResult | AgentFoldersListResult | AgentHistorySessionsResult | AgentSessionHistoryResult | AgentProxyOpened | AgentProxyData | AgentProxyClose | AgentSwarmOutput | AgentSwarmTurnComplete | AgentSwarmStatus | AgentSwarmShipment | AgentRolesListResult | AgentTemplatesListResult | AgentExecutionAborted | AgentSessionDied | AgentSkillListUpdate | AgentSessionStateReport | AgentManifest | AgentSessionWorktreeReady | AgentSessionWorktreeClosed | AgentSessionShipmentUpdated | AgentSessionWorktreeDeleted | AgentGenericResponse | AgentGenericPush | ProjectsListResult | ProjectsGetResult | ProjectsTasksResult | ProjectsTaskResult | ProjectsSwarmsResult | ProjectsSwarmResult | ProjectsInboxesResult | ProjectsInboxResult | ProjectsSwarmSessionIdResult | ProjectsFilesListResult | ProjectsFileReadResult | ProjectsFileWriteResult | ProjectsEnsureProjectResult | WorkdirMkdirResult | ProjectsSwarmAddRoleResult | ProjectsShipmentGetResult | ProjectsShipmentActionResult | ProjectsShipmentDiffResult | ProjectsShipmentsListResult | ProjectsAlwaysOnGetResult | ProjectsAlwaysOnSetResult | ProjectsAlwaysOnTickNowResult;
 /**
  * Capability string the agent advertises in its `auth` message to declare
  * support for the `projects.*` RPC namespace. The hub fails fast with HTTP
@@ -373,6 +530,13 @@ export type AgentClientMessage = AgentAuth | AgentHeartbeat | AgentSessionCreate
  * agent connecting to a new hub mid-deploy.
  */
 export declare const PROJECTS_RPC_CAPABILITY = "projects.rpc.v1";
+/**
+ * Capability string for agent-side workDir/project creation helpers. This is
+ * separate from `projects.rpc.v1` so a new hub can fail fast instead of
+ * timing out when an older agent supports project reads but not project
+ * ensure/create flows.
+ */
+export declare const WORKDIR_RPC_CAPABILITY = "workdir.rpc.v1";
 export interface ProjectsListRequest {
     type: "projects.list";
     requestId: string;
@@ -567,4 +731,399 @@ export interface ProjectsFileWriteResult {
         details?: Record<string, unknown>;
     } | null;
 }
+export type ProjectWorkdirErrorCode = "invalid_path" | "root_forbidden" | "path_forbidden" | "workdir_not_found" | "not_directory" | "create_dir_unsupported" | "meta_write_failed" | "project_load_failed" | "parent_not_found" | "parent_not_directory" | "mkdir_failed" | "agent_error";
+export interface ProjectWorkdirErrorWire {
+    status: number;
+    message: string;
+    /**
+     * `root_forbidden` is reserved for the filesystem root itself.
+     * `path_forbidden` means the normalized path is exactly, or under, a
+     * protected system prefix such as /etc or /usr.
+     */
+    code?: ProjectWorkdirErrorCode;
+    details?: Record<string, unknown>;
+}
+export interface ProjectsEnsureProjectRequest {
+    type: "projects.ensure_project";
+    requestId: string;
+    workDir: string;
+    /**
+     * Reserved for the future workDir-creation flow. T3 only supports existing
+     * directories; agents may return a 400 when this is true until mkdir support
+     * lands.
+     */
+    createDir?: boolean;
+}
+export interface ProjectsEnsureProjectResult {
+    type: "projects.ensure_project_result";
+    requestId: string;
+    ok: boolean;
+    project: ProjectSummaryWire | null;
+    encodedCwd?: string;
+    workDir?: string;
+    createdMeta?: boolean;
+    error: ProjectWorkdirErrorWire | null;
+}
+export interface WorkdirMkdirRequest {
+    type: "workdir.mkdir";
+    requestId: string;
+    workDir: string;
+}
+export interface WorkdirMkdirResult {
+    type: "workdir.mkdir_result";
+    requestId: string;
+    ok: boolean;
+    workDir?: string;
+    created?: boolean;
+    error: ProjectWorkdirErrorWire | null;
+}
+export interface ProjectsSwarmAddRoleRequest {
+    type: "projects.swarm_add_role";
+    requestId: string;
+    encodedCwd: string;
+    swarmId: string;
+    roleName: string;
+    backend?: "claude" | "codex";
+    sandbox?: string;
+    customPrompt?: string;
+    taskPrompt?: string;
+}
+export interface ProjectsSwarmAddRoleResult {
+    type: "projects.swarm_add_role_result";
+    requestId: string;
+    ok: boolean;
+    swarmId?: string;
+    instanceId?: string;
+    error?: string;
+}
+export interface ProjectsShipmentGetRequest {
+    type: "projects.shipment_get";
+    requestId: string;
+    encodedCwd: string;
+    swarmId: string;
+}
+export interface ProjectsShipmentGetResult {
+    type: "projects.shipment_get_result";
+    requestId: string;
+    projectFound: boolean;
+    shipment: ShipmentSnapshot | null;
+    diffContent?: string;
+    reportContent?: string;
+}
+/**
+ * M6.2 hotfix S4: full uncapped diff.patch download. Companion to
+ * `ProjectsShipmentGetRequest` — the inline `diffContent` there is capped
+ * at 1 MiB; this RPC returns the entire file as a string so the hub can
+ * stream it back to the browser as a `text/plain` download. `content: null`
+ * with `projectFound: true` means the swarm exists but never produced a
+ * diff (strategy=pr without local diff, skipped, etc).
+ */
+export interface ProjectsShipmentDiffRequest {
+    type: "projects.shipment_diff";
+    requestId: string;
+    encodedCwd: string;
+    swarmId: string;
+}
+export interface ProjectsShipmentDiffResult {
+    type: "projects.shipment_diff_result";
+    requestId: string;
+    projectFound: boolean;
+    content: string | null;
+}
+/**
+ * M6.3: cross-swarm shipment history listing. Scans
+ * `<projectsDir>/<encoded>/swarms/<id>/shipment.json` and returns every
+ * parseable entry sorted by `createdAt` desc (newest first; missing
+ * timestamps sink to the bottom). Corrupt JSON files are skipped with a
+ * warn rather than failing the whole list — the UI is best-effort historic
+ * data, not a transaction.
+ *
+ * The agent returns the full ShipmentSnapshot per swarm so the UI can
+ * filter / render without a second round-trip per row. Each entry stays
+ * bounded (no diff/report inlined here — M6.3 history view is a list, not a
+ * detail view; users click through to the per-swarm WorkspaceBlock for diff).
+ */
+export interface ShipmentListEntry {
+    swarmId: string;
+    shipment: ShipmentSnapshot;
+}
+export interface ProjectsShipmentsListRequest {
+    type: "projects.shipments_list";
+    requestId: string;
+    encodedCwd: string;
+}
+export interface ProjectsShipmentsListResult {
+    type: "projects.shipments_list_result";
+    requestId: string;
+    projectFound: boolean;
+    shipments: ShipmentListEntry[];
+}
+export type ProjectsShipmentActionKind = "merge" | "apply" | "discard";
+export interface ProjectsShipmentActionRequest {
+    type: "projects.shipment_action";
+    requestId: string;
+    encodedCwd: string;
+    swarmId: string;
+    action: ProjectsShipmentActionKind;
+    /**
+     * Apply-only: bypass the "dirty working tree" and "branch already exists"
+     * safety guards. Plumbed end-to-end from the hub route (?force=true query
+     * or {force:true} body) → agent handler → applyShipment. UI does NOT pass
+     * this in M6.2 — wired now so M7 can add a second-confirm UX without
+     * another protocol round-trip.
+     */
+    force?: boolean;
+}
+export interface ProjectsShipmentActionResult {
+    type: "projects.shipment_action_result";
+    requestId: string;
+    /** false when project/swarm not found (hub maps to 404). */
+    projectFound: boolean;
+    ok: boolean;
+    message?: string;
+    newBranchName?: string;
+    error?: string;
+}
+/**
+ * Hub → Agent: create a backend session.
+ * Replaces the "first call" semantics of claude.execute. Carries backend
+ * kind + sticky model/mode + optional initial input.
+ */
+export interface SessionCreate {
+    type: "session.create";
+    sessionId: string;
+    workDir?: string;
+    backend: BackendKind;
+    sticky?: {
+        model?: string;
+        mode?: string;
+    };
+    systemPrompt?: string;
+    useBrainCore?: boolean;
+    /** Optional first user input — agent calls sendUserInput right after spawn. */
+    initialInput?: string;
+    /** Resume from this backendSessionId (Claude --resume). */
+    backendSessionId?: string;
+    /** (N5) Prepare an isolated workspace before spawning; see ChatCreateConversation. */
+    useWorktree?: boolean;
+    /**
+     * (PR-A) Optional user-supplied branch suffix. Agent prepends `clawnet/chat-`
+     * to keep namespace isolation. Only meaningful when useWorktree=true.
+     */
+    worktreeBranchName?: string;
+}
+/**
+ * Hub → Agent: send user input to an existing session.
+ * Replaces the "subsequent call" semantics of claude.execute. Carries
+ * optional per-turn override (model / mode) that wins over sticky.
+ */
+export interface SessionInput {
+    type: "session.input";
+    sessionId: string;
+    content: string;
+    messageMeta?: {
+        model?: string;
+        mode?: string;
+    };
+    /**
+     * (N3) Optional resume hint — when agent receives session.input for a
+     * session it doesn't have alive (e.g. after agent restart), it can use
+     * this to auto-recreate via `--resume <backendSessionId>` instead of
+     * surfacing session.error. Hub populates this from chat_sessions.
+     */
+    backendSessionId?: string;
+    /**
+     * (N3) Optional working directory for restart-recovery. When agent
+     * recovers via --resume, the spawn needs cwd + memory injection +
+     * braincore mounts. Hub populates from chat_sessions.work_dir.
+     * Healthy-path sendUserInput ignores this (the existing process has
+     * its own cwd already).
+     */
+    workDir?: string;
+    /**
+     * (N3) Optional braincore mount flag for restart-recovery. Same
+     * rationale as workDir — only consulted by the recovery branch.
+     */
+    useBrainCore?: boolean;
+}
+/**
+ * Hub → Agent: update sticky model/mode on a running session.
+ * Partial — fields omitted keep their current value. Agent applies to
+ * next spawn; in-flight turn is not interrupted.
+ */
+export interface SessionUpdateSticky {
+    type: "session.update_sticky";
+    sessionId: string;
+    sticky: {
+        model?: string;
+        mode?: string;
+    };
+}
+export type AlwaysOnMode = "off" | "quiet" | "active" | "aggressive";
+/**
+ * M8.2 — per-source opt-in toggles for the cascade picker. The agent applies
+ * sensible defaults (TaskStore + Idea Todo + Idea Research on; introspection
+ * off) when fields are absent. The M8.3 UI surfaces the toggles; today only
+ * an `always-on.json` edit can flip them.
+ */
+export interface AlwaysOnTaskSourcesConfig {
+    /** L1 — TaskStore (sprint backlog). Default true. */
+    taskStore?: boolean;
+    /** L2a — Ideas with status=todo. Default true. */
+    ideaTodo?: boolean;
+    /** L2b — Ideas with status=idea (research cycle). Default true. */
+    ideaResearch?: boolean;
+    /** L3 — Queen self-introspection (opt-in). Default false. */
+    introspection?: boolean;
+}
+export interface AlwaysOnConfig {
+    mode: AlwaysOnMode;
+    /** 1..20 cycles/day, integer. */
+    dailyBudget: number;
+    /** ISO timestamp; absent or in the past = not paused. */
+    pausedUntil?: string;
+    /**
+     * Template name used when AlwaysOnManager spawns a scheduler cycle swarm.
+     * Forward-compatible: the M7 UI doesn't expose this yet; agents pick a safe
+     * default ("minimal") when absent. PATCH-able once the toggle UI lands.
+     */
+    templateName?: string;
+    /**
+     * M8.2 — per-source opt-in toggles. Omitted fields fall back to defaults
+     * (taskStore / ideaTodo / ideaResearch on; introspection off).
+     */
+    taskSources?: AlwaysOnTaskSourcesConfig;
+    /**
+     * M8.2 — cooldown (in hours) between consecutive L3 introspection cycles.
+     * Independent of dailyBudget so the agent doesn't burn its main quota on
+     * self-introspection. Default 24.
+     */
+    introspectionCooldownHours?: number;
+    /**
+     * M8.2 — runtime state: ISO timestamp of the most recent introspection
+     * cycle that ran (regardless of whether it produced ideas). Persisted to
+     * disk by AlwaysOnManager so cooldown survives an agent restart.
+     */
+    lastIntrospectionAt?: string;
+    /**
+     * M8.2 — runtime state: when true, every idea produced by the previous
+     * introspection cycle was archived by the user. Next introspection will
+     * skip itself to avoid producing more noise. Cleared as soon as one prior
+     * idea survives (status != archived).
+     */
+    lastIntrospectionRejected?: boolean;
+    /**
+     * M8 hotfix I1/I2 — runtime state: when set, the agent has an
+     * introspection swarm spawned in a prior tick whose output has not yet
+     * been ingested. The next IntrospectionSource pick observes this
+     * breadcrumb, checks the swarm's terminal status, POSTs the cohort, and
+     * clears the field. Persisted so an agent restart mid-cycle still ingests
+     * the result on next boot. Wire-exposed for future UI surfacing — the
+     * current UI ignores it.
+     */
+    pendingIntrospectionSwarmId?: string;
+    /**
+     * PR-B follow-up — workspace.cwd of the pending introspection swarm,
+     * captured at spawn time. Persisted alongside `pendingIntrospectionSwarmId`
+     * so the spawner can resolve the candidates output file after
+     * `swarm_complete` deletes the swarm from the coordinator registry
+     * (post-deletion `getSwarm()` returns undefined and the live workspace
+     * handle is lost). Absent when introspection swarm runs without an
+     * isolated workspace (snapshot-copy fallback skipped, or no
+     * WorkspaceManager wired). Wire-exposed for parity with the agent-side
+     * persisted config; current UI ignores it.
+     */
+    pendingIntrospectionWorkspaceCwd?: string;
+}
+/**
+ * Live runtime snapshot from a DiscoveryScheduler instance. M7.2 returns an
+ * empty/default snapshot when no scheduler is wired (no live runner yet —
+ * that's M7.3); the UI still renders the "Status" line correctly.
+ *
+ * All Date values are serialised as ISO strings here because the protocol
+ * crosses a JSON boundary.
+ */
+export interface AlwaysOnTickRecord {
+    at: string;
+    decision: "fired" | "skipped" | "halted";
+    /** Gates evaluated, in order. Last entry on a non-fire is the gate that
+     *  short-circuited the cascade. */
+    gateBreakdown: Array<{
+        gate: string;
+        decision: {
+            kind: "fire";
+        } | {
+            kind: "skip";
+            reason: string;
+        } | {
+            kind: "halt";
+            reason: string;
+        };
+    }>;
+    durationMs: number;
+}
+export interface AlwaysOnSnapshot {
+    mode: AlwaysOnMode;
+    ticksToday: number;
+    /** ISO timestamp or null when scheduler has never fired. */
+    lastFireAt: string | null;
+    /** ISO timestamp or null when stopped / mode=off / halted. */
+    nextTickAt: string | null;
+    /** Last N tick records, newest at the end. */
+    recentTicks: AlwaysOnTickRecord[];
+}
+export interface ProjectsAlwaysOnGetRequest {
+    type: "projects.always_on_get";
+    requestId: string;
+    encodedCwd: string;
+}
+export interface ProjectsAlwaysOnGetResult {
+    type: "projects.always_on_get_result";
+    requestId: string;
+    projectFound: boolean;
+    config: AlwaysOnConfig;
+    snapshot: AlwaysOnSnapshot;
+}
+export interface ProjectsAlwaysOnSetRequest {
+    type: "projects.always_on_set";
+    requestId: string;
+    encodedCwd: string;
+    /** Partial update; omitted fields keep their persisted value. */
+    config: Omit<Partial<AlwaysOnConfig>, "pausedUntil"> & {
+        pausedUntil?: string | null;
+    };
+}
+export interface ProjectsAlwaysOnSetResult {
+    type: "projects.always_on_set_result";
+    requestId: string;
+    projectFound: boolean;
+    config: AlwaysOnConfig;
+    snapshot: AlwaysOnSnapshot;
+    error?: string;
+}
+/**
+ * B6 — dev-only force-tick. Bypasses the always-on gate cascade (userActive
+ * in particular) by clearing `lastActivityAt` for the project before
+ * invoking `DiscoveryScheduler.tickNow()`. Hub gates this on
+ * `NODE_ENV !== "production"` so it never reaches the agent in prod.
+ *
+ * Returned snapshot reflects the state AFTER the forced tick so callers can
+ * observe ticksToday increment / lastFireAt move in one round trip.
+ */
+export interface ProjectsAlwaysOnTickNowRequest {
+    type: "projects.always_on_tick_now";
+    requestId: string;
+    encodedCwd: string;
+}
+export interface ProjectsAlwaysOnTickNowResult {
+    type: "projects.always_on_tick_now_result";
+    requestId: string;
+    projectFound: boolean;
+    /** "fired" | "skipped" | "halted" — matches TickRecord.decision. */
+    decision?: string;
+    /** Per-gate breakdown so dev tools can see WHY a forced tick still skipped. */
+    gateBreakdown?: AlwaysOnTickRecord["gateBreakdown"];
+    snapshot?: AlwaysOnSnapshot;
+    error?: string;
+}
 //# sourceMappingURL=agent.d.ts.map