@gajae-code/coding-agent 0.4.1 → 0.4.3

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

@@ -0,0 +1,37 @@
+/**
+ * Canonical AgentSession event observation: the single semantic mapping from
+ * `AgentSessionEvent` (and non-event wire frames) to bounded owner observations.
+ *
+ * This is the one place that derives `AgentWireOwnerObservation`s. Harness (and
+ * any other owner control plane) consumes these instead of re-parsing the wire
+ * protocol with private knowledge.
+ *
+ * Hard rule: evidence is BOUNDED — only ids, names, categories, statuses,
+ * cursors, timestamps, and short codes/messages. Never assistant text, message
+ * deltas, command output, raw args, or raw tool results.
+ */
+import type { AgentSessionEvent } from "../../../session/agent-session";
+import type { AgentWireEventPayload, AgentWireOwnerObservation } from "./event-contract";
+import { toAgentWireEventPayload } from "./event-envelope";
+/** True when a tool name or command indicates a test-runner invocation. */
+export declare function isTestRunnerTool(toolName?: unknown, command?: unknown): boolean;
+/** Only accept a known closed-vocabulary tool status; reject arbitrary strings. */
+export declare function boundedStatus(v: unknown): string | undefined;
+/** Accept only identifier-shaped tokens (e.g. RPC command names); reject free text. */
+export declare function boundedToken(v: unknown): string | undefined;
+/**
+ * Map a single `AgentSessionEvent` to its bounded owner observation, or null
+ * when the event carries no owner-facing signal.
+ */
+export declare function observeAgentSessionEvent(event: AgentSessionEvent): AgentWireOwnerObservation | null;
+/** Build the rich event payload (renderer-facing) for an `AgentSessionEvent`. */
+export { toAgentWireEventPayload };
+/** Observe the bounded owner signal carried by a rich event payload. */
+export declare function observeAgentWireEventPayload(payload: AgentWireEventPayload): AgentWireOwnerObservation | null;
+/**
+ * Map a single outbound RPC wire frame (docs/rpc.md) to a bounded owner
+ * observation, or null when the frame carries no owner-facing signal. Event
+ * frames delegate to {@link observeAgentWireEventPayload}; non-event frames are
+ * mapped here so owners never re-parse protocol semantics privately.
+ */
+export declare function observeRpcOutboundFrame(frame: Record<string, unknown>): AgentWireOwnerObservation | null;

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

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

package/dist/types/reminders/star-reminder.d.ts

