@gajae-code/coding-agent 0.17.2 → 0.17.5

package/dist/types/cli/public-command-evidence.d.ts

@@ -0,0 +1,99 @@
+export declare const EVIDENCE_LIMITS: Readonly<{
+    slots: 64;
+    recordBytes: 1048576;
+    totalBytes: 16777216;
+    ttlMs: 86400000;
+    fragmentBytes: 1024;
+    responseBytes: 8192;
+}>;
+export type EvidenceReferenceKind = "sessionId" | "operationRef" | "idempotencyKey" | "claimId" | "commandId" | "turnId";
+export interface EvidenceReference {
+    kind: EvidenceReferenceKind;
+    value: string;
+}
+export interface EvidenceClassification {
+    code: string;
+    category: "usage" | "unavailable" | "authorization" | "timeout" | "uncertain" | "operation" | "internal";
+    retryability: "yes" | "no" | "unknown";
+    outcomeCertainty: "not-applied" | "applied" | "unknown";
+}
+export type EvidenceUnavailableReason = "record_too_large" | "quota_exceeded" | "store_busy" | "permission_denied" | "permission_unsupported" | "unsafe_path" | "store_corrupt" | "io_error" | "verification_failed" | "locator_too_large" | "evidence_unavailable" | "evidence_changed" | "evidence_corrupt" | "evidence_unsafe" | "evidence_clock_invalid" | "invalid_request";
+export interface EvidenceUnavailable {
+    status: "unavailable";
+    reason: EvidenceUnavailableReason;
+    requiredBytes: number | null;
+    continuation: null;
+}
+export interface EvidenceContinuation {
+    kind: "local-store";
+    id: string;
+    sha256: string;
+    expiresAt: string;
+    page: number;
+    executable: "gjc";
+    argv: string[];
+}
+export interface EvidenceLocatorOptions {
+    family: "sdk" | "daemon";
+    scopeAgentDir?: string;
+    json?: boolean;
+}
+export interface PublishCommandEvidenceInput {
+    agentDir: string;
+    command: string[];
+    error: EvidenceClassification;
+    references: readonly EvidenceReference[];
+}
+export interface EvidenceRetained {
+    status: "retained";
+    id: string;
+    sha256: string;
+    bytes: number;
+    expiresAt: string;
+    continuation: EvidenceContinuation;
+}
+export interface EvidenceRecord {
+    schema: "gjc.command-error-record";
+    version: 1;
+    pagingVersion: 1;
+    id: string;
+    command: string[];
+    error: EvidenceClassification;
+    createdAt: string;
+    expiresAt: string;
+    references: EvidenceReference[];
+}
+export interface EvidencePage {
+    schema: "gjc.command-error-evidence";
+    version: 1;
+    ok: true;
+    id: string;
+    sha256: string;
+    expiresAt: string;
+    page: number;
+    complete: boolean;
+    fragments: {
+        entryId: string;
+        encoding: "base64";
+        offsetBytes: number;
+        totalBytes: number;
+        data: string;
+    }[];
+    next: EvidenceContinuation | null;
+}
+export interface ReadCommandEvidenceInput extends EvidenceLocatorOptions {
+    agentDir: string;
+    id: string;
+    sha256: string;
+    page?: number;
+}
+/** Narrow per-call fault instrumentation; production callers omit this argument. */
+export interface EvidencePublicationTestHooks {
+    id?: string;
+    before?: (phase: "write" | "file-sync" | "link" | "directory-sync" | "readback" | "cleanup") => void | Promise<void>;
+}
+export declare function publishCommandEvidence(input: PublishCommandEvidenceInput, options: EvidenceLocatorOptions, testHooks?: EvidencePublicationTestHooks): Promise<EvidenceRetained | EvidenceUnavailable>;
+export declare function readCommandEvidence(input: ReadCommandEvidenceInput): Promise<{
+    status: "available";
+    page: EvidencePage;
+} | EvidenceUnavailable>;

package/dist/types/cli/public-command-help.d.ts

