@gajae-code/coding-agent 0.3.1 → 0.4.0

package/dist/types/extensibility/gjc-plugins/loader.d.ts

@@ -0,0 +1,3 @@
+import { type LoadedGjcPlugin } from "./types";
+export declare function loadGjcPlugin(root: string): Promise<LoadedGjcPlugin>;
+export declare function loadGjcPlugins(roots: readonly string[]): Promise<LoadedGjcPlugin[]>;

package/dist/types/extensibility/gjc-plugins/paths.d.ts

@@ -0,0 +1,8 @@
+export declare function gjcPluginUserRoot(): string;
+export declare function gjcPluginProjectRoot(cwd: string): string;
+export declare function rootContainsGjcManifest(dir: string): Promise<boolean>;
+export declare function discoverGjcPluginRoots({ cwd }: {
+    cwd: string;
+    home?: string;
+}): Promise<string[]>;
+export declare function resolveWithinRoot(root: string, rel: string): string;

package/dist/types/extensibility/gjc-plugins/schema.d.ts

@@ -0,0 +1,3 @@
+import { type GjcPluginManifest, type SubskillFrontmatter } from "./types";
+export declare function parseManifest(raw: unknown, manifestPath: string): GjcPluginManifest;
+export declare function parseSubskillFrontmatter(fm: Record<string, unknown>, filePath: string): SubskillFrontmatter;

package/dist/types/extensibility/gjc-plugins/state.d.ts

@@ -0,0 +1,9 @@
+import type { ActiveSubskillEntry } from "../../skill-state/active-state";
+import type { LoadedSubskillActivation } from "./types";
+export declare function toActiveSubskillEntry(activation: LoadedSubskillActivation): ActiveSubskillEntry;
+export declare function readActiveSubskillsForParent(input: {
+    cwd: string;
+    sessionId?: string;
+    parent: string;
+    phase: string;
+}): Promise<ActiveSubskillEntry[]>;

package/dist/types/extensibility/gjc-plugins/tools.d.ts

@@ -0,0 +1,8 @@
+import type { CustomTool } from "../custom-tools/types";
+export declare function loadActiveSubskillTools(input: {
+    cwd: string;
+    sessionId?: string;
+    parent: string;
+    phase: string;
+    reservedToolNames?: string[];
+}): Promise<CustomTool[]>;

package/dist/types/extensibility/gjc-plugins/types.d.ts

@@ -0,0 +1,64 @@
+import type { CanonicalGjcWorkflowSkill } from "../../skill-state/active-state";
+export declare const GJC_PLUGIN_MANIFEST_FILENAME = "gajae-plugin.json";
+export declare const GJC_PLUGIN_KIND = "gajae-code-plugin";
+export declare const GJC_SUBSKILL_PARENT_SKILLS: readonly ["deep-interview", "ralplan", "ultragoal", "team"];
+export type GjcSubskillParentSkill = CanonicalGjcWorkflowSkill;
+export declare const GJC_SUBSKILL_PARENT_AGENTS: readonly ["executor", "architect", "planner", "critic"];
+export type GjcSubskillParentAgent = (typeof GJC_SUBSKILL_PARENT_AGENTS)[number];
+export type GjcSubskillParent = GjcSubskillParentSkill | GjcSubskillParentAgent;
+export declare const GJC_AGENT_SUBSKILL_PHASES: Record<GjcSubskillParentAgent, string[]>;
+export interface GjcPluginManifest {
+    name: string;
+    version: string;
+    kind: "gajae-code-plugin";
+    subskills: string[];
+    tools: string[];
+}
+export interface SubskillFrontmatter {
+    name: string;
+    binds_to: string;
+    phase: string;
+    activation_arg: string;
+    description: string;
+}
+export interface LoadedSubskillBinding {
+    plugin: string;
+    subskillName: string;
+    parent: string;
+    bindsTo: string;
+    phase: string;
+    activationArg: string;
+    description: string;
+    filePath: string;
+    body: string;
+    toolPaths: string[];
+}
+export interface LoadedSubskillActivation {
+    activationArg: string;
+    plugin: string;
+    subskillName: string;
+    parent: string;
+    bindsTo: string;
+    phase: string;
+    filePath: string;
+    toolPaths: string[];
+}
+export interface PhaseScopedToolBinding {
+    plugin: string;
+    parent: string;
+    phase: string;
+    toolPath: string;
+}
+export interface LoadedGjcPlugin {
+    name: string;
+    version: string;
+    root: string;
+    manifestPath: string;
+    bindings: LoadedSubskillBinding[];
+    toolBindings: PhaseScopedToolBinding[];
+}
+export type GjcPluginLoadErrorCode = "forbidden_surface" | "invalid_manifest" | "invalid_frontmatter" | "invalid_parent" | "invalid_phase" | "duplicate_arg" | "duplicate_parent_phase" | "missing_file" | "invalid_kind";
+export declare class GjcPluginLoadError extends Error {
+    readonly code: GjcPluginLoadErrorCode;
+    constructor(code: GjcPluginLoadErrorCode, message: string, options?: ErrorOptions);
+}

