@gajae-code/coding-agent 0.3.0 → 0.3.1

package/dist/types/modes/shared/agent-wire/handshake.d.ts

@@ -0,0 +1,46 @@
+import { BRIDGE_PROTOCOL_VERSION, type BridgeFrameType } from "./protocol";
+import type { BridgeCommandScope } from "./scopes";
+export type BridgeCapability = "events" | "prompt" | "permission" | "elicitation" | "ui.declarative" | "ui.editor" | "ui.terminal_input" | "host_tools" | "host_uri" | "client_bridge.read_text_file" | "client_bridge.write_text_file" | "client_bridge.create_terminal";
+export interface BridgeProtocolRange {
+    min: number;
+    max: number;
+}
+export interface BridgeHandshakeRequest {
+    protocol_version_range: BridgeProtocolRange;
+    capabilities: BridgeCapability[];
+    requested_scopes: BridgeCommandScope[];
+    last_seq?: number;
+}
+export interface BridgeEndpointDescriptor {
+    events: string;
+    commands: string;
+    uiResponses: string;
+    claimControl: string;
+    disconnectControl: string;
+    hostToolResults: string;
+    hostUriResults: string;
+}
+export interface BridgeHandshakeAccepted {
+    status: "accepted";
+    protocol_version: typeof BRIDGE_PROTOCOL_VERSION;
+    session_id: string;
+    accepted_capabilities: BridgeCapability[];
+    accepted_scopes: BridgeCommandScope[];
+    unsupported: BridgeCapability[];
+    endpoints: BridgeEndpointDescriptor;
+    frame_types: BridgeFrameType[];
+}
+export interface BridgeHandshakeRejected {
+    status: "rejected";
+    reason: "incompatible_version" | "unauthorized" | "invalid_request";
+    message: string;
+}
+export type BridgeHandshakeResponse = BridgeHandshakeAccepted | BridgeHandshakeRejected;
+export declare function isBridgeHandshakeRequest(value: unknown): value is BridgeHandshakeRequest;
+export declare function negotiateBridgeHandshake(request: BridgeHandshakeRequest, server: {
+    sessionId: string;
+    capabilities: readonly BridgeCapability[];
+    scopes: readonly BridgeCommandScope[];
+    endpoints: BridgeEndpointDescriptor;
+    frameTypes: readonly BridgeFrameType[];
+}): BridgeHandshakeResponse;

package/dist/types/modes/shared/agent-wire/host-tool-bridge.d.ts

@@ -0,0 +1,16 @@
+import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
+import type { RpcHostToolCallRequest, RpcHostToolCancelRequest, RpcHostToolDefinition, RpcHostToolResult, RpcHostToolUpdate } from "../../rpc/rpc-types";
+type RpcHostToolOutput = (frame: RpcHostToolCallRequest | RpcHostToolCancelRequest) => void;
+export declare function isRpcHostToolResult(value: unknown): value is RpcHostToolResult;
+export declare function isRpcHostToolUpdate(value: unknown): value is RpcHostToolUpdate;
+export declare class RpcHostToolBridge {
+    #private;
+    constructor(output: RpcHostToolOutput);
+    getToolNames(): string[];
+    setTools(tools: RpcHostToolDefinition[]): AgentTool[];
+    handleResult(frame: RpcHostToolResult): boolean;
+    handleUpdate(frame: RpcHostToolUpdate): boolean;
+    requestExecution(definition: RpcHostToolDefinition, toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<unknown>): Promise<AgentToolResult<unknown>>;
+    rejectAllPending(message: string): void;
+}
+export {};

package/dist/types/modes/shared/agent-wire/host-uri-bridge.d.ts