@@ -0,0 +1,65 @@
+import { type PublicCommandDescriptor, type PublicHelpSection } from "./public-command-registry";
+export declare const PUBLIC_HELP_MAX_BYTES = 8192;
+export interface PublicHelpOptions {
+    json?: boolean;
+    section?: string;
+    page?: string | number;
+    revision?: string;
+}
+export type PublicHelpErrorCode = "unknown_command" | "invalid_section" | "invalid_page" | "invalid_revision" | "revision_mismatch" | "static_metadata_too_large" | "invalid_registry";
+export declare class PublicHelpError extends Error {
+    readonly code: PublicHelpErrorCode;
+    readonly exitCode: 2 | 1;
+    constructor(code: PublicHelpErrorCode);
+}
+export interface PublicHelpEntry {
+    id: string;
+    kind: "overview" | "usage" | "child" | "argument" | "option" | "example" | "recovery";
+    complete: true;
+    value: unknown;
+}
+export interface PublicHelpFragment {
+    id: string;
+    kind: "fragment";
+    complete: false;
+    encoding: "base64";
+    offsetBytes: number;
+    totalBytes: number;
+    sha256: string;
+    data: string;
+}
+export interface PublicHelpNext {
+    section: PublicHelpSection;
+    page: number;
+    executable: "gjc";
+    argv: string[];
+}
+export interface PublicHelpDocument {
+    schema: "gjc.command-help";
+    version: 1;
+    ok: true;
+    command: readonly string[];
+    canonicalCommand: readonly string[];
+    revision: string;
+    section: PublicHelpSection;
+    page: number;
+    sections: readonly PublicHelpSection[];
+    entries: readonly (PublicHelpEntry | PublicHelpFragment)[];
+    sectionComplete: boolean;
+    documentComplete: boolean;
+    next: PublicHelpNext | null;
+}
+export interface PublicHelpRenderResult {
+    /** Complete serialization including its single trailing newline. No output is written. */
+    output: string;
+    bytes: number;
+    document: PublicHelpDocument;
+}
+/** The digest covers every descriptor and this renderer's paging/schema policy. */
+export declare function getPublicHelpRevision(registry?: readonly PublicCommandDescriptor[]): string;
+/**
+ * Pure command-local rendering. Each page holds one complete entry or one byte fragment;
+ * empty sections still have page 1. This keeps traversal stable and independently bounded.
+ * The optional registry supports isolated static fixtures without replacing global state.
+ */
+export declare function renderPublicCommandHelp(command: readonly string[], options?: PublicHelpOptions, registry?: readonly PublicCommandDescriptor[]): PublicHelpRenderResult;

package/dist/types/cli/public-command-registry.d.ts

@@ -0,0 +1,69 @@
+import type { ArgDescriptor, FlagDescriptor } from "@gajae-code/utils/cli";
+import { type Operation, type OperationKind } from "../sdk/protocol/operation-registry";
+export declare const PUBLIC_HELP_SECTIONS: readonly ["overview", "usage", "children", "arguments", "options", "examples", "recovery"];
+export type PublicHelpSection = (typeof PUBLIC_HELP_SECTIONS)[number];
+export type PublicCommandFamily = "sdk" | "daemon";
+export type PublicDisruption = "none" | "interrupts-work" | "force-kill";
+export interface PublicRecovery {
+    description: string;
+    disruption: PublicDisruption;
+    requiresConfirmation: boolean;
+}
+export interface PublicFlagDescriptor extends FlagDescriptor {
+    description: string;
+    /** Boundary options are stripped before operation parsing. */
+    boundary?: "help" | "mode" | "retrieval";
+    conflicts?: readonly string[];
+    requires?: readonly string[];
+    risk?: string;
+    validation?: "positive-safe-integer" | "sha256" | "error-id" | "search-limit" | "pending-ceiling";
+    /** Serve's existing operation parser accepts separate operands only. */
+    valueSyntax?: "separate" | "separate-or-equals";
+}
+export interface PublicArgumentDescriptor extends ArgDescriptor {
+    description: string;
+}
+export interface PublicCommandDescriptor {
+    command: readonly string[];
+    canonicalCommand: readonly string[];
+    parent: readonly string[] | null;
+    description: string;
+    /** Effective local grammar, not a union of sibling options. Keys have no leading --. */
+    flags: Readonly<Record<string, PublicFlagDescriptor>>;
+    /** Insertion order is positional order; child tokens are not arguments. */
+    args: Readonly<Record<string, PublicArgumentDescriptor>>;
+    children: readonly string[];
+    usage: readonly {
+        syntax: string;
+        executable: false;
+    }[];
+    examples: readonly {
+        syntax: string;
+        executable: false;
+    }[];
+    recovery: readonly PublicRecovery[];
+    risk?: string;
+    defaultChild?: string;
+    exactlyOneOf?: readonly (readonly string[])[];
+    /** Semantic conditions remain runtime-owned (e.g. proof-bound retirement). */
+    constraints: readonly string[];
+    operationKind?: Exclude<OperationKind, "reverse">;
+}
+export interface PublicCommandResolution {
+    descriptor: PublicCommandDescriptor;
+    /** Number of path tokens consumed, including the family. No argv scanning is performed. */
+    consumed: number;
+    remaining: readonly string[];
+    exact: boolean;
+}
+export declare const PUBLIC_BOUNDARY_FLAGS: Readonly<Record<string, PublicFlagDescriptor>>;
+export declare const PUBLIC_RETRIEVAL_FLAGS: Readonly<Record<string, PublicFlagDescriptor>>;
+/** Static descriptors only: no settings, theme, broker, transport, filesystem or process initialization. */
+export declare const PUBLIC_COMMANDS: readonly PublicCommandDescriptor[];
+/** Exact full public path lookup; private workers and function-only verbs are absent. */
+export declare function getPublicCommand(command: readonly string[]): PublicCommandDescriptor | undefined;
+export declare function getPublicCommandChildren(descriptor: PublicCommandDescriptor): readonly PublicCommandDescriptor[];
+/** Resolve path tokens only. The entry scanner must first respect flag operands and --. */
+export declare function resolvePublicCommand(tokens: readonly string[]): PublicCommandResolution | undefined;
+/** Operation metadata is reused, not promoted to command paths or usage-level enum rejection. */
+export declare function getPublicRawOperations(kind: Exclude<OperationKind, "reverse">): readonly Operation[];

