@gajae-code/coding-agent 0.2.5 → 0.3.0

package/dist/types/harness-control-plane/session-lease.d.ts

@@ -0,0 +1,65 @@
+export interface SessionLease {
+    ownerId: string;
+    sessionId: string;
+    pid: number;
+    leaseTokenHash: string;
+    endpoint: {
+        kind: "unix-socket" | "fifo";
+        path: string;
+    } | null;
+    eventsPath: string;
+    heartbeatAt: string;
+    expiresAt: string;
+    leaseEpoch: number;
+    writer: {
+        ownerId: string;
+        leaseEpoch: number;
+    };
+}
+export declare class LeaseError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export type LeaseStatus = "missing" | "live" | "expiredAlive" | "dead" | "epermAlive";
+type PidStatus = "alive" | "dead" | "eperm";
+export declare function readLease(root: string, sessionId: string): Promise<SessionLease | null>;
+export declare function isExpired(lease: SessionLease, clock?: () => number): boolean;
+export declare function classifyLeaseStatus(lease: SessionLease | null, opts?: {
+    clock?: () => number;
+    probe?: (pid: number) => PidStatus;
+}): LeaseStatus;
+/** Liveness probe via signal 0. Defaults to the real process table; injectable for tests. */
+export declare function isOwnerAlive(pid: number, probe?: (pid: number) => boolean): boolean;
+export declare function isStale(lease: SessionLease, opts?: {
+    clock?: () => number;
+    probe?: (pid: number) => boolean;
+}): boolean;
+export interface AcquireOptions {
+    ownerId: string;
+    pid: number;
+    endpoint?: SessionLease["endpoint"];
+    eventsPath: string;
+    ttlMs: number;
+    clock?: () => number;
+    probe?: (pid: number) => boolean | PidStatus;
+}
+export interface AcquiredLease {
+    lease: SessionLease;
+    token: string;
+}
+/**
+ * Acquire (or take over a stale) lease. Fails closed with `lease_held` when a live,
+ * unexpired lease is held by a different owner. Re-acquiring as the current owner refreshes.
+ */
+export declare function acquireLease(root: string, sessionId: string, opts: AcquireOptions): Promise<AcquiredLease>;
+/** Refresh the lease expiry. Only the recorded owner may heartbeat (single-writer). */
+export declare function heartbeat(root: string, sessionId: string, ownerId: string, ttlMs: number, clock?: () => number): Promise<SessionLease>;
+/** Whether `ownerId` is the live, unexpired single writer permitted to append events. */
+export declare function canWriteEvents(lease: SessionLease, ownerId: string, clock?: () => number): boolean;
+/** Release the lease (owner shutdown). Only the holder may release. */
+export declare function releaseLease(root: string, sessionId: string, ownerId: string): Promise<void>;
+export declare function reapDeadOwnerArtifacts(root: string, sessionId: string, expectedOwnerId: string, expectedEpoch: number, opts?: {
+    clock?: () => number;
+    probe?: (pid: number) => PidStatus;
+}): Promise<boolean>;
+export {};

package/dist/types/harness-control-plane/state-machine.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Lifecycle state machine + the universal `{state, evidence, nextAllowedActions}` contract.
+ *
+ * `nextAllowedActions` is the forcing function: it tells the caller exactly which
+ * primitives are currently permitted and, when not, why. Owner-routed verbs
+ * (`submit`) report `owner-not-live` when no `RuntimeOwner` holds the session lease.
+ */
+import type { HarnessLifecycle, NextAllowedAction, PrimitiveResponse, SessionState, SessionStateView } from "./types";
+export declare function isTerminal(lifecycle: HarnessLifecycle): boolean;
+export declare function canTransition(from: HarnessLifecycle, to: HarnessLifecycle): boolean;
+export declare function assertTransition(from: HarnessLifecycle, to: HarnessLifecycle): void;
+/**
+ * Derive the permitted next actions for a session given its lifecycle and whether
+ * a live owner currently holds the lease.
+ */
+export declare function nextAllowedActions(lifecycle: HarnessLifecycle, ownerLive: boolean): NextAllowedAction[];
+export declare function buildStateView(state: SessionState, ownerLive: boolean): SessionStateView;
+/** Build the universal contract response carried by every primitive. */
+export declare function buildResponse<E extends Record<string, unknown>>(state: SessionState, ownerLive: boolean, evidence: E, ok?: boolean): PrimitiveResponse<E>;

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