package/dist/types/extensibility/gjc-plugins/validation.d.ts

@@ -0,0 +1,4 @@
+import { type LoadedSubskillBinding, type SubskillFrontmatter } from "./types";
+export declare function validateBinding(fm: SubskillFrontmatter): void;
+export declare function buildParentArgMap(bindings: readonly LoadedSubskillBinding[]): Map<string, Map<string, LoadedSubskillBinding>>;
+export declare function buildParentPhaseSet(bindings: readonly LoadedSubskillBinding[]): Set<string>;

package/dist/types/extensibility/skills.d.ts

@@ -1,6 +1,7 @@
 import type { SourceMeta } from "../capability/types";
 import type { SkillsSettings } from "../config/settings";
 import type { SkillPromptDetails } from "../session/messages";
+import type { LoadedSubskillActivation } from "./gjc-plugins";
 export interface Skill {
     name: string;
     description: string;
@@ -55,6 +56,13 @@ export interface BuiltSkillPromptMessage {
     message: string;
     details: SkillPromptDetails;
 }
+export interface BuildSkillPromptMessageContext {
+    subskillActivation?: LoadedSubskillActivation;
+    subskillActivationSet?: LoadedSubskillActivation[];
+    currentPhase?: string;
+    cwd?: string;
+    sessionId?: string;
+}
 export declare function getSkillSlashCommandName(skill: Pick<Skill, "name">): string;
 export declare function isNamespacedSkillSlashCommandName(commandName: string): boolean;
 export declare function getSkillSlashCommandNames(skill: Pick<Skill, "name">): string[];
@@ -71,4 +79,4 @@ export interface ParsedSkillInvocation {
 }
 export declare function parseSkillInvocations(text: string, skillsByCommandName: ReadonlyMap<string, Skill>): ParsedSkillInvocation[];
 export declare function resolveSkillSlashCommands(skills: readonly Skill[], _reservedDirectCommandNames: ReadonlySet<string>): ResolvedSkillSlashCommand[];
-export declare function buildSkillPromptMessage(skill: Pick<Skill, "name" | "filePath" | "content">, args: string): Promise<BuiltSkillPromptMessage>;
+export declare function buildSkillPromptMessage(skill: Pick<Skill, "name" | "filePath" | "content">, args: string, context?: BuildSkillPromptMessageContext): Promise<BuiltSkillPromptMessage>;

package/dist/types/gjc-runtime/state-runtime.d.ts

@@ -11,5 +11,27 @@ export interface StateCommandResult {
     stdout?: string;
     stderr?: string;
 }
+/**
+ * Reconcile a workflow skill's mode-state + active-state/HUD from a caller-derived
+ * payload. Unlike `gjc state write`, this is a derived repair: callers reconcile from
+ * an authoritative source (e.g. the ultragoal plan/ledger), where intermediate
+ * aggregate phases like ultragoal `active -> pending` are legitimate, so it bypasses
+ * ONLY verb transition-edge validation while preserving schema validation,
+ * unknown-phase rejection, version/checksum stamping, and audit/out-of-band tamper
+ * detection. Receipts carry `owner: "gjc-runtime"` and `verb: "reconcile"` so the
+ * provenance is distinguishable from a user-initiated write.
+ */
+export declare function reconcileWorkflowSkillState(options: {
+    cwd: string;
+    mode: CanonicalGjcWorkflowSkill;
+    sessionId: string | undefined;
+    threadId?: string;
+    turnId?: string;
+    active: boolean;
+    phase: string;
+    payload: Record<string, unknown>;
+}): Promise<{
+    stateFile: string;
+}>;
 export declare function readWorkflowStateJson(cwd: string, skill: CanonicalGjcWorkflowSkill, sessionId?: string): Promise<Record<string, unknown>>;
 export declare function runNativeStateCommand(args: string[], cwd?: string): Promise<StateCommandResult>;

package/dist/types/harness-control-plane/storage.d.ts

@@ -1,4 +1,8 @@
 import type { EventEnvelope, ReceiptFamily, SessionState } from "./types";
+interface ResolveHarnessSessionRootOptions {
+    expectedWorkspace?: string;
+}
+export declare function canonicalWorkspacePath(workspace: string): string;
 export declare const MAX_UNIX_SOCKET_PATH_BYTES = 100;
 export declare function controlSocketPath(root: string, sessionId: string, env?: NodeJS.ProcessEnv): string;
 export declare class StorageError extends Error {
@@ -27,6 +31,8 @@ export interface SessionPaths {
 }
 export declare function sessionPaths(root: string, sessionId: string): SessionPaths;
 export declare function readSessionState(root: string, sessionId: string): Promise<SessionState | null>;
+export declare function rememberHarnessSessionRoot(root: string, sessionId: string, env?: NodeJS.ProcessEnv): Promise<void>;
+export declare function resolveHarnessSessionRoot(root: string, sessionId: string, env?: NodeJS.ProcessEnv, options?: ResolveHarnessSessionRootOptions): Promise<string>;
 export declare function writeSessionState(root: string, state: SessionState): Promise<void>;
 export declare function sessionExists(root: string, sessionId: string): Promise<boolean>;
 /** Append a single severity envelope to events.jsonl. Single-writer discipline is the owner's job (M3). */
@@ -51,3 +57,4 @@ export declare function writeReceiptImmutable(root: string, sessionId: string, f
     createdAt: string;
 }): Promise<ReceiptIndexEntry>;
 export declare function readReceiptIndex(root: string, sessionId: string, family?: ReceiptFamily): Promise<ReceiptIndexEntry[]>;
+export {};

package/dist/types/lsp/client.d.ts

@@ -4,6 +4,7 @@ import type { LspClient, ServerConfig } from "./types";
  * @param ms - Timeout in milliseconds, or null/undefined to disable
  */
 export declare function setIdleTimeout(ms: number | null | undefined): void;
+export declare function isIdleCheckerActiveForTests(): boolean;
 /** Timeout for warmup initialize requests (5 seconds) */
 export declare const WARMUP_TIMEOUT_MS = 5000;
 /**

package/dist/types/main.d.ts

@@ -24,10 +24,19 @@ export interface AcpSessionFactoryOptions {
     sessionDir?: string;
     authStorage: AuthStorage;
     modelRegistry: ModelRegistry;
-    parsedArgs: Pick<Args, "apiKey">;
+    parsedArgs: Pick<Args, "apiKey" | "default" | "model" | "mpreset" | "thinking">;
     rawArgs: string[];
     createSession: (options: CreateAgentSessionOptions) => Promise<CreateAgentSessionResult>;
 }
+export declare function applyStartupModelProfiles(args: {
+    session: AgentSession;
+    settings: Settings;
+    modelRegistry: ModelRegistry;
+    parsedArgs: Pick<Args, "default" | "model" | "mpreset" | "thinking">;
+    startupModel?: CreateAgentSessionOptions["model"];
+    startupThinkingLevel?: CreateAgentSessionOptions["thinkingLevel"];
+}): Promise<void>;
+export declare function applyStartupModelProfilesOrExit(args: Parameters<typeof applyStartupModelProfiles>[0]): Promise<void>;
 /**
  * Build the per-`session/new` factory used by ACP mode.
  *

package/dist/types/modes/bridge/bridge-mode.d.ts

@@ -7,6 +7,7 @@ import { RpcHostUriBridge } from "../shared/agent-wire/host-uri-bridge";
 import { type BridgeCommandScope } from "../shared/agent-wire/scopes";
 import { UiRequestBroker } from "../shared/agent-wire/ui-request-broker";
 import type { BridgeUiResult } from "../shared/agent-wire/ui-result";
+import { UnattendedSessionControlPlane } from "../shared/agent-wire/unattended-session";
 import { type BridgePermissionRequestPayload } from "./bridge-client-bridge";
 import { type BridgeUiRequestPayload } from "./bridge-ui-context";
 import { BridgeEventStream } from "./event-stream";
@@ -30,6 +31,7 @@ interface BridgeFetchHandlerOptions {
     hostToolBridge?: RpcHostToolBridge;
     hostUriBridge?: RpcHostUriBridge;
     endpointMatrix?: Partial<BridgeEndpointMatrix>;
+    unattendedControlPlane?: UnattendedSessionControlPlane;
 }
 interface BridgeIdempotencyRecord {
     route: string;

package/dist/types/modes/components/custom-provider-wizard.d.ts

@@ -0,0 +1,10 @@
+import { Container } from "@gajae-code/tui";
+import type { ProviderSetupInput } from "../../setup/provider-onboarding";
+export type CustomProviderCredentialSource = "env" | "literal";
+export type CustomProviderWizardSubmit = ProviderSetupInput;
+export declare class CustomProviderWizardComponent extends Container {
+    #private;
+    constructor(onSubmit: (input: CustomProviderWizardSubmit) => void, onCancel: () => void, onRender?: () => void);
+    setSubmitError(error: string): void;
+    handleInput(keyData: string): void;
+}

package/dist/types/modes/components/model-selector.d.ts

@@ -23,8 +23,12 @@ export type ModelSelectorSelection = {
     selector: string;
     preset: ModelAssignmentPreset;
     assignments: Record<GjcModelAssignmentTargetId, ThinkingLevel>;
+} | {
+    kind: "profile";
+    profileName: string;
+    setDefault: boolean;
 };
-type RoleSelectCallback = (selection: ModelSelectorSelection) => void;
+type RoleSelectCallback = (selection: ModelSelectorSelection) => void | Promise<void>;
 /**
  * Component that renders a canonical model selector with provider tabs.
  * - Tab/Arrow Left/Right: Switch between provider tabs
@@ -40,5 +44,6 @@ export declare class ModelSelectorComponent extends Container {
     });
     handleInput(keyData: string): void;
     getSearchInput(): Input;
+    __testSelectProfile(profileName: string, setDefault: boolean): Promise<void>;
 }
 export {};

package/dist/types/modes/components/provider-onboarding-selector.d.ts

@@ -1,5 +1,5 @@
 import { Container } from "@gajae-code/tui";
-export type ProviderOnboardingAction = "oauth-login" | "api-guide";
+export type ProviderOnboardingAction = "custom-provider-wizard" | "oauth-login" | "api-guide";
 export declare class ProviderOnboardingSelectorComponent extends Container {
     #private;
     constructor(onSelect: (action: ProviderOnboardingAction) => void, onCancel: () => void);

package/dist/types/modes/controllers/selector-controller.d.ts

@@ -15,6 +15,7 @@ export declare class SelectorController {
         focus: Component;
     }): void;
     showProviderOnboarding(): void;
+    showCustomProviderWizard(): void;
     showSettingsSelector(): void;
     showThemeSelector(): void;
     showHistorySearch(): void;

package/dist/types/modes/prompt-action-autocomplete.d.ts

@@ -1,5 +1,5 @@
-import { type AutocompleteItem, type AutocompleteProvider, type SlashCommand } from "@gajae-code/tui";
-import { type KeybindingsManager } from "../config/keybindings";
+import type { AutocompleteItem, AutocompleteProvider, SlashCommand } from "@gajae-code/tui";
+import type { KeybindingsManager } from "../config/keybindings";
 interface PromptActionDefinition {
     id: string;
     label: string;

package/dist/types/modes/rpc/rpc-client.d.ts

@@ -8,7 +8,7 @@ import type { CompactionResult } from "@gajae-code/agent-core/compaction";
 import type { ImageContent, Model } from "@gajae-code/ai";
 import type { BashResult } from "../../exec/bash-executor";
 import type { SessionStats } from "../../session/agent-session";
-import type { RpcHandoffResult, RpcHostToolDefinition, RpcSessionState } from "./rpc-types";
+import type { RpcHandoffResult, RpcHostToolDefinition, RpcSessionState, RpcWorkflowGate, RpcWorkflowGateResolution } from "./rpc-types";
 export interface RpcClientOptions {
     /** Path to the CLI entry point (default: searches for dist/cli.js) */
     cliPath?: string;
@@ -60,6 +60,14 @@ export declare class RpcClient {
      * Subscribe to agent events.
      */
     onEvent(listener: RpcEventListener): () => void;
+    /**
+     * Subscribe to workflow lifecycle gates emitted by RPC mode.
+     */
+    onWorkflowGate(listener: (gate: RpcWorkflowGate) => void): () => void;
+    /**
+     * Answer a workflow lifecycle gate and wait for the server resolution envelope.
+     */
+    respondGate(gateId: string, answer: unknown, idempotencyKey?: string): Promise<RpcWorkflowGateResolution>;
     /**
      * Get collected stderr output (useful for debugging).
      */

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

@@ -145,7 +145,14 @@ export type RpcCommand = {
     id?: string;
     type: "login";
     providerId: string;
-};
+} | {
+    id?: string;
+    type: "negotiate_unattended";
+    declaration: RpcUnattendedDeclaration;
+} | ({
+    id?: string;
+    type: "workflow_gate_response";
+} & RpcWorkflowGateResponse);
 export interface RpcSessionState {
     model?: Model;
     thinkingLevel: ThinkingLevel | undefined;
@@ -411,12 +418,24 @@ export type RpcResponse = {
     data: {
         providerId: string;
     };
+} | {
+    id?: string;
+    type: "response";
+    command: "negotiate_unattended";
+    success: true;
+    data: RpcUnattendedAccepted;
+} | {
+    id?: string;
+    type: "response";
+    command: "workflow_gate_response";
+    success: true;
+    data: RpcWorkflowGateResolution;
 } | {
     id?: string;
     type: "response";
     command: string;
     success: false;
-    error: string;
+    error: string | object;
 };
 /** Emitted when an extension needs user input */
 export type RpcExtensionUIRequest = {
@@ -584,3 +603,161 @@ export type RpcExtensionUIResponse = {
     timedOut?: boolean;
 };
 export type RpcCommandType = RpcCommand["type"];
+/**
+ * Lifecycle stages that emit machine-addressable gates. v1 is single-agent;
+ * `team` parallel execution over RPC is deferred, so it is intentionally absent
+ * from this union. Gate construction rejects any other stage value.
+ */
+export type RpcWorkflowStage = "deep-interview" | "ralplan" | "ultragoal";
+/** Reserved stage names that are explicitly not part of the v1 contract. */
+export declare const RESERVED_WORKFLOW_STAGES: readonly string[];
+export type RpcWorkflowGateKind = "question" | "approval" | "execution";
+/**
+ * The documented JSON Schema 2020-12 subset supported by the gate validator.
+ * Schemas containing any keyword outside this shape are rejected at gate
+ * construction time so the server never advertises a schema it cannot validate.
+ */
+export interface RpcJsonSchema {
+    type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+    enum?: unknown[];
+    const?: unknown;
+    properties?: Record<string, RpcJsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | RpcJsonSchema;
+    items?: RpcJsonSchema;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minimum?: number;
+    maximum?: number;
+    title?: string;
+    description?: string;
+    oneOf?: RpcJsonSchema[];
+    anyOf?: RpcJsonSchema[];
+}
+export interface RpcWorkflowGateOption {
+    value: unknown;
+    label: string;
+    description?: string;
+}
+export interface RpcWorkflowGateContext {
+    title?: string;
+    prompt?: string;
+    summary?: string;
+    stage_state?: Record<string, unknown>;
+    artifact_refs?: Array<{
+        kind: string;
+        path?: string;
+        sha256?: string;
+    }>;
+    language?: string;
+}
+/** Outbound event: a machine-addressable workflow gate awaiting an answer. */
+export interface RpcWorkflowGate {
+    type: "workflow_gate";
+    /** Run-scoped, monotonic, stable id (e.g. `wg_<run>_<stage>_000001`). */
+    gate_id: string;
+    stage: RpcWorkflowStage;
+    kind: RpcWorkflowGateKind;
+    schema: RpcJsonSchema;
+    /** Canonical hash of `schema`; advertised hash must equal server validation hash. */
+    schema_hash: string;
+    options?: RpcWorkflowGateOption[];
+    context: RpcWorkflowGateContext;
+    created_at: string;
+    required: true;
+}
+/** Inbound: the agent's answer to a workflow gate. */
+export interface RpcWorkflowGateResponse {
+    gate_id: string;
+    answer: unknown;
+    /** Optional idempotency key; same key + body returns the cached resolution. */
+    idempotency_key?: string;
+}
+/** Outcome of resolving a gate, surfaced back to the answering client. */
+export interface RpcWorkflowGateResolution {
+    gate_id: string;
+    status: "accepted" | "rejected";
+    answer_hash: string;
+    resolved_at: string;
+    /** Present only when `status === "rejected"`. */
+    error?: RpcWorkflowGateValidationError;
+}
+/** Typed error shape for schema validation failures (#315 acceptance). */
+export interface RpcWorkflowGateValidationError {
+    code: "invalid_workflow_gate_answer";
+    gate_id: string;
+    schema_hash: string;
+    errors: Array<{
+        path: string;
+        keyword: string;
+        message: string;
+        expected?: unknown;
+    }>;
+}
+export interface RpcUnattendedBudget {
+    max_tokens: number;
+    max_tool_calls: number;
+    max_wall_time_ms: number;
+    max_cost_usd: number;
+}
+export interface RpcUnattendedDeclaration {
+    /** Identity of the operating external agent, recorded in the audit trail. */
+    actor: string;
+    budget: RpcUnattendedBudget;
+    /** Coarse command scopes the agent may use (maps to BridgeCommandScope). */
+    scopes: string[];
+    /** Action classes the agent is allowed to perform (default-deny otherwise). */
+    action_allowlist: string[];
+}
+export interface RpcUnattendedAccepted {
+    run_id: string;
+    actor: string;
+    budget: RpcUnattendedBudget;
+    scopes: string[];
+    action_allowlist: string[];
+    accepted_at: string;
+}
+export type RpcBudgetMetric = "tokens" | "tool_calls" | "wall_time" | "cost";
+/** Typed payload emitted when a declared budget cap is breached (#318). */
+export interface RpcBudgetExceeded {
+    code: "budget_exceeded";
+    metric: RpcBudgetMetric;
+    limit: number;
+    observed: number;
+    /** The accounting phase that detected the breach. */
+    phase: string;
+    run_id: string;
+    session_id?: string;
+    /** `aborting` = breach detected, async abort initiated; settled status follows in audit. */
+    abort_status: "aborting" | "aborted" | "abort_failed";
+}
+export type RpcUnattendedRefusalCode = "unattended_not_negotiated" | "incomplete_budget" | "unsupported_budget_metric" | "invalid_unattended_declaration" | "unattended_aborted";
+/** Typed refusal emitted when unattended mode cannot start or continue (fail-closed). */
+export interface RpcUnattendedRefused {
+    code: RpcUnattendedRefusalCode;
+    message: string;
+}
+/** v1 action taxonomy: every authorized operation maps to one of these classes. */
+export type RpcUnattendedActionClass = "command.prompt" | "command.control" | "command.bash" | "command.export" | "command.session" | "command.model" | "command.message_read" | "command.host_tools" | "command.host_uri" | "command.admin" | "bash.readonly" | "bash.mutating" | "bash.destructive" | "git.force_push" | "file.delete" | "file.write" | "host_tool.invoke" | "host_uri.read" | "host_uri.write" | "auth.login";
+/** Typed error when a command's coarse scope is not in the declared allowlist. */
+export interface RpcScopeDenied {
+    code: "scope_denied";
+    scope: string;
+    command?: string;
+    run_id: string;
+    session_id?: string;
+    /** Always true: enforcement happens before the side effect runs. */
+    pre_side_effect: true;
+}
+/** Typed error when an action class is not in the declared allowlist (default-deny). */
+export interface RpcActionDenied {
+    code: "action_denied";
+    action: string;
+    command?: string;
+    run_id: string;
+    session_id?: string;
+    pre_side_effect: true;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Ralplan approval + ultragoal execution gate mapping (#317).
+ *
+ * Maps the two human-gated lifecycle decisions onto `workflow_gate` events:
+ *  - ralplan `pending approval` -> `workflow_gate` { kind: "approval" } whose
+ *    answer is one of approve / request-changes / reject (+ optional comments);
+ *  - ultragoal execution sign-off -> `workflow_gate` { kind: "execution" } whose
+ *    answer is approve / decline (+ optional reason).
+ *
+ * Gates remain mandatory; the external agent substitutes for the human at the
+ * answer boundary only. Declining / requesting changes is honored and is NEVER
+ * silently treated as approval.
+ *
+ * This is the pure mapping primitive; routing ralplan/ultragoal through it when
+ * an unattended controller + gate broker are attached is wired with the transport
+ * in #321 and exercised end-to-end by #323.
+ */
+import type { RpcWorkflowGateContext } from "../../rpc/rpc-types";
+import type { OpenGateInput } from "./workflow-gate-broker";
+export type ApprovalDecision = "approve" | "request-changes" | "reject";
+export type ExecutionDecision = "approve" | "decline";
+export interface ApprovalGateAnswer {
+    decision: ApprovalDecision;
+    comments?: string;
+}
+export interface ExecutionGateAnswer {
+    decision: ExecutionDecision;
+    reason?: string;
+}
+export interface ApprovalGateResult {
+    approved: boolean;
+    decision: ApprovalDecision;
+    comments?: string;
+}
+export interface ExecutionGateResult {
+    approved: boolean;
+    decision: ExecutionDecision;
+    reason?: string;
+}
+export declare class ApprovalGateError extends Error {
+    readonly code: "invalid_answer_shape" | "unknown_decision" | "missing_comments";
+    constructor(code: "invalid_answer_shape" | "unknown_decision" | "missing_comments", message: string);
+}
+/** Build the ralplan `pending approval` -> `workflow_gate { kind: "approval" }` open-input. */
+export declare function approvalGate(context?: RpcWorkflowGateContext): OpenGateInput;
+/** Build the ultragoal execution sign-off -> `workflow_gate { kind: "execution" }` open-input. */
+export declare function executionGate(context?: RpcWorkflowGateContext): OpenGateInput;
+/**
+ * Decode a ralplan approval answer. `request-changes` requires comments and is
+ * NEVER treated as approval; only an explicit `approve` advances.
+ */
+export declare function decodeApproval(answer: unknown): ApprovalGateResult;
+/**
+ * Decode an ultragoal execution answer. Only an explicit `approve` advances;
+ * `decline` is honored and never silently approved.
+ */
+export declare function decodeExecution(answer: unknown): ExecutionGateResult;

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

@@ -1,7 +1,7 @@
 import type { AgentTool } from "@gajae-code/agent-core";
 import type { ExtensionUIContext } from "../../../extensibility/extensions";
 import type { AgentSession } from "../../../session/agent-session";
-import type { RpcCommand, RpcExtensionUIRequest, RpcHostToolDefinition, RpcHostUriSchemeDefinition, RpcResponse } from "../../rpc/rpc-types";
+import type { RpcCommand, RpcExtensionUIRequest, RpcHostToolDefinition, RpcHostUriSchemeDefinition, RpcResponse, RpcUnattendedAccepted, RpcUnattendedDeclaration, RpcWorkflowGateResolution, RpcWorkflowGateResponse } from "../../rpc/rpc-types";
 export type RpcCommandDispatchOutput = (obj: RpcResponse | RpcExtensionUIRequest | object) => void;
 export interface RpcHostToolRegistry {
     setTools(tools: RpcHostToolDefinition[]): AgentTool[];
@@ -9,12 +9,27 @@ export interface RpcHostToolRegistry {
 export interface RpcHostUriRegistry {
     setSchemes(schemes: RpcHostUriSchemeDefinition[]): string[];
 }
+/**
+ * Optional unattended control plane wired into RPC dispatch (#318/#319/#323).
+ * When present, `negotiate_unattended` and `workflow_gate_response` route here
+ * instead of falling through to the unknown-command path.
+ */
+export interface RpcUnattendedControlPlane {
+    /** Enter unattended mode (fail-closed); throws an Error on refusal. */
+    negotiate(declaration: RpcUnattendedDeclaration): RpcUnattendedAccepted;
+    /** Resolve a pending workflow gate with the agent's answer. */
+    resolveGate(response: RpcWorkflowGateResponse): Promise<RpcWorkflowGateResolution>;
+    isUnattended?(): boolean;
+    preflightCommand?(command: RpcCommand): void;
+    reconcileUsage?(phase?: string): void;
+}
 export interface RpcCommandDispatchContext {
     session: AgentSession;
     output: RpcCommandDispatchOutput;
     hostToolRegistry: RpcHostToolRegistry;
     hostUriRegistry: RpcHostUriRegistry;
     createUiContext: () => Pick<ExtensionUIContext, "notify">;
+    unattendedControlPlane?: RpcUnattendedControlPlane;
 }
 export declare function normalizeHostToolDefinitions(tools: RpcHostToolDefinition[]): RpcHostToolDefinition[];
 export declare function dispatchRpcCommand(command: RpcCommand, context: RpcCommandDispatchContext): Promise<RpcResponse>;