package/dist/types/cli/session-picker.d.ts

@@ -1,5 +1,5 @@
 import { type SessionSelectionResult } from "../modes/components/session-selector";
 import { type SessionInfo } from "../session/session-manager";
 export declare function deleteSessionPickerCandidate(sessionPath: string, explicitSessionDir?: string): Promise<void>;
-/** Show the read-only TUI session picker and return the user's consent intent. */
+/** Show the session picker and return the user's resume consent intent. */
 export declare function selectSession(sessions: SessionInfo[], explicitSessionDir?: string): Promise<SessionSelectionResult>;

package/dist/types/cli/setup-cli.d.ts

@@ -18,6 +18,7 @@ export interface SetupCommandArgs {
         baseUrl?: string;
         apiKeyEnv?: string;
         model?: string[];
+        discover?: boolean;
         modelsPath?: string;
         smoke?: boolean;
         install?: boolean;

package/dist/types/cli/skills-cli.d.ts

@@ -5,6 +5,11 @@ export interface SkillsCommandArgs {
     flags?: {
         json?: boolean;
         source?: "all" | "project" | "user";
+        /** Max discover results; clamped to [1, SKILL_DISCOVERY_MAX_LIMIT] by the library. */
+        limit?: number;
+        /** Zero-based start of the discover page; normalized by the library. */
+        offset?: number;
+        query?: string;
     };
 }
 export declare function runSkillsCommand(cmd: SkillsCommandArgs): Promise<void>;

package/dist/types/cli.d.ts

@@ -1,3 +1,6 @@
 #!/usr/bin/env bun
+import type { CommandEntry } from "@gajae-code/utils/cli";
+/** Public-family hooks kept available for private-worker tests without loading the full registry. */
+export declare const commands: CommandEntry[];
 /** Run the CLI with argv excluding process.argv prefix. */
 export declare function runCli(argv: string[]): Promise<void>;

package/dist/types/commands/daemon.d.ts

@@ -1,54 +1,8 @@
-/**
- * Manage GJC background daemons (status/list/stop/restart).
- */
-import { Command } from "@gajae-code/utils/cli";
+/** Manage public daemon operations while keeping worker grammar private. */
+import { type ArgDescriptor, Command, type FlagDescriptor } from "@gajae-code/utils/cli";
 export default class Daemon extends Command {
     static description: string;
-    static examples: string[];
-    static args: {
-        action: import("@gajae-code/utils/cli").ArgDescriptor & {
-            description: string;
-            required: false;
-            options: string[];
-        };
-        kind: import("@gajae-code/utils/cli").ArgDescriptor & {
-            description: string;
-            required: false;
-            multiple: true;
-        };
-    };
-    static flags: {
-        verbose: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            char: string;
-            description: string;
-        };
-        all: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            description: string;
-        };
-        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            description: string;
-        };
-        force: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            description: string;
-        };
-        "graceful-timeout-ms": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
-            description: string;
-        };
-        "kill-timeout-ms": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
-            description: string;
-        };
-        "spawn-if-stopped": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            description: string;
-        };
-        smoke: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            description: string;
-        };
-        "owner-id": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
-            description: string;
-        };
-        "agent-dir": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
-            description: string;
-        };
-    };
+    static args: Record<string, ArgDescriptor>;
+    static flags: Record<string, FlagDescriptor>;
     run(): Promise<void>;
 }

package/dist/types/commands/sdk.d.ts

