@sayknow-cli/coding-agent 0.4.1 → 0.4.3

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/shared/agent-wire/unattended-action-policy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Unattended action taxonomy + classifier (#319).
+ *
+ * Maps coarse command scopes and concrete bash commands onto the v1 action
+ * taxonomy so the controller can authorize (default-deny) BEFORE any side effect.
+ *
+ * The classifier is deliberately FAIL-CLOSED for shell evasion:
+ *  - nested execution via `$(...)`, backticks, and `<(...)` / `>(...)` is
+ *    extracted and classified recursively, so a destructive command hidden in a
+ *    substitution cannot masquerade as the harmless outer command;
+ *  - statements are split on newlines and `; && || | &`, so a second
+ *    (destructive) command on another line is classified too;
+ *  - leading environment assignments and wrappers (`sudo`, `env`, `command`,
+ *    `xargs`, …) are stripped/followed to the effective command;
+ *  - anything that is not provably read-only escalates to at least
+ *    `bash.mutating`, and clearly destructive forms escalate further, so an
+ *    undeclared destructive action is denied rather than silently allowed.
+ */
+import type { RpcUnattendedActionClass } from "../../rpc/rpc-types";
+import type { BridgeCommandScope } from "./scopes";
+/** Coarse command scope -> `command.<scope>` action class. */
+export declare function actionClassForScope(scope: BridgeCommandScope): RpcUnattendedActionClass;
+/** Runtime list of every v1 action class — membership-validation source for negotiate (#319). */
+export declare const RPC_UNATTENDED_ACTION_CLASSES: readonly RpcUnattendedActionClass[];
+/**
+ * Classify a (possibly compound / nested) bash command into the most severe
+ * action class across all statements and nested substitutions. Fail-closed.
+ */
+export declare function classifyBashAction(command: string): RpcUnattendedActionClass;

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

@@ -0,0 +1,68 @@
+import type { RpcBudgetExceeded, RpcWorkflowGateKind, RpcWorkflowStage } from "../../rpc/rpc-types";
+export declare const AUDIT_SCHEMA_VERSION = 1;
+export declare const AUDIT_CATEGORY = "unattended_lifecycle";
+export type AuditOutcome = "accepted" | "rejected" | "denied" | "exceeded" | "aborted" | "info";
+export interface AuditRecord {
+    event_id: string;
+    schema_version: number;
+    category: typeof AUDIT_CATEGORY;
+    run_id: string;
+    session_id?: string;
+    actor?: string;
+    timestamp: string;
+    event: string;
+    outcome: AuditOutcome;
+    dedupe_key: string;
+    gate_id?: string;
+    stage?: RpcWorkflowStage;
+    kind?: RpcWorkflowGateKind;
+    scope?: string;
+    action?: string;
+    budget?: RpcBudgetExceeded;
+    /** Full answer (omitted when redaction is enabled). */
+    answer?: unknown;
+    answer_hash?: string;
+    error?: unknown;
+}
+export interface AuditQuery {
+    run_id?: string;
+    session_id?: string;
+    actor?: string;
+    gate_id?: string;
+    outcome?: AuditOutcome;
+    event?: string;
+    since?: string;
+    until?: string;
+}
+export interface AuditLogOptions {
+    /** When true, gate answers are stored as hash + summary only. */
+    redactAnswers?: boolean;
+    /** Injectable id/clock for deterministic tests. */
+    now?(): number;
+    nextId?(): string;
+}
+export declare function defaultAuditPath(runId: string, root?: string, skcSessionId?: string): string;
+/** Append-only audit log writer + reader for one unattended run. */
+export declare class UnattendedAuditLog {
+    private readonly filePath;
+    private readonly seen;
+    private readonly now;
+    private readonly nextId;
+    private readonly redactAnswers;
+    constructor(filePath: string, options?: AuditLogOptions);
+    /**
+     * Append a record. Returns the written record, or `null` if a record with the
+     * same dedupe_key was already written (exactly-once).
+     */
+    record(input: Omit<AuditRecord, "event_id" | "schema_version" | "category" | "timestamp">): AuditRecord | null;
+    /** Append one line and fsync it for crash durability. */
+    private appendDurable;
+    /** Read every record (fail-closed: a corrupt line throws rather than silently dropping). */
+    readAll(): AuditRecord[];
+    /** Query records with filters (run/session/actor/gate/outcome/event + time window). */
+    query(filter?: AuditQuery): AuditRecord[];
+    /** Export the full trail as an array (for `get_unattended_audit`). */
+    export(filter?: AuditQuery): AuditRecord[];
+}
+/** SHA-256 of the canonical JSON of an answer (matches the gate broker's hash). */
+export declare function answerHash(answer: unknown): string;

package/dist/types/modes/shared/agent-wire/unattended-run-controller.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Unattended run controller (#318).
+ *
+ * The single required owner of negotiated unattended state. Entering unattended
+ * mode is fail-closed: a controller can only be created via {@link
+ * UnattendedRunController.negotiate}, which rejects a missing/partial budget, an
+ * invalid declaration, or a provider that cannot account for tokens/cost.
+ *
+ * The controller owns budget accounting across metrics and phases. Scope/action
+ * authorization (#319) and the durable audit trail (#320) layer onto the same
+ * controller; this slice wires the budget floor and abort coordination.
+ *
+ * Attended mode never constructs a controller, so by construction the attended
+ * path is unaffected by everything here.
+ */
+import type { RpcActionDenied, RpcBudgetExceeded, RpcBudgetMetric, RpcScopeDenied, RpcUnattendedActionClass, RpcUnattendedBudget, RpcUnattendedRefusalCode } from "../../rpc/rpc-types";
+import type { BridgeCommandScope } from "./scopes";
+import { actionClassForScope } from "./unattended-action-policy";
+/** Coordinated abort surfaces invoked exactly once on a budget breach / abort. */
+export interface UnattendedAbortHooks {
+    abortModelStream?(): void | Promise<void>;
+    abortBash?(): void | Promise<void>;
+    cancelHostTools?(reason: string): void | Promise<void>;
+    cancelHostUris?(reason: string): void | Promise<void>;
+    stopWorkflow?(reason: string): void | Promise<void>;
+}
+export type UnattendedAuditEvent = {
+    event: "unattended_negotiated";
+    run_id: string;
+    actor: string;
+} | {
+    event: "budget_exceeded";
+    payload: RpcBudgetExceeded;
+} | {
+    event: "unattended_aborted";
+    run_id: string;
+    reason: string;
+} | {
+    event: "unattended_abort_settled";
+    run_id: string;
+    status: "aborted" | "abort_failed";
+    failures: number;
+} | {
+    event: "scope_denied";
+    payload: RpcScopeDenied;
+} | {
+    event: "action_denied";
+    payload: RpcActionDenied;
+};
+export interface NegotiateContext {
+    runId: string;
+    sessionId?: string;
+    audit?(event: UnattendedAuditEvent): void;
+    abortHooks?: UnattendedAbortHooks;
+    /**
+     * Whether the active provider can report token usage and cost. Unattended
+     * mode rejects providers without this accounting up front (fail-closed).
+     */
+    providerSupportsTokenCostMetrics?: boolean;
+    /** Injectable clock for deterministic tests. Defaults to Date.now. */
+    now?(): number;
+}
+export declare class UnattendedNegotiationError extends Error {
+    readonly code: RpcUnattendedRefusalCode;
+    constructor(code: RpcUnattendedRefusalCode, message: string);
+}
+export declare class UnattendedBudgetExceededError extends Error {
+    readonly payload: RpcBudgetExceeded;
+    constructor(payload: RpcBudgetExceeded);
+}
+/** Thrown when a provider/tool reports a non-finite usage value (fail-closed). */
+export declare class UnattendedAccountingError extends Error {
+    readonly metric: RpcBudgetMetric;
+    readonly phase: string;
+    constructor(metric: RpcBudgetMetric, phase: string, value: unknown);
+}
+/** Thrown when a command's coarse scope is outside the declared allowlist (#319). */
+export declare class ScopeDeniedError extends Error {
+    readonly payload: RpcScopeDenied;
+    constructor(payload: RpcScopeDenied);
+}
+/** Thrown when an action class is outside the declared allowlist (default-deny, #319). */
+export declare class ActionDeniedError extends Error {
+    readonly payload: RpcActionDenied;
+    constructor(payload: RpcActionDenied);
+}
+interface Usage {
+    tokens: number;
+    toolCalls: number;
+    costUsd: number;
+}
+export declare class UnattendedRunController {
+    readonly runId: string;
+    readonly sessionId?: string;
+    readonly actor: string;
+    readonly budget: RpcUnattendedBudget;
+    readonly scopes: ReadonlySet<string>;
+    readonly actionAllowlist: ReadonlySet<string>;
+    private readonly usage;
+    private readonly startedAt;
+    private readonly now;
+    private readonly audit?;
+    private readonly abortHooks;
+    private aborted;
+    private abortPromise?;
+    private constructor();
+    /** Fail-closed entry: validate the declaration + budget, or throw. */
+    static negotiate(declaration: unknown, ctx: NegotiateContext): UnattendedRunController;
+    get isAborted(): boolean;
+    usageSnapshot(): Readonly<Usage> & {
+        wallTimeMs: number;
+    };
+    remainingWallTimeMs(): number;
+    /**
+     * Authorize a command's coarse scope against the declared allowlist. Throws
+     * ScopeDeniedError (pre-side-effect) when the scope was not declared.
+     */
+    authorizeScope(scope: BridgeCommandScope, command?: string): void;
+    /**
+     * Authorize an action class against the declared allowlist. Default-deny: any
+     * class not explicitly declared is rejected with ActionDeniedError before the
+     * side effect runs.
+     */
+    authorizeAction(action: RpcUnattendedActionClass, command?: string): void;
+    /**
+     * Classify a bash command and authorize the resulting action class BEFORE the
+     * command is executed. Returns the classified action class on success.
+     */
+    authorizeBash(command: string): RpcUnattendedActionClass;
+    /** Convenience: map a coarse scope to its `command.<scope>` action class. */
+    static actionClassForScope: typeof actionClassForScope;
+    /** Pre-turn estimate: refuse to start a turn that would obviously breach. */
+    preTurnEstimate(estimate: {
+        tokens?: number;
+        costUsd?: number;
+    }): void;
+    /** Reserve one tool-call unit BEFORE any side effect; breach if it would exceed. */
+    preflightToolCall(phase?: string): void;
+    /** Post-turn reconciliation of actual token usage. Fails closed on non-finite. */
+    recordTokens(tokens: number, phase?: string): void;
+    recordCost(costUsd: number, phase?: string): void;
+    /** Combined post-turn reconciliation. */
+    reconcile(actual: {
+        tokens?: number;
+        costUsd?: number;
+    }, phase?: string): void;
+    /** Wall-time check; call before/inside long operations. */
+    checkWallTime(phase?: string): void;
+    private breach;
+    /**
+     * Idempotent abort: runs every abort hook at most once. Safe to call from the
+     * synchronous breach path (which does not await) and from callers that do; both
+     * share a single abort promise so hook completion can be awaited deterministically.
+     */
+    abort(reason: string): Promise<void>;
+    /** Returns the in-flight/settled abort completion once aborting has begun. */
+    get abortCompletion(): Promise<void> | undefined;
+    private fireAbort;
+    /**
+     * Invoke every configured abort hook exactly once with per-hook isolation, so a
+     * failing hook never prevents the other cancellation surfaces from running.
+     * Returns the number of hooks that rejected.
+     */
+    private runAbortHooks;
+}
+export {};

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

@@ -0,0 +1,127 @@
+/**
+ * Session-level unattended control plane (#323 / G011 emission side).
+ *
+ * Bridges the gate EMISSION side (skill runtimes / ask tool emitting gates) to
+ * the gate ANSWER side (the external agent's `workflow_gate_response` over RPC):
+ *
+ *  - `emitGate(input)` opens a gate on the durable broker, emits the gate frame
+ *    to the transport, and returns a promise that resolves with the agent's
+ *    answer once it arrives.
+ *  - `resolveGate(response)` (called from RPC dispatch) validates + resolves the
+ *    gate on the broker; the broker's `advance` hook resolves the pending
+ *    `emitGate` promise with the answer.
+ *
+ * Also implements the dispatch-facing {@link RpcUnattendedControlPlane} so the
+ * RPC server can route `negotiate_unattended` + `workflow_gate_response` here.
+ */
+import type { Model } from "@sayknow-cli/ai";
+import type { AskSelectedAckOutcome } from "../../../tools";
+import type { RpcCommand, RpcUnattendedAccepted, RpcUnattendedDeclaration, RpcWorkflowGate, RpcWorkflowGateResolution, RpcWorkflowGateResponse } from "../../rpc/rpc-types";
+import type { RpcUnattendedControlPlane } from "./command-dispatch";
+import { type UnattendedAbortHooks, type UnattendedAuditEvent, UnattendedRunController } from "./unattended-run-controller";
+import { type GateStore, type OpenGateInput } from "./workflow-gate-broker";
+export interface WorkflowGateTerminalController {
+    completeGateInteractions(gateId: string): void | Promise<void>;
+    cancelGateInteractions(gateId: string, reason: string): void | Promise<void>;
+}
+export interface WorkflowGateTerminalEvent {
+    gateId: string;
+    kind: "accepted" | "cancelled";
+    origin?: "rpc" | "bridge" | "other" | "telegram_notification";
+    reason?: string;
+}
+export interface NotificationGateResolutionOptions {
+    interactionActionId: string;
+    replyReceiptId: string;
+    answerJson: string;
+    idempotencyKey?: string;
+    requestSelectedAck(input: {
+        replyReceiptId: string;
+        actionId: string;
+        commitKey: string;
+        daemonDeadlineAt: number;
+        hostTimeoutMs: number;
+    }): Promise<AskSelectedAckOutcome>;
+    resolveClaim(): void;
+    closeClaimInvalid(reason: string): void;
+}
+export interface AskSelectedAckRecoveryParticipant {
+    requestRecoveredAskSelectedAck(input: {
+        sessionId: string;
+        actionId: string;
+        commitKey: string;
+        deadlineAt: number;
+        hostTimeoutMs: number;
+    }): Promise<AskSelectedAckOutcome>;
+}
+/**
+ * Derive an explicit `providerSupportsTokenCostMetrics` capability from the
+ * active model so unattended negotiation fails closed when token/cost usage
+ * cannot be accounted for (#606). Callers that omit a model — or whose model is
+ * configured to suppress streaming usage (`compat.supportsUsageInStreaming:
+ * false`) — get `false`, which the controller refuses with
+ * `unsupported_budget_metric`.
+ */
+export declare function modelSupportsTokenCostMetrics(model: Model | undefined): boolean;
+/** Minimal surface a skill runtime / ask tool uses to emit a gate and await its answer. */
+export interface WorkflowGateEmitter {
+    /** True only when unattended mode has been negotiated. */
+    isUnattended(): boolean;
+    /** Open + emit a gate; resolves with the agent's answer (from workflow_gate_response). */
+    emitGate(input: OpenGateInput): Promise<unknown>;
+    /**
+     * Optional bridge surface (present on {@link UnattendedSessionControlPlane}) that
+     * lets an in-process extension observe emitted gates and answer them — used by
+     * the notifications SDK to resolve a real ask gate from a remote reply.
+     */
+    onGateEmitted?(listener: (gate: RpcWorkflowGate) => void): () => void;
+    resolveGate?(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution>;
+    resolveGateFromNotification?(response: RpcWorkflowGateResponse, options: NotificationGateResolutionOptions): Promise<RpcWorkflowGateResolution>;
+    registerGateTerminalController?(controller: WorkflowGateTerminalController): () => void;
+    listPendingGates?(): RpcWorkflowGate[];
+    setAckRecoveryParticipant?(participant: AskSelectedAckRecoveryParticipant | null): void;
+}
+export interface UnattendedSessionOptions {
+    runId: string;
+    sessionId?: string;
+    /** Emit a workflow_gate frame to the transport so the agent receives it. */
+    emitFrame: (gate: RpcWorkflowGate) => void;
+    /** Durable gate store; defaults to in-memory. */
+    store?: GateStore;
+    /** Audit sink for controller + gate events. */
+    audit?: (event: UnattendedAuditEvent | {
+        event: string;
+        [k: string]: unknown;
+    }) => void;
+    abortHooks?: UnattendedAbortHooks;
+    /** Whether the active provider reports token/cost usage (fail-closed when false/omitted). */
+    providerSupportsTokenCostMetrics?: boolean;
+    /** Snapshot live cumulative usage after a dispatch or turn, for budget reconciliation. */
+    getUsageSnapshot?: () => {
+        tokens?: number;
+        costUsd?: number;
+    };
+}
+export declare class UnattendedSessionControlPlane implements RpcUnattendedControlPlane, WorkflowGateEmitter {
+    #private;
+    private readonly opts;
+    constructor(opts: UnattendedSessionOptions);
+    isUnattended(): boolean;
+    /** Observe every emitted gate (e.g. so an extension can map an ask to its gate_id). */
+    onGateEmitted(listener: (gate: RpcWorkflowGate) => void): () => void;
+    get controller(): UnattendedRunController | undefined;
+    registerGateTerminalController(controller: WorkflowGateTerminalController): () => void;
+    setAckRecoveryParticipant(participant: AskSelectedAckRecoveryParticipant | null): void;
+    negotiate(declaration: RpcUnattendedDeclaration): RpcUnattendedAccepted;
+    preflightCommand(command: RpcCommand): void;
+    reconcileUsage(phase?: string): void;
+    resolveGate(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution>;
+    resolveGateFromNotification(response: RpcWorkflowGateResponse, options: NotificationGateResolutionOptions): Promise<RpcWorkflowGateResolution>;
+    startRecoveryOnce(options?: {
+        participantGraceMs?: number;
+    }): Promise<void>;
+    dispose(reason?: string): void;
+    listPendingGates(): import("../../rpc/rpc-types").RpcWorkflowGate[];
+    emitGate(input: OpenGateInput): Promise<unknown>;
+    recover(): Promise<void>;
+}