@@ -0,0 +1,53 @@
+import type { EventEnvelope, ReceiptFamily, SessionState } from "./types";
+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 {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** Resolve the harness state root from explicit value, env, or cwd default. */
+export declare function resolveHarnessRoot(opts?: {
+    root?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+export declare function assertSafeSessionId(id: string): void;
+export declare function generateSessionId(prefix?: string): string;
+export interface SessionPaths {
+    dir: string;
+    state: string;
+    lease: string;
+    events: string;
+    receiptsIndex: string;
+    receiptsDir: string;
+    artifactsDir: string;
+    controlSock: string;
+    controlFifo: string;
+    gjcSessionDir: string;
+}
+export declare function sessionPaths(root: string, sessionId: string): SessionPaths;
+export declare function readSessionState(root: string, sessionId: string): Promise<SessionState | null>;
+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). */
+export declare function appendEvent(root: string, sessionId: string, envelope: EventEnvelope): Promise<void>;
+/** Read events from cursor (exclusive). Tail-only: never mutates the log. */
+export declare function readEvents(root: string, sessionId: string, fromCursor?: number): Promise<EventEnvelope[]>;
+export interface ReceiptIndexEntry {
+    receiptId: string;
+    family: ReceiptFamily;
+    valid: boolean;
+    createdAt: string;
+    path: string;
+}
+/**
+ * Persist a receipt immutably. Fails closed if the receipt id already exists,
+ * then appends an index entry to receipts.jsonl.
+ */
+export declare function writeReceiptImmutable(root: string, sessionId: string, family: ReceiptFamily, receiptId: string, value: {
+    receiptId: string;
+    family: ReceiptFamily;
+    valid: boolean;
+    createdAt: string;
+}): Promise<ReceiptIndexEntry>;
+export declare function readReceiptIndex(root: string, sessionId: string, family?: ReceiptFamily): Promise<ReceiptIndexEntry[]>;

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

@@ -0,0 +1,162 @@
+/**
+ * Core types for the gajae-code-native coding-harness operations control plane (v1).
+ *
+ * See the approved consensus plan at
+ * `.gjc/plans/ralplan/2026-06-02-0853-3e33/stage-02-revision.md` and the spec at
+ * `.gjc/specs/deep-interview-harness-control-plane.md`.
+ *
+ * v1 implements the gajae-code adapter only. omx/codex/remote/auth are deferred seams.
+ */
+/** Harnesses the control plane can operate. v1 implements `gajae-code` only. */
+export type Harness = "gajae-code" | "codex" | "omx";
+/** Lifecycle states of an operated session. */
+export type HarnessLifecycle = "new" | "started" | "submitted" | "observing" | "recovering" | "validating" | "finalizing" | "completed" | "blocked" | "retired";
+/** Event severities emitted by the owner. */
+export type Severity = "info" | "warn" | "critical";
+/** Bounded git delta classification surfaced by `observe`. */
+export type GitDelta = "clean" | "dirty" | "zero-delta" | "unknown";
+/** Risk classification surfaced by `observe`. */
+export type RiskKind = "normal" | "prompt-not-accepted" | "deleted-worktree" | "vanished-dirty";
+/** Deterministic recovery classifications. */
+export type RecoveryClassification = "continue" | "send-enter" | "reinject-prompt" | "restart-clean" | "restart-preserve-delta" | "fallback-codex-exec" | "human-check";
+/** Receipt families persisted under the session storage dir. */
+export type ReceiptFamily = "vanish" | "prompt-acceptance" | "validation" | "completion";
+/** The CLI verbs / primitives exposed by `gjc harness <verb>`. */
+export type HarnessVerb = "start" | "submit" | "observe" | "classify" | "recover" | "validate" | "finalize" | "retire" | "events" | "monitor" | "operate";
+/** Submission transports. */
+export type SubmitMode = "paste-buffer" | "stdin" | "file";
+/** A single entry in the forcing-function `nextAllowedActions` list. */
+export interface NextAllowedAction {
+    verb: HarnessVerb;
+    available: boolean;
+    /** Present when `available` is false; explains why the verb is currently disallowed. */
+    reason?: string;
+}
+/** Compact, model-facing view of session state included in every response. */
+export interface SessionStateView {
+    sessionId: string;
+    lifecycle: HarnessLifecycle;
+    harness: Harness;
+    ownerLive: boolean;
+    blockers: string[];
+}
+/**
+ * The universal contract: EVERY primitive response carries `{state, evidence, nextAllowedActions}`.
+ * `ok` is a transport-level convenience; semantic blocking is expressed via state + nextAllowedActions.
+ */
+export interface PrimitiveResponse<E = Record<string, unknown>> {
+    ok: boolean;
+    state: SessionStateView;
+    evidence: E;
+    nextAllowedActions: NextAllowedAction[];
+}
+/** Re-grabbable session handle returned by `start` / `operate`. */
+export interface SessionHandle {
+    sessionId: string;
+    harness: Harness;
+    repo: string | null;
+    workspace: string;
+    branch: string | null;
+    base: string | null;
+    issueOrPr: string | null;
+    processHandle: {
+        kind: "runtime-owner";
+        ownerId: string | null;
+        pid: number | null;
+    };
+    rpcHandle: {
+        kind: "rpc-subprocess";
+        pid: number | null;
+        sessionDir: string;
+    };
+    ownerHandle: {
+        leasePath: string;
+        endpoint: string | null;
+        heartbeatAt: string | null;
+    };
+    routerHandle: {
+        kind: "default-in-owner";
+        policy: string;
+        eventsPath: string;
+    };
+    viewportHandle: {
+        kind: "event-monitor";
+        tmuxSessionName: string | null;
+        viewOnly: true;
+    };
+    startedAt: string;
+    updatedAt: string;
+}
+/** Persisted per-session record (state.json). */
+export interface SessionState {
+    schemaVersion: number;
+    sessionId: string;
+    lifecycle: HarnessLifecycle;
+    harness: Harness;
+    handle: SessionHandle;
+    /** Per-classification retry counters consumed by the recovery policy. */
+    retries: Record<string, number>;
+    blockers: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** Bounded observed-signal vocabulary surfaced by `observe` (the owner only ever emits these). */
+export type ObservedSignal = "SessionStart" | "prompt-accepted" | "tool-call" | "test-running" | "commit-created" | "completed" | "error" | "streaming" | "idle";
+export declare const OBSERVED_SIGNALS: readonly ObservedSignal[];
+/** Bounded observation surfaced by `observe` — never a raw pane/transcript dump. */
+export interface Observation {
+    lifecycle: HarnessLifecycle;
+    ownerLive: boolean;
+    cwd: string;
+    branch: string | null;
+    gitDelta: GitDelta;
+    lastActivityAt: string | null;
+    observedSignals: string[];
+    risk: RiskKind;
+    /** RPC subprocess liveness, distinct from owner-process/lease liveness. Optional for back-compat. */
+    rpcLive?: boolean;
+    /** ISO timestamp of the most recent RPC frame the owner observed, if any. */
+    rpcLastFrameAt?: string | null;
+}
+/** Input to the deterministic recovery classifier. */
+export interface ClassifyInput {
+    observation: Observation;
+    /** Remaining retry budget per classification family. */
+    retryBudget: RetryBudget;
+    /** Whether an accepted prompt was in flight when the owner/RPC was last seen. */
+    acceptedPromptActive?: boolean;
+}
+/** Default and supplied retry budgets. */
+export interface RetryBudget {
+    reinjectPrompt: number;
+    zeroDeltaVanish: number;
+    dirtyVanishPreserve: number;
+    validationRepair: number;
+}
+/** Result of the deterministic recovery classifier. */
+export interface RecoveryDecision {
+    classification: RecoveryClassification;
+    reason: string;
+    severity: Severity;
+    /** Whether executing the recommended action requires a live owner. */
+    ownerRequired: boolean;
+    /** Receipt family that MUST be valid before the action may proceed (e.g. `vanish`). */
+    requiredReceiptFamily: ReceiptFamily | null;
+}
+/** Severity-tagged event envelope written exclusively by the owner. */
+export interface EventEnvelope<E = Record<string, unknown>> {
+    eventId: string;
+    cursor: number;
+    createdAt: string;
+    severity: Severity;
+    kind: string;
+    state: SessionStateView;
+    evidence: E;
+    nextAllowedActions: NextAllowedAction[];
+    writer: {
+        ownerId: string;
+        leaseEpoch: number;
+    };
+}
+export declare const SESSION_SCHEMA_VERSION: 1;
+export declare const DEFAULT_RETRY_BUDGET: RetryBudget;

package/dist/types/hooks/skill-keywords.d.ts

@@ -1,3 +1,4 @@
+import { type CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
 export interface SkillKeywordDefinition {
     keyword: string;
     skill: GjcWorkflowSkill;
@@ -5,7 +6,7 @@ export interface SkillKeywordDefinition {
     guidance: string;
 }
 export declare const GJC_WORKFLOW_SKILLS: readonly ["deep-interview", "ralplan", "ultragoal", "team"];
-export type GjcWorkflowSkill = (typeof GJC_WORKFLOW_SKILLS)[number];
+export type GjcWorkflowSkill = CanonicalGjcWorkflowSkill;
 export declare const GJC_SKILL_KEYWORD_DEFINITIONS: readonly SkillKeywordDefinition[];
 export declare function isGjcWorkflowSkill(value: string): value is GjcWorkflowSkill;
 export declare function compareSkillKeywordMatches(a: {

package/dist/types/hooks/skill-state.d.ts

@@ -1,5 +1,5 @@
 import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
-import type { SkillActiveEntry as CanonicalSkillActiveEntry, WorkflowHudSummary } from "../skill-state/active-state";
+import { type SkillActiveState } from "../skill-state/active-state";
 import { type GjcWorkflowSkill } from "./skill-keywords";
 export declare const GJC_STATE_DIR = ".gjc/state";
 export declare const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
@@ -14,34 +14,7 @@ export interface SkillKeywordMatch {
     skill: GjcWorkflowSkill;
     priority: number;
 }
-export interface SkillActiveEntry extends Omit<CanonicalSkillActiveEntry, "skill"> {
-    skill: GjcWorkflowSkill;
-    phase?: string;
-    active?: boolean;
-    activated_at?: string;
-    updated_at?: string;
-    session_id?: string;
-    thread_id?: string;
-    turn_id?: string;
-    hud?: WorkflowHudSummary;
-    stale?: boolean;
-}
-export interface SkillActiveState {
-    version: number;
-    active: boolean;
-    skill: GjcWorkflowSkill;
-    keyword: string;
-    phase: string;
-    activated_at: string;
-    updated_at: string;
-    source: "gjc-skill-state-hook";
-    session_id?: string;
-    thread_id?: string;
-    turn_id?: string;
-    initialized_mode?: GjcWorkflowSkill;
-    initialized_state_path?: string;
-    active_skills: SkillActiveEntry[];
-}
+export type { SkillActiveEntry, SkillActiveState } from "../skill-state/active-state";
 export interface ModeState {
     active?: boolean;
     current_phase?: string;

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

@@ -21,6 +21,7 @@ export interface HookSelectorOptions {
      * byte-identical to the previous implementation for all consumers.
      */
     wrapFocused?: boolean;
+    scrollTitleRows?: number;
 }
 export declare class HookSelectorComponent extends Container {
     #private;

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

@@ -86,6 +86,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     retryLoader: Loader | undefined;
     autoCompactionEscapeHandler?: () => void;
     retryEscapeHandler?: () => void;
+    retryCountdownTimer?: ReturnType<typeof setInterval>;
     unsubscribe?: () => void;
     onInputCallback?: (input: SubmittedUserInput) => void;
     optimisticUserMessageSignature: string | undefined;

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

@@ -93,6 +93,7 @@ export interface InteractiveModeContext {
     retryLoader: Loader | undefined;
     autoCompactionEscapeHandler?: () => void;
     retryEscapeHandler?: () => void;
+    retryCountdownTimer?: ReturnType<typeof setInterval>;
     unsubscribe?: () => void;
     onInputCallback?: (input: SubmittedUserInput) => void;
     optimisticUserMessageSignature: string | undefined;

package/dist/types/sdk.d.ts

@@ -127,6 +127,8 @@ export interface CreateAgentSessionOptions {
     forkContextSeed?: ForkContextSeed;
     /** Optional provider state override. Fork-context children should omit this by default. */
     providerSessionState?: Map<string, ProviderSessionState>;
+    /** Cooperative pause checkpoint passed through to Agent. */
+    shouldPause?: () => boolean;
 }
 /** Result from createAgentSession */
 export interface CreateAgentSessionResult {

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

@@ -90,6 +90,7 @@ export type AgentSessionEvent = AgentEvent | {
     maxAttempts: number;
     delayMs: number;
     errorMessage: string;
+    unbounded?: boolean;
 } | {
     type: "auto_retry_end";
     success: boolean;
@@ -604,6 +605,7 @@ export declare class AgentSession {
     abort(options?: {
         goalReason?: "interrupted" | "internal";
         timeoutMs?: number;
+        cause?: "user_interrupt" | "new_session" | "session_switch" | "compaction" | "handoff" | "tool_abort" | "internal";
     }): Promise<void>;
     /**
      * Start a new session, optionally with initial messages and parent tracking.
@@ -752,6 +754,12 @@ export declare class AgentSession {
      * Cancel in-progress retry.
      */
     abortRetry(): void;
+    /**
+     * Skip the current retry backoff and re-attempt immediately. Distinct from
+     * abortRetry(), which cancels the retry and returns to idle. No-op when no
+     * retry backoff is active.
+     */
+    retryNow(): void;
     /** Whether auto-retry is currently in progress */
     get isRetrying(): boolean;
     /** Whether auto-retry is enabled */

package/dist/types/skill-state/active-state.d.ts

@@ -46,6 +46,8 @@ export interface SkillActiveState {
     session_id?: string;
     thread_id?: string;
     turn_id?: string;
+    initialized_mode?: CanonicalGjcWorkflowSkill;
+    initialized_state_path?: string;
     active_skills?: SkillActiveEntry[];
     [key: string]: unknown;
 }

package/dist/types/skill-state/deep-interview-mutation-guard.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool } from "@gajae-code/agent-core";
 export declare const DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE = "Deep-interview phase boundary: continue gathering context/questions/risks and emit a handoff/spec before code edits. Mutation tools and patch execution are blocked while deep-interview is active; finalize specs through `gjc deep-interview --write --stage final` or hand off to an execution phase.";
-export declare const WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE = "Workflow state JSON is runtime-owned. Use `gjc state <skill> read|write --input '<json>'` for deep-interview, ralplan, ultragoal, and team. Planning artifacts under `.gjc/specs/` and `.gjc/plans/` remain allowed.";
+export declare const WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE = ".gjc workflow state and artifacts are runtime-owned. Agent mutation tools cannot edit `.gjc/**`; use the sanctioned `gjc` CLI instead.";
 type ToolWithEditMode = AgentTool & {
     mode?: unknown;
     customWireName?: unknown;

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

@@ -4,6 +4,12 @@ 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 {
+    algorithm: "sha256";
+    value: string;
+    covered_path: string;
+    computed_at: string;
+}
 export interface WorkflowStateReceipt {
     version: 1;
     skill: CanonicalGjcWorkflowSkill;
@@ -15,6 +21,24 @@ export interface WorkflowStateReceipt {
     fresh_until: string;
     status: WorkflowStateReceiptStatus;
     mutation_id: string;
+    verb?: string;
+    from_phase?: string;
+    to_phase?: string;
+    forced?: boolean;
+    paths?: string[];
+    content_sha256?: WorkflowStateContentChecksum;
+}
+export interface AuditEntry {
+    ts: string;
+    skill?: string;
+    category: string;
+    verb: string;
+    owner: WorkflowStateMutationOwner;
+    mutation_id: string;
+    from_phase?: string;
+    to_phase?: string;
+    forced: boolean;
+    paths: string[];
 }
 export declare function workflowModeStateFileName(skill: CanonicalGjcWorkflowSkill): string;
 export declare function workflowStateStoragePath(cwd: string, skill: CanonicalGjcWorkflowSkill, sessionId?: string): string;

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

@@ -29,6 +29,9 @@ export interface ExecutorOptions {
     index: number;
     id: string;
     modelOverride?: string | string[];
+    runMode?: "initial" | "resume" | "message";
+    resumeMessage?: string;
+    subagentId?: string;
     /**
      * Active model selector of the parent session, used as an auth-aware fallback
      * if the resolved subagent model has no working credentials. See #985.

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

@@ -32,7 +32,7 @@ export interface SubagentLifecyclePayload {
     agent: string;
     agentSource: AgentSource;
     description?: string;
-    status: "started" | "completed" | "failed" | "aborted";
+    status: "started" | "completed" | "failed" | "aborted" | "paused";
     sessionFile?: string;
     index: number;
 }
@@ -171,7 +171,7 @@ export interface AgentProgress {
     id: string;
     agent: string;
     agentSource: AgentSource;
-    status: "pending" | "running" | "completed" | "failed" | "aborted";
+    status: "pending" | "running" | "completed" | "failed" | "aborted" | "paused";
     task: string;
     assignment?: string;
     description?: string;
@@ -213,6 +213,7 @@ export interface AgentProgress {
     retryState?: {
         attempt: number;
         maxAttempts: number;
+        unbounded?: boolean;
         delayMs: number;
         errorMessage: string;
         startedAtMs: number;
@@ -261,6 +262,7 @@ export interface SingleResult {
     error?: string;
     aborted?: boolean;
     abortReason?: string;
+    paused?: boolean;
     /** Aggregated usage from the subprocess, accumulated incrementally from message_end events. */
     usage?: Usage;
     /** Output path for the task result */
@@ -299,9 +301,59 @@ export interface TaskToolDetails {
     outputPaths?: string[];
     progress?: AgentProgress[];
     async?: {
-        state: "running" | "completed" | "failed";
+        state: "running" | "paused" | "queued" | "completed" | "failed";
         jobId: string;
         type: "task";
     };
 }
+/**
+ * Persisted per-turn / per-subagent token record (Phase 0 instrumentation).
+ *
+ * Additive: this does not alter any existing task result shape. It is the
+ * durable, model-independent unit the deterministic orchestration-token
+ * benchmark (`@gajae-code/orchestration-token-benchmark`) consumes to measure
+ * token efficiency without any live-model calls.
+ */
+export interface TaskTokenLog {
+    /** Subagent id, or "root" for the orchestrator's own turn. */
+    subagentId: string;
+    /** Agent name for attribution, when known. */
+    agent?: string;
+    /** 1-based turn index within the subagent's session. */
+    turn: number;
+    /** ISO-8601 timestamp the turn completed. */
+    at: string;
+    /** Cost-bearing input tokens (excludes cache reads), mirrors `Usage.input`. */
+    input: number;
+    /** Total output tokens for the turn, mirrors `Usage.output`. */
+    output: number;
+    /** Tokens read from the prompt cache, mirrors `Usage.cacheRead`. */
+    cacheRead: number;
+    /** Tokens written to the prompt cache, mirrors `Usage.cacheWrite`. */
+    cacheWrite: number;
+    /** input + output + cacheRead + cacheWrite. */
+    totalTokens: number;
+    /** Latest per-turn context-window occupancy, when known. */
+    contextTokens?: number;
+    /** Estimated USD cost for the turn, when known. */
+    cost?: number;
+    /** Model id used for the turn, when known. */
+    model?: string;
+}
+/**
+ * Deterministic aggregate token metrics computed from a set of `TaskTokenLog`
+ * entries. The cache-hit-rate field is the primary prompt-cache signal called
+ * out by the prefix-stability invariant (see the approved plan).
+ */
+export interface TaskTokenMetrics {
+    /** Number of token-log entries aggregated. */
+    turns: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    /** cacheRead / (input + cacheRead); 0 when there is no input-class traffic. */
+    cacheHitRate: number;
+}
 export {};

package/dist/types/tools/subagent.d.ts

@@ -8,13 +8,18 @@ declare const subagentSchema: z.ZodObject<{
         cancel: "cancel";
         inspect: "inspect";
         list: "list";
+        pause: "pause";
+        resume: "resume";
+        steer: "steer";
     }>;
     ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    message: z.ZodOptional<z.ZodString>;
+    pause: z.ZodOptional<z.ZodBoolean>;
     timeout_ms: z.ZodOptional<z.ZodNumber>;
     limit: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 type SubagentParams = z.infer<typeof subagentSchema>;
-type SubagentStatus = "running" | "completed" | "failed" | "cancelled" | "not_found" | "already_completed";
+type SubagentStatus = "running" | "paused" | "queued" | "completed" | "failed" | "cancelled" | "not_found" | "already_completed";
 export interface SubagentSnapshot {
     id: string;
     jobId: string;
@@ -45,8 +50,13 @@ export declare class SubagentTool implements AgentTool<typeof subagentSchema, Su
             cancel: "cancel";
             inspect: "inspect";
             list: "list";
+            pause: "pause";
+            resume: "resume";
+            steer: "steer";
         }>;
         ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        message: z.ZodOptional<z.ZodString>;
+        pause: z.ZodOptional<z.ZodBoolean>;
         timeout_ms: z.ZodOptional<z.ZodNumber>;
         limit: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.2.5",
+	"version": "0.3.0",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -48,12 +48,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.2.5",
-		"@gajae-code/agent-core": "0.2.5",
-		"@gajae-code/ai": "0.2.5",
-		"@gajae-code/natives": "0.2.5",
-		"@gajae-code/tui": "0.2.5",
-		"@gajae-code/utils": "0.2.5",
+		"@gajae-code/stats": "0.3.0",
+		"@gajae-code/agent-core": "0.3.0",
+		"@gajae-code/ai": "0.3.0",
+		"@gajae-code/natives": "0.3.0",
+		"@gajae-code/tui": "0.3.0",
+		"@gajae-code/utils": "0.3.0",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",