@@ -0,0 +1,115 @@
+import type { ImageContent } from "@gajae-code/ai";
+import type { CustomMessage } from "../session/messages";
+export declare const STAR_REMINDER_REPO = "Yeachan-Heo/gajae-code";
+export declare const STAR_REMINDER_CUSTOM_TYPE = "star-reminder";
+export declare const STARRED_CACHE_TTL_MS: number;
+export interface StarReminderState {
+    declined: boolean;
+    starred: boolean;
+    /** ISO-8601 timestamp of the last authoritative star check, or "" if never. */
+    starredCheckedAt: string;
+}
+export type StarCheckStatus = "starred" | "unstarred" | "unavailable";
+export interface GhResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+export type RunGh = (args: string[], options?: {
+    timeoutMs?: number;
+}) => Promise<GhResult>;
+export interface StarReminderDeps {
+    statePath?: string;
+    now?: () => Date;
+    runGh?: RunGh;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function getStarReminderStatePath(): string;
+export declare function defaultStarReminderState(): StarReminderState;
+/** Read state without locking. Missing or malformed files return the default. */
+export declare function readStarReminderStateUnlocked(statePath?: string): Promise<StarReminderState>;
+/** Whether a stored `starred:true` is still within the 24h cache window. */
+export declare function isStarredCacheFresh(state: StarReminderState, now?: Date): boolean;
+/**
+ * Lock-protected read-modify-write. The mutator receives the freshly re-read
+ * state under the lock; callers MUST base monotonic decisions on that value,
+ * not on any snapshot captured before the lock was held.
+ */
+export declare function updateStarReminderStateLocked(mutator: (current: StarReminderState) => StarReminderState | Promise<StarReminderState>, deps?: StarReminderDeps): Promise<StarReminderState>;
+/** A successful PUT is authoritative: always record starred and clear declined. */
+export declare function recordStarredFromPut(deps?: StarReminderDeps): Promise<StarReminderState>;
+/**
+ * Record the result of a fresh `gh` star check performed by this operation.
+ * - "starred": authoritative, clears declined so all reminders stop.
+ * - "unstarred": may downgrade, but only when the current state is not a
+ *   still-fresh confirmed star (which a concurrent process may have just
+ *   written); in that case the fresher confirmation wins.
+ */
+export declare function recordFreshStarCheck(status: "starred" | "unstarred", deps?: StarReminderDeps): Promise<StarReminderState>;
+/** Record a launch-nudge decline. Never downgrades a confirmed star. */
+export declare function recordDeclinedAfterNo(deps?: StarReminderDeps): Promise<StarReminderState>;
+/** Default `gh` runner. Returns an unavailable-style result instead of throwing. */
+export declare function runGhDefault(args: string[], options?: {
+    timeoutMs?: number;
+}): Promise<GhResult>;
+/** Classify the star state of the repo via `gh api`. */
+export declare function checkGhStarred(deps?: StarReminderDeps): Promise<StarCheckStatus>;
+/** Star the repo via `gh api -X PUT`. Returns whether the PUT succeeded. */
+export declare function autoStarRepo(deps?: StarReminderDeps): Promise<boolean>;
+/**
+ * Determine the star state for this session, hitting `gh` only when needed.
+ * A fresh cached star skips `gh`; unstarred and declined states are rechecked.
+ * Authoritative results are persisted via the monotonic helpers.
+ */
+export declare function refreshStarStateForSession(deps?: StarReminderDeps): Promise<StarCheckStatus>;
+export interface StarReminderPromptUI {
+    /** Show a yes/no confirmation. Resolves true when the user accepts. */
+    confirm(title: string, message: string): Promise<boolean>;
+    /** Optional guard; when it returns false the nudge is skipped silently. */
+    isIdle?: () => boolean;
+}
+/**
+ * Run the launch nudge once. Caller is responsible for the `startup.quiet`,
+ * `starReminder.enabled`, and true-interactive gates. All errors are swallowed
+ * so the launch path can never be broken by the reminder.
+ */
+export declare function maybeShowLaunchStarReminder(ui: StarReminderPromptUI, deps?: StarReminderDeps): Promise<void>;
+/**
+ * Schedule the launch nudge to run after the first render so the networked
+ * `gh` check never blocks startup. Returns immediately.
+ */
+export declare function scheduleLaunchStarReminderAfterFirstRender(ui: StarReminderPromptUI, deps?: StarReminderDeps): void;
+export interface StarReminderLaunchGateInput {
+    /** The `starReminder.enabled` setting. */
+    enabled: boolean;
+    /** The `startup.quiet` setting. */
+    quiet: boolean;
+}
+export interface StarReminderLaunchGate {
+    /** Whether to register the decline-driven injection contributor. */
+    register: boolean;
+    /** Whether to schedule the launch nudge after first render. */
+    schedule: boolean;
+}
+/**
+ * Pure decision for interactive wiring. The injection contributor is registered
+ * whenever the feature is enabled; the launch nudge is additionally suppressed
+ * by quiet startup. Centralizing this keeps the interactive gate testable.
+ */
+export declare function starReminderLaunchGate(input: StarReminderLaunchGateInput): StarReminderLaunchGate;
+export interface StarReminderSessionRef {
+    getSessionId(): string | undefined;
+}
+export type StarReminderCustomMessage = Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">;
+export type InternalBeforeAgentStartContributor = (event: {
+    prompt: string;
+    images?: ImageContent[];
+    sessionId: string | undefined;
+}) => Promise<StarReminderCustomMessage | undefined>;
+export declare function createStarReminderMessage(): StarReminderCustomMessage;
+/**
+ * Build a before-agent-start contributor that injects the persuasion message
+ * once per logical session id, for declined-and-still-unstarred users only.
+ */
+export declare function createStarReminderBeforeAgentStartContributor(session: StarReminderSessionRef, deps?: StarReminderDeps): InternalBeforeAgentStartContributor;

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

@@ -25,6 +25,14 @@ export interface ForkContextSeedMetadata {
     maxTokens: number;
     skippedReasons: Record<string, number>;
 }
+export interface PurgeQueuedCustomMessagesResult {
+    agentSteering: number;
+    agentFollowUp: number;
+    pendingNextTurn: number;
+    displaySteering: number;
+    displayFollowUp: number;
+    totalExecutable: number;
+}
 export interface ForkContextSeed {
     messages: Message[];
     agentMessages: AgentMessage[];
@@ -294,6 +302,18 @@ export interface SessionStats {
     premiumRequests: number;
     cost: number;
 }
+/** A custom message contributed at the before-agent-start point. */
+export type BeforeAgentStartInternalMessage = Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">;
+/**
+ * Internal (first-party, non-user-hook) contributor invoked at the active
+ * before-agent-start point alongside the extension runner. Returns an optional
+ * custom message to append to the prompt context. Errors are nonfatal.
+ */
+export type BeforeAgentStartContributor = (event: {
+    prompt: string;
+    images?: ImageContent[];
+    sessionId: string | undefined;
+}) => Promise<BeforeAgentStartInternalMessage | undefined>;
 export declare class AgentSession {
     #private;
     readonly agent: Agent;
@@ -556,6 +576,7 @@ export declare class AgentSession {
      */
     followUp(text: string, images?: ImageContent[]): Promise<void>;
     queueDeferredMessage(message: CustomMessage): void;
+    queueDeferredMessageForTests(message: CustomMessage, triggerTurn?: boolean): void;
     /**
      * Send a custom message to the session. Creates a CustomMessageEntry.
      *
@@ -568,6 +589,8 @@ export declare class AgentSession {
         triggerTurn?: boolean;
         deliverAs?: "steer" | "followUp" | "nextTurn";
     }): Promise<void>;
+    /** Remove undelivered queued custom messages matching `predicate` from executable queues and tagged display mirrors. */
+    purgeQueuedCustomMessages(predicate: (message: CustomMessage) => boolean): PurgeQueuedCustomMessagesResult;
     /**
      * Send a user message to the agent.
      * When deliverAs is set, queue the message instead of starting a new turn.
@@ -671,7 +694,7 @@ export declare class AgentSession {
     /**
      * Cycle through configured role models in a fixed order.
      * Skips missing roles.
-     * @param roleOrder - Order of roles to cycle through (e.g., ["slow", "default", "smol"])
+     * @param roleOrder - Order of roles to cycle through (e.g., ["default"])
      * @param options - Optional settings: `temporary` to not persist to settings
      */
     cycleRoleModels(roleOrder: readonly string[], options?: {
@@ -991,6 +1014,12 @@ export declare class AgentSession {
      * Check if extensions have handlers for a specific event type.
      */
     hasExtensionHandlers(eventType: string): boolean;
+    /**
+     * Register a first-party internal before-agent-start contributor. Returns an
+     * unregister function. This is NOT user-facing hook discovery; it is an
+     * in-core seam invoked alongside the extension runner.
+     */
+    registerBeforeAgentStartContributor(contributor: BeforeAgentStartContributor): () => void;
     /**
      * Get the extension runner (for setting UI context and error handlers).
      */

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

@@ -38,7 +38,7 @@ export interface ModelChangeEntry extends SessionEntryBase {
     type: "model_change";
     /** Model in "provider/modelId" format */
     model: string;
-    /** Role: "default", "smol", "slow", etc. Undefined treated as "default" */
+    /** Role: "default" or an agent role. Undefined treated as "default" */
     role?: string;
 }
 export interface ServiceTierChangeEntry extends SessionEntryBase {

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

@@ -78,6 +78,8 @@ export declare class BashTool implements AgentTool<BashToolSchema, BashToolDetai
         label?: string;
         ctx?: AgentToolContext;
         onRawLine?: (line: string, jobId: string) => void;
+        shouldAcceptRawLine?: (jobId: string) => boolean;
+        lifecycle?: import("../async").AsyncJobLifecycleCleanup;
     }): Promise<{
         jobId: string;
         label: string;

package/dist/types/tools/browser/actions.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Structured browser action space.
+ *
+ * Adapts the SOTA computer-use / browser-use pattern: instead of authoring raw
+ * JavaScript for every interaction, the model emits a list of structured verbs
+ * (navigate / click / type / …) that reference elements by the numeric `id`
+ * returned from {@link Observation}. Each verb is compiled onto the existing
+ * in-tab `tab.*` helpers and executed through the same worker `run` path, so the
+ * worker protocol is unchanged and the raw-JS `run` escape hatch still works.
+ */
+export type BrowserActionVerb = "navigate" | "click" | "type" | "fill" | "select" | "press" | "scroll" | "back" | "wait" | "observe" | "extract" | "screenshot";
+export interface BrowserActionStep {
+    verb: BrowserActionVerb;
+    /** Element id from a prior `observe` (preferred for click/type). */
+    id?: number;
+    /** CSS / puppeteer selector when not addressing by `id`. */
+    selector?: string;
+    /** Text to type. */
+    text?: string;
+    /** Value for `fill`. */
+    value?: string;
+    /** Option value(s) for `select`. */
+    values?: string[];
+    /** URL for `navigate`. */
+    url?: string;
+    /** Key for `press` (e.g. "Enter"). */
+    key?: string;
+    /** Horizontal scroll delta. */
+    dx?: number;
+    /** Vertical scroll delta. */
+    dy?: number;
+    /** Sleep duration for `wait` when no selector is given. */
+    ms?: number;
+    /** Extract format. */
+    format?: "markdown" | "text" | "html";
+    /** Navigation wait condition for `navigate`. */
+    wait_until?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+    /** Only return interactive/viewport elements for `observe`. */
+    viewport_only?: boolean;
+    include_all?: boolean;
+}
+/**
+ * Validate a single step's required fields. Returns an error string, or
+ * `undefined` when the step is well-formed.
+ */
+export declare function validateActionStep(step: BrowserActionStep, index: number): string | undefined;
+/** Validate the full step list. Throws on the first invalid step. */
+export declare function validateActionSteps(steps: readonly BrowserActionStep[]): void;
+/**
+ * Compile structured steps into a JS program for the in-tab `run` worker. Steps
+ * are embedded as parsed JSON (no string interpolation, so values cannot inject
+ * code) and dispatched by a fixed interpreter against the `tab` / `page` helpers.
+ */
+export declare function compileActionSteps(steps: readonly BrowserActionStep[]): string;

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

@@ -8,6 +8,7 @@ export { extractReadableFromHtml, type ReadableFormat, type ReadableResult } fro
 export type { Observation, ObservationEntry } from "./browser/tab-protocol";
 declare const browserSchema: z.ZodObject<{
     action: z.ZodEnum<{
+        act: "act";
         close: "close";
         open: "open";
         run: "run";
@@ -36,6 +37,45 @@ declare const browserSchema: z.ZodObject<{
         dismiss: "dismiss";
     }>>;
     code: z.ZodOptional<z.ZodString>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        verb: z.ZodEnum<{
+            back: "back";
+            click: "click";
+            extract: "extract";
+            fill: "fill";
+            navigate: "navigate";
+            observe: "observe";
+            press: "press";
+            screenshot: "screenshot";
+            scroll: "scroll";
+            select: "select";
+            type: "type";
+            wait: "wait";
+        }>;
+        id: z.ZodOptional<z.ZodNumber>;
+        selector: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        url: z.ZodOptional<z.ZodString>;
+        key: z.ZodOptional<z.ZodString>;
+        dx: z.ZodOptional<z.ZodNumber>;
+        dy: z.ZodOptional<z.ZodNumber>;
+        ms: z.ZodOptional<z.ZodNumber>;
+        format: z.ZodOptional<z.ZodEnum<{
+            html: "html";
+            markdown: "markdown";
+            text: "text";
+        }>>;
+        wait_until: z.ZodOptional<z.ZodEnum<{
+            domcontentloaded: "domcontentloaded";
+            load: "load";
+            networkidle0: "networkidle0";
+            networkidle2: "networkidle2";
+        }>>;
+        viewport_only: z.ZodOptional<z.ZodBoolean>;
+        include_all: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
     timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     all: z.ZodOptional<z.ZodBoolean>;
     kill: z.ZodOptional<z.ZodBoolean>;
@@ -73,6 +113,7 @@ export declare class BrowserTool implements AgentTool<typeof browserSchema, Brow
     readonly summary = "Control a headless browser to navigate and interact with web pages";
     readonly parameters: z.ZodObject<{
         action: z.ZodEnum<{
+            act: "act";
             close: "close";
             open: "open";
             run: "run";
@@ -101,6 +142,45 @@ export declare class BrowserTool implements AgentTool<typeof browserSchema, Brow
             dismiss: "dismiss";
         }>>;
         code: z.ZodOptional<z.ZodString>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            verb: z.ZodEnum<{
+                back: "back";
+                click: "click";
+                extract: "extract";
+                fill: "fill";
+                navigate: "navigate";
+                observe: "observe";
+                press: "press";
+                screenshot: "screenshot";
+                scroll: "scroll";
+                select: "select";
+                type: "type";
+                wait: "wait";
+            }>;
+            id: z.ZodOptional<z.ZodNumber>;
+            selector: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodString>;
+            values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            url: z.ZodOptional<z.ZodString>;
+            key: z.ZodOptional<z.ZodString>;
+            dx: z.ZodOptional<z.ZodNumber>;
+            dy: z.ZodOptional<z.ZodNumber>;
+            ms: z.ZodOptional<z.ZodNumber>;
+            format: z.ZodOptional<z.ZodEnum<{
+                html: "html";
+                markdown: "markdown";
+                text: "text";
+            }>>;
+            wait_until: z.ZodOptional<z.ZodEnum<{
+                domcontentloaded: "domcontentloaded";
+                load: "load";
+                networkidle0: "networkidle0";
+                networkidle2: "networkidle2";
+            }>>;
+            viewport_only: z.ZodOptional<z.ZodBoolean>;
+            include_all: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
         timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
         all: z.ZodOptional<z.ZodBoolean>;
         kill: z.ZodOptional<z.ZodBoolean>;

package/dist/types/tools/image-gen.d.ts

@@ -72,6 +72,7 @@ interface InlineImageData {
 }
 /** Set the preferred image provider from settings */
 export declare function setPreferredImageProvider(provider: ImageProvider | "auto"): void;
+export declare function isOpenAIHostedImageModel(model: Model | undefined): model is Model;
 export declare const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails>;
 export declare function getImageGenTools(modelRegistry?: ModelRegistry, activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
 export declare function getImageGenToolsWithRegistry(modelRegistry: ModelRegistry, activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;

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

@@ -8,7 +8,7 @@ import type { HindsightSessionState } from "../hindsight/state";
 import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/unattended-session";
 import type { PlanModeState } from "../plan-mode/state";
 import type { AgentRegistry } from "../registry/agent-registry";
-import type { ForkContextSeed, ForkContextSeedOptions } from "../session/agent-session";
+import type { ForkContextSeed, ForkContextSeedOptions, PurgeQueuedCustomMessagesResult } from "../session/agent-session";
 import type { ArtifactManager } from "../session/artifacts";
 import type { ClientBridge } from "../session/client-bridge";
 import type { CustomMessage } from "../session/messages";
@@ -117,6 +117,8 @@ export interface ToolSession {
     /** Agent identity used for IRC routing. Returns the registry id (e.g. "0-Main", "0-AuthLoader"). */
     getAgentId?: () => string | null;
     /** Look up a registered tool by name (used by the eval js backend's tool bridge). */
+    /** Purge undelivered queued custom messages matching the predicate. Returns counts. */
+    purgeQueuedCustomMessages?: (predicate: (message: CustomMessage) => boolean) => PurgeQueuedCustomMessagesResult;
     getToolByName?: (name: string) => AgentTool | undefined;
     /** Agent registry for IRC routing across live sessions. */
     agentRegistry?: AgentRegistry;

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

@@ -19,7 +19,7 @@ interface JobSnapshot {
     resultText?: string;
     errorText?: string;
 }
-type CancelStatus = "cancelled" | "not_found" | "already_completed";
+type CancelStatus = "cancelled" | "not_found" | "already_completed" | "already_cancelled";
 export interface JobToolDetails {
     jobs: JobSnapshot[];
     cancelled?: {

package/examples/extensions/README.md

@@ -5,57 +5,37 @@ Example extensions for gajae-code.
 ## Usage
 
 ```bash
-# Load an extension with --extension flag
-pi --extension examples/extensions/permission-gate.ts
+# Copy an existing extension into the user extension directory for auto-discovery
+mkdir -p ~/.gjc/agent/extensions
+cp packages/coding-agent/examples/extensions/hello.ts ~/.gjc/agent/extensions/
 
-# Or copy to extensions directory for auto-discovery
-cp permission-gate.ts ~/.gjc/agent/extensions/
+# Project-local extensions can live in .gjc/extensions/
+mkdir -p .gjc/extensions
+cp packages/coding-agent/examples/extensions/pirate.ts .gjc/extensions/
 ```
 
 ## Examples
 
-### Lifecycle & Safety
+### Custom Tools & API
 
-| Extension                | Description                                                                  |
-| ------------------------ | ---------------------------------------------------------------------------- |
-| `permission-gate.ts`     | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
-| `protected-paths.ts`     | Blocks writes to protected paths (.env, .git/, node_modules/)                |
-| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, branch)          |
-| `dirty-repo-guard.ts`    | Prevents session changes with uncommitted git changes                        |
-
-### Custom Tools
-
-| Extension     | Description                                                                   |
-| ------------- | ----------------------------------------------------------------------------- |
-| `todo.ts`     | Todo list tool + `/todos` command with custom rendering and state persistence |
-| `hello.ts`    | Minimal custom tool example                                                   |
-| `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions                  |
-| `subagent/`   | Delegate tasks to specialized subagents with isolated context windows         |
+| Extension     | Description                                                |
+| ------------- | ---------------------------------------------------------- |
+| `hello.ts`    | Minimal custom tool example                                |
+| `api-demo.ts` | Demonstrates logger access, injected `pi.zod`, and modules |
 
 ### Commands & UI
 
-| Extension        | Description                                                                    |
-| ---------------- | ------------------------------------------------------------------------------ |
-| `plan-mode.ts`   | Anthropic Code-style plan mode for read-only exploration with `/plan` command     |
-| `tools.ts`       | Interactive `/tools` command to enable/disable tools with session persistence  |
-| `handoff.ts`     | Transfer context to a new focused session via `/handoff <goal>`                |
-| `qna.ts`         | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
-| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors      |
-| `snake.ts`       | Snake game with custom UI, keyboard handling, and session persistence          |
-
-### Git Integration
-
-| Extension                | Description                                                               |
-| ------------------------ | ------------------------------------------------------------------------- |
-| `git-checkpoint.ts`      | Creates git stash checkpoints at each turn for code restoration on branch |
-| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message      |
+| Extension           | Description                                                                   |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `plan-mode.ts`      | Anthropic Code-style plan mode for read-only exploration with `/plan` command |
+| `tools.ts`          | Interactive `/tools` command to enable/disable tools with session persistence |
+| `reload-runtime.ts` | Adds a command and tool for reloading extensions, skills, prompts, and themes |
 
 ### System Prompt & Compaction
 
-| Extension              | Description                                                           |
-| ---------------------- | --------------------------------------------------------------------- |
-| `pirate.ts`            | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
-| `custom-compaction.ts` | Custom compaction that summarizes entire conversation                 |
+| Extension   | Description                                                          |
+| ----------- | -------------------------------------------------------------------- |
+| `pirate.ts` | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
 
 ### External Dependencies
 
@@ -63,11 +43,10 @@ cp permission-gate.ts ~/.gjc/agent/extensions/
 | ----------------- | ------------------------------------------------------------------------- |
 | `chalk-logger.ts` | Uses chalk from parent node_modules (demonstrates jiti module resolution) |
 | `with-deps/`      | Extension with its own package.json and dependencies                      |
-| `file-trigger.ts` | Watches a trigger file and injects contents into conversation             |
 
 ## Writing Extensions
 
-See [docs/extensions.md](../../docs/extensions.md) for full documentation.
+The examples below show the core extension patterns used by this directory.
 
 ```typescript
 import type { ExtensionAPI } from "@gajae-code/coding-agent";

package/package.json

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