@@ -0,0 +1,17 @@
+import { InternalUrlRouter } from "../../../internal-urls";
+import type { InternalResource, InternalUrl, ResolveContext, WriteContext } from "../../../internal-urls/types";
+import type { RpcHostUriCancelRequest, RpcHostUriRequest, RpcHostUriResult, RpcHostUriSchemeDefinition } from "../../rpc/rpc-types";
+type RpcHostUriOutput = (frame: RpcHostUriRequest | RpcHostUriCancelRequest) => void;
+export declare function isRpcHostUriResult(value: unknown): value is RpcHostUriResult;
+export declare class RpcHostUriBridge {
+    #private;
+    constructor(output: RpcHostUriOutput, router?: InternalUrlRouter);
+    getSchemes(): string[];
+    setSchemes(schemes: RpcHostUriSchemeDefinition[]): string[];
+    clear(message?: string): void;
+    handleResult(frame: RpcHostUriResult): boolean;
+    rejectAllPending(message: string): void;
+    requestRead(scheme: string, url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+    requestWrite(_scheme: string, url: InternalUrl, content: string, context?: WriteContext): Promise<void>;
+}
+export {};

package/dist/types/modes/shared/agent-wire/protocol.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared agent-wire protocol primitives for GJC bridge surfaces.
+ *
+ * This module is the transport-agnostic, versioned frame contract that the
+ * RPC mode and the (in-progress) `--mode bridge` wiring site both build on.
+ * It carries the SEMANTIC agent surface — events, responses, and UI/permission
+ * requests — never pixels. See `.gjc/specs/deep-interview-gjc-backend-bridge.md`
+ * and `.gjc/plans/ralplan/gjc-backend-bridge/pending-approval.md`.
+ */
+import type { AgentSessionEvent } from "../../../session/agent-session";
+/** Wire protocol version. Bump on breaking envelope/semantic changes. */
+export declare const BRIDGE_PROTOCOL_VERSION: 1;
+/** The discriminant of every `AgentSessionEvent` the agent can emit. */
+export type AgentSessionEventType = AgentSessionEvent["type"];
+/** Every agent-session event type, derived from the exhaustive registry. */
+export declare const AGENT_SESSION_EVENT_TYPES: readonly AgentSessionEventType[];
+/** Top-level frame categories carried over any bridge transport. */
+export type BridgeFrameType = "ready" | "event" | "response" | "ui_request" | "permission_request" | "host_tool_call" | "host_uri_request" | "reset" | "error";
+/**
+ * Universal frame envelope. Every frame on every transport carries these
+ * fields so clients can order (`seq`), resume (`seq` cursor), and correlate
+ * request/response pairs (`correlation_id`). `session_id` is present from v1
+ * even though v1 runs one session per process, so in-process multiplexing is
+ * an additive, non-breaking change later.
+ */
+export interface BridgeFrameEnvelope<TType extends BridgeFrameType = BridgeFrameType, TPayload = unknown> {
+    protocol_version: typeof BRIDGE_PROTOCOL_VERSION;
+    session_id: string;
+    /** Monotonic per-session sequence number, starting at 1. */
+    seq: number;
+    /** Unique id for this frame. */
+    frame_id: string;
+    /** Ties a request frame to its response frame, when applicable. */
+    correlation_id?: string;
+    type: TType;
+    payload: TPayload;
+}
+/** Payload carried by an `event` frame. */
+export interface BridgeEventPayload {
+    event_type: AgentSessionEventType;
+    event: AgentSessionEvent;
+}
+/** An `AgentSessionEvent` serialized into a versioned wire frame. */
+export type BridgeEventFrame = BridgeFrameEnvelope<"event", BridgeEventPayload>;

package/dist/types/modes/shared/agent-wire/responses.d.ts

@@ -0,0 +1,4 @@
+/** Shared RPC-compatible response helpers for agent-wire consumers. */
+import type { RpcCommand, RpcResponse } from "../../rpc/rpc-types";
+export declare function rpcSuccess<T extends RpcCommand["type"]>(id: string | undefined, command: T, data?: object | null): RpcResponse;
+export declare function rpcError(id: string | undefined, command: string, message: string): RpcResponse;

package/dist/types/modes/shared/agent-wire/scopes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Coarse bridge authorization scopes for RPC commands.
+ *
+ * The v1 bridge exposes a network-reachable control surface, so every
+ * `RpcCommand` must be assigned to one coarse scope before any REST handler can
+ * dispatch it. The registry is intentionally typed as `Record<RpcCommandType,
+ * BridgeCommandScope>` so adding a new RPC command without a scope is a compile
+ * failure.
+ */
+import type { RpcCommand } from "../../rpc/rpc-types";
+export type RpcCommandType = RpcCommand["type"];
+export type BridgeCommandScope = "prompt" | "control" | "bash" | "export" | "session" | "model" | "message:read" | "host_tools" | "host_uri" | "admin";
+export declare const BRIDGE_COMMAND_SCOPES: readonly BridgeCommandScope[];
+export declare const RPC_COMMAND_TYPES: readonly RpcCommandType[];
+export declare function isRpcCommandType(value: unknown): value is RpcCommandType;
+export declare const MANDATORY_FLOOR_COMMAND_SCOPES: readonly BridgeCommandScope[];
+export declare function scopeForRpcCommand(type: RpcCommandType): BridgeCommandScope;
+export declare function isRpcCommandAllowed(type: RpcCommandType, scopes: ReadonlySet<BridgeCommandScope>): boolean;

package/dist/types/modes/shared/agent-wire/ui-request-broker.d.ts

@@ -0,0 +1,42 @@
+export type UiRequestCancelReason = "timeout" | "abort" | "disconnect";
+export interface UiRequestCancelled {
+    status: "cancelled";
+    reason: UiRequestCancelReason;
+}
+export type UiRequestResolution<TResponse> = TResponse | UiRequestCancelled;
+export type UiBrokerResponseResult = {
+    status: "accepted";
+} | {
+    status: "rejected";
+    code: "not_controller" | "already_resolved" | "unknown_request";
+};
+export interface UiRequestBrokerOptions<TRequest> {
+    emitRequest: (correlationId: string, request: TRequest) => void;
+}
+export interface UiRequestOptions {
+    correlationId?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Broker for one active session. v1 supports one controller token at a time;
+ * other clients may observe frames but cannot answer correlated requests.
+ */
+export declare class UiRequestBroker<TRequest, TResponse> {
+    #private;
+    constructor(options: UiRequestBrokerOptions<TRequest>);
+    get ownerToken(): string | undefined;
+    get pendingCount(): number;
+    claimController(ownerToken?: string): {
+        status: "claimed";
+        ownerToken: string;
+    } | {
+        status: "busy";
+    };
+    releaseController(ownerToken: string): boolean;
+    request(request: TRequest, options?: UiRequestOptions): Promise<UiRequestResolution<TResponse>>;
+    respond(correlationId: string, ownerToken: string, response: TResponse): UiBrokerResponseResult;
+    cancelAll(reason: UiRequestCancelReason): void;
+    cancel(correlationId: string, reason: UiRequestCancelReason): boolean;
+    disconnectController(ownerToken: string): boolean;
+}

package/dist/types/modes/shared/agent-wire/ui-result.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Typed UI/manipulation result semantics for bridge-capability handling.
+ *
+ * `unsupported` is distinct from both a real value and user cancellation. This
+ * prevents local-only or undeclared `ExtensionUIContext` surfaces from becoming
+ * silent no-ops that look like user intent.
+ */
+export interface BridgeUiValue<TValue> {
+    status: "value";
+    value: TValue;
+}
+export interface BridgeUiCancelled {
+    status: "cancelled";
+    reason?: "user" | "timeout" | "abort" | "disconnect";
+}
+export interface BridgeUiUnsupported {
+    status: "unsupported";
+    capability: string;
+    reason: string;
+}
+export type BridgeUiResult<TValue> = BridgeUiValue<TValue> | BridgeUiCancelled | BridgeUiUnsupported;
+export declare function uiValue<TValue>(value: TValue): BridgeUiValue<TValue>;
+export declare function uiCancelled(reason?: BridgeUiCancelled["reason"]): BridgeUiCancelled;
+export declare function uiUnsupported(capability: string, reason: string): BridgeUiUnsupported;
+export declare function isUiUnsupported<TValue>(result: BridgeUiResult<TValue>): result is BridgeUiUnsupported;
+export declare function isUiCancelled<TValue>(result: BridgeUiResult<TValue>): result is BridgeUiCancelled;
+export declare function isUiValue<TValue>(result: BridgeUiResult<TValue>): result is BridgeUiValue<TValue>;

package/dist/types/modes/types.d.ts

@@ -228,6 +228,7 @@ export interface InteractiveModeContext {
     showHookConfirm(title: string, message: string): Promise<boolean>;
     showDebugSelector(): void;
     showSessionObserver(): void;
+    showJobsOverlay(): void;
     resetObserverRegistry(): void;
     handleCtrlC(): void;
     handleCtrlD(): void;

package/dist/types/sdk.d.ts

@@ -93,6 +93,8 @@ export interface CreateAgentSessionOptions {
     requireYieldTool?: boolean;
     /** Task recursion depth (for subagent sessions). Default: 0 */
     taskDepth?: number;
+    /** Current role-agent type/name for nested task sessions. */
+    currentAgentType?: string;
     /** Parent Hindsight state to alias for subagent memory tools. */
     parentHindsightSessionState?: HindsightSessionState;
     /** Pre-allocated agent identity for IRC routing. Default: "0-Main" for top-level, parentTaskPrefix-derived for sub. */

package/dist/types/session/agent-session.d.ts

@@ -133,7 +133,7 @@ export type AgentSessionEvent = AgentEvent | {
 };
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
-export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
+export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime" | "metadata">;
 export interface AsyncJobSnapshot {
     running: AsyncJobSnapshotItem[];
     recent: AsyncJobSnapshotItem[];
@@ -358,6 +358,7 @@ export declare class AgentSession {
      *  Does NOT push to the agent's steering/followUp queue — that happens
      *  separately inside `sendCustomMessage`. */
     enqueueCustomMessageDisplay(text: string, mode: "steer" | "followUp"): string;
+    getAgentId(): string | undefined;
     getAsyncJobSnapshot(options?: {
         recentLimit?: number;
     }): AsyncJobSnapshot | null;
@@ -577,6 +578,10 @@ export declare class AgentSession {
     };
     /** Number of pending messages (includes steering, follow-up, and next-turn messages) */
     get queuedMessageCount(): number;
+    /** Whether the agent has queued steering messages that a `user_interrupt`
+     *  abort would resume into (steer-on-interrupt). Drives the Esc-on-steer UX:
+     *  the first Esc consumes the steer and auto-continues, a second Esc aborts. */
+    get hasQueuedSteering(): boolean;
     /** Get pending messages (read-only). Returns the public text-only view;
      *  internal `{text, tag?}` records are mapped to `.text` so callers
      *  (`updatePendingMessagesDisplay`, `restoreQueuedMessagesToEditor`) see
@@ -606,6 +611,11 @@ export declare class AgentSession {
         goalReason?: "interrupted" | "internal";
         timeoutMs?: number;
         cause?: "user_interrupt" | "new_session" | "session_switch" | "compaction" | "handoff" | "tool_abort" | "internal";
+        /** Suppress the "Operation aborted" line on the resulting aborted message
+         *  by stamping `SILENT_ABORT_MARKER`. Used when Esc consumes a queued steer
+         *  and resumes via steer-on-interrupt, so the interrupt reads as a quiet
+         *  hand-off rather than a failure. */
+        silent?: boolean;
     }): Promise<void>;
     /**
      * Start a new session, optionally with initial messages and parent tracking.

package/dist/types/skill-state/workflow-state-contract.d.ts

@@ -1,7 +1,6 @@
 import { type CanonicalGjcWorkflowSkill } from "./active-state";
+export { WORKFLOW_STATE_RECEIPT_FRESH_MS, WORKFLOW_STATE_RECEIPT_VERSION, WORKFLOW_STATE_VERSION, } from "./workflow-state-version";
 export type { CanonicalGjcWorkflowSkill };
-export declare const WORKFLOW_STATE_RECEIPT_VERSION = 1;
-export declare const WORKFLOW_STATE_RECEIPT_FRESH_MS: number;
 export type WorkflowStateMutationOwner = "gjc-state-cli" | "gjc-runtime" | "gjc-hook";
 export type WorkflowStateReceiptStatus = "fresh" | "stale";
 export interface WorkflowStateContentChecksum {

package/dist/types/skill-state/workflow-state-version.d.ts

@@ -0,0 +1,3 @@
+export declare const WORKFLOW_STATE_RECEIPT_VERSION = 1;
+export declare const WORKFLOW_STATE_VERSION = 2;
+export declare const WORKFLOW_STATE_RECEIPT_FRESH_MS: number;

package/dist/types/task/id.d.ts

@@ -0,0 +1,7 @@
+export declare const TASK_ID_PATTERN: RegExp;
+export declare const TASK_ID_DESCRIPTION = "filesystem-safe identifier matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,47}$";
+export declare function isValidTaskId(id: string): boolean;
+export declare function getTaskIdValidationError(id: unknown): string | undefined;
+export declare function validateTaskId(id: string): string;
+export declare function isValidAllocatedTaskId(id: string): boolean;
+export declare function validateAllocatedTaskId(id: string): string;

package/dist/types/task/index.d.ts

@@ -1,4 +1,5 @@
 import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
+import type { Model } from "@gajae-code/ai";
 import type { ToolSession } from "..";
 import type { Theme } from "../modes/theme/theme";
 import { type TaskToolDetails, type TaskToolSchemaInstance } from "./types";
@@ -7,9 +8,13 @@ import { renderResult, renderCall as renderTaskCall } from "./render";
 export { loadBundledAgents as BUNDLED_AGENTS } from "./agents";
 export { discoverCommands, expandCommand, getCommand } from "./commands";
 export { discoverAgents, getAgent } from "./discovery";
+export { isValidAllocatedTaskId, isValidTaskId, TASK_ID_DESCRIPTION, TASK_ID_PATTERN, validateAllocatedTaskId, validateTaskId, } from "./id";
 export { AgentOutputManager } from "./output-manager";
+export type { TaskResultReceipt } from "./receipt";
+export { assertNoRawTaskFields, buildTaskReceipt, buildTaskRoi, buildTaskRoiSummary, findRawTaskLeakKeys, sanitizeTaskToolDetails, } from "./receipt";
 export type { AgentDefinition, AgentProgress, SingleResult, SubagentLifecyclePayload, SubagentProgressPayload, TaskParams, TaskToolDetails, } from "./types";
 export { TASK_SUBAGENT_EVENT_CHANNEL, TASK_SUBAGENT_LIFECYCLE_CHANNEL, TASK_SUBAGENT_PROGRESS_CHANNEL, taskSchema, } from "./types";
+export declare function resolveForkContextMaxTokens(configured: number, model: Model | undefined): number;
 /**
  * Task tool - Delegate tasks to specialized agents.
  *

package/dist/types/task/receipt.d.ts

@@ -0,0 +1,85 @@
+import type { SingleResult, TaskToolDetails } from "./types";
+export interface TaskRoi {
+    tokens: number;
+    contextTokens?: number;
+    clonedTokens?: number;
+    costTotal?: number;
+    outputBytes?: number;
+    outputLines?: number;
+    producedChanges: boolean;
+    materialContribution: boolean;
+    lowRoi: boolean;
+}
+export interface TaskResultReceipt {
+    index: number;
+    id: string;
+    agent: string;
+    agentSource: SingleResult["agentSource"];
+    task: string;
+    assignment?: string;
+    description?: string;
+    status: "completed" | "failed" | "aborted" | "merge_failed" | "paused";
+    exitCode: number;
+    aborted?: boolean;
+    paused?: boolean;
+    truncated: boolean;
+    durationMs: number;
+    tokens: number;
+    contextTokens?: number;
+    contextWindow?: number;
+    modelOverride?: string | string[];
+    usage?: SingleResult["usage"];
+    cost?: number;
+    branchName?: string;
+    retryFailure?: {
+        attempt: number;
+        errorSummary: string;
+    };
+    errorSummary?: string;
+    abortSummary?: string;
+    preview: string;
+    previewTruncated: boolean;
+    outputRef?: {
+        uri: string;
+        sizeBytes: number;
+        lineCount: number;
+        sha256?: string;
+    };
+    outputUnavailable?: boolean;
+    review?: {
+        overallCorrectness?: string;
+        findingCount: number;
+        findings?: Array<{
+            severity?: string;
+            summary: string;
+        }>;
+    };
+    extractedToolCounts?: Record<string, number>;
+    forkContext?: SingleResult["forkContext"];
+    roi?: TaskRoi;
+}
+/**
+ * Heuristic task ROI signal built only from receipt-safe accounting fields.
+ * Advisory only: these flags never change task success/failure semantics.
+ */
+export declare function buildTaskRoi(raw: SingleResult): TaskRoi;
+export declare function buildTaskRoiSummary(receipts: readonly TaskResultReceipt[]): TaskToolDetails["roiSummary"];
+export declare function buildTaskReceipt(raw: SingleResult): TaskResultReceipt;
+/**
+ * Raw, pre-sanitization task details: the internal shape produced during task
+ * execution, where `results` are full `SingleResult` objects. The public
+ * `TaskToolDetails` exposes only receipts.
+ */
+export interface RawTaskToolDetails {
+    projectAgentsDir: string | null;
+    results: SingleResult[];
+    totalDurationMs: number;
+    usage?: TaskToolDetails["usage"];
+    async?: TaskToolDetails["async"];
+    forkContextClonedTokens?: number;
+    roiSummary?: TaskToolDetails["roiSummary"];
+}
+/** Central converter from raw task details to receipt-only public details. */
+export declare function sanitizeTaskToolDetails(raw: RawTaskToolDetails): TaskToolDetails;
+export declare function findRawTaskLeakKeys(value: unknown): string[];
+export declare function assertNoRawTaskFields(value: unknown, surface: string): void;

package/dist/types/task/spawn-gate.d.ts

@@ -0,0 +1,38 @@
+/** The hard, locked batch threshold enforced by the runtime gate. */
+export declare const DEFAULT_SPAWN_THRESHOLD = 4;
+/** The justification a large batch or reviewer-spawned explorer must supply to pass the hard gate. */
+export interface SpawnPlanReceipt {
+    whyParallel: string;
+    whyNotLocal: string;
+    independence: string;
+    expectedReceiptShape: string;
+    maxInlineTokens: number;
+}
+export interface SpawnGateRequest {
+    /** Number of children the batch wants to spawn. */
+    childCount: number;
+    /** The spawn-plan receipt, when provided. */
+    plan?: SpawnPlanReceipt;
+}
+export interface ReviewerExploreGateRequest {
+    /** Agent type/name doing the spawning, when known. */
+    spawningAgentType?: string | null;
+    /** Target agent type/name requested by the task call. */
+    targetAgent: string;
+    /** The spawn-plan receipt, when provided. */
+    plan?: SpawnPlanReceipt;
+}
+export type SpawnGateOutcome = "allowed" | "rejected";
+export interface SpawnGateDecision {
+    outcome: SpawnGateOutcome;
+    /** Human-readable reason, suitable for a blocked-result message. */
+    reason: string;
+    /** Whether a plan was required for this request. */
+    planRequired: boolean;
+    /** Missing plan field names when rejected for an incomplete plan. */
+    missingFields: readonly string[];
+}
+export declare function findMissingPlanFields(plan: SpawnPlanReceipt | undefined): string[];
+export declare function decide(childCount: number, threshold: number, plan: SpawnPlanReceipt | undefined): SpawnGateDecision;
+export declare function evaluateSpawnGate(request: SpawnGateRequest): SpawnGateDecision;
+export declare function evaluateReviewerExploreGate(request: ReviewerExploreGateRequest): SpawnGateDecision;