@@ -41,10 +41,10 @@ export declare function watchSessionHostBrokerLiveness(deps: {
  * no client attached before treating itself as abandoned.
  *
  * This cannot fire during healthy work. "Attached" is the host's own live
- * socket-subscription count, so a client that is merely idle — an editor
- * sitting on an open ACP session, a long agent turn with nobody typing — still
- * holds a socket and resets the window on every poll. Only a client that is
- * actually gone opens it, and 30 minutes is far longer than any client
+ * demand count: observer-only sockets (such as an idle chat daemon) do not
+ * reset the window, while an in-flight turn is reported separately. Only a
+ * client that is actually demanding the host opens it, and 30 minutes is far
+ * longer than any client
  * reconnect budget (ACP's is seconds), so a crashed-and-restarted client
  * reattaches long before the window closes.
  */
@@ -66,8 +66,8 @@ export declare const SESSION_HOST_FIRST_ATTACH_GRACE_MS: number;
  * from every client for a full idle grace, or nobody has come for it at all
  * for a full first-attach grace.
  *
- * `readAttachedClients` reports the host's own live client/socket subscription
- * count; `undefined` means the SDK endpoint publishes no such evidence — before
+ * `readAttachedClients` reports the host's own live demanding-client count;
+ * `undefined` means the SDK endpoint publishes no such evidence — before
  * startup, after teardown, or when every reader itself fails. That ambiguity is
  * never instant detachment: it cannot reap on the poll that first sees it, it
  * can only open a window. Which window depends on what was already observed. A
@@ -78,25 +78,24 @@ export declare const SESSION_HOST_FIRST_ATTACH_GRACE_MS: number;
  * an observed count of zero. Every reachable state therefore carries a finite
  * bound.
  *
- * `readWorkInFlight` reports whether the host is running agent work right now.
- * Work is positive proof a client did come for this host: a prompt can only
- * arrive over an endpoint a client dialed. Live work therefore restarts both
- * windows, which is what keeps a mid-prompt host alive whether its count reads
- * zero or stops being readable at all. That still bounds a host whose SDK
- * runtime never came up: with no transport it can never receive a prompt, so it
- * never reports work and its window keeps running from process start. And any
- * real turn ends, after which the window resumes; live work defers a bound, it
- * never removes it.
+ * `readWorkLease` reports whether the host's authoritative session-work lease
+ * is held. A lease is positive proof a client did come for this host: a prompt
+ * can only arrive over an endpoint a client dialed. Live work therefore
+ * restarts both windows, which is what keeps a mid-prompt host alive whether
+ * its count reads zero or stops being readable at all. That still bounds a
+ * host whose SDK runtime never came up: with no transport it can never receive
+ * a prompt, so it never acquires work and its window keeps running from process
+ * start. Releasing the lease resumes the applicable bound.
  */
 export declare function watchSessionHostClientAttachment(deps: {
     readAttachedClients: () => number | undefined;
-    readWorkInFlight?: () => boolean;
+    readWorkLease?: () => boolean;
     now?: () => number;
     sleep?: (ms: number) => Promise<void>;
     idleGraceMs?: number;
     firstAttachGraceMs?: number;
     pollMs?: number;
-}): Promise<void>;
+}): Promise<"detached_idle">;
 /** Opens lifecycle-authorized history without letting replacement content reach readiness. */
 export declare function openLifecycleSessionManager(request: SessionLifecycleLaunchRequest, cwd: string, agentDir: string): Promise<{
     parsed: ParsedArgs;
@@ -126,6 +125,10 @@ export type SdkInternalArgv = {
     agentDir: string;
 } | {
     action: "session-host-internal";
+} | {
+    action: "stderr-drain-internal";
+    logPath: string;
+    maxBytes: number;
 };
 /** Parses the exact private argv contracts used by SDK child-process spawns. */
 export declare function parseSdkInternalArgv(argv: readonly string[]): SdkInternalArgv;
@@ -133,25 +136,5 @@ export default class Sdk extends Command {
     static description: string;
     static hidden: boolean;
     static delegateHelp: boolean;
-    static args: {
-        action: import("@gajae-code/utils/cli").ArgDescriptor & {
-            required: false;
-            options: string[];
-        };
-    };
-    static flags: {
-        stdio: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
-            description: string;
-        };
-        socket: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
-            description: string;
-        };
-        session: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
-            description: string;
-        };
-        "pending-ceiling": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
-            description: string;
-        };
-    };
     run(): Promise<void>;
 }

package/dist/types/commands/setup.d.ts

@@ -102,6 +102,9 @@ export default class Setup extends Command {
             description: string;
             multiple: true;
         };
+        discover: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
         "models-path": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };

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

@@ -25,6 +25,15 @@ export default class Skills extends Command {
             options: string[];
             default: string;
         };
+        limit: import("@gajae-code/utils/cli").FlagDescriptor<"integer"> & {
+            description: string;
+        };
+        offset: import("@gajae-code/utils/cli").FlagDescriptor<"integer"> & {
+            description: string;
+        };
+        query: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
     };
     static examples: string[];
     run(): Promise<void>;