@gajae-code/coding-agent 0.2.4 → 0.3.0

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

@@ -251,11 +251,7 @@ export declare function stopThemeWatcher(): void;
  * Used by HTML export to generate CSS custom properties.
  */
 export declare function getResolvedThemeColors(themeName?: string): Promise<Record<string, string>>;
-/**
- * Check if a theme is a "light" theme by analyzing its background color luminance.
- * Loads theme JSON synchronously (built-in or custom file) and resolves userMessageBg.
- */
-export declare function isLightTheme(themeName?: string): boolean;
+export declare function isLightTheme(themeName?: string, agentDir?: string): boolean;
 /**
  * Get explicit export colors from theme JSON, if specified.
  * Returns undefined for each color that isn't explicitly set.

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

@@ -70,6 +70,7 @@ export interface InteractiveModeContext {
     isInitialized: boolean;
     isBackgrounded: boolean;
     isBashMode: boolean;
+    isBashNoContext: boolean;
     toolOutputExpanded: boolean;
     todoExpanded: boolean;
     planModeEnabled: boolean;
@@ -92,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

@@ -99,6 +99,8 @@ export interface CreateAgentSessionOptions {
     agentId?: string;
     /** Display name for the agent in IRC. Default: "main" or "sub". */
     agentDisplayName?: string;
+    /** Optional restricted bash command prefixes for read-only role agents. */
+    bashAllowedPrefixes?: string[];
     /** Optional shared agent registry for IRC routing. Default: AgentRegistry.global(). */
     agentRegistry?: AgentRegistry;
     /** Parent task ID prefix for nested artifact naming (e.g., "6-Extensions") */
@@ -125,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/session/streaming-output.d.ts

@@ -41,6 +41,17 @@ export interface OutputSinkOptions {
     onChunk?: (chunk: string) => void;
     /** Minimum ms between onChunk calls. 0 = every chunk (default). */
     chunkThrottleMs?: number;
+    /**
+     * Unthrottled per-chunk callback fired *after* sanitization but *before*
+     * any throttle gating, column capping, or head/tail bookkeeping. Used by
+     * background-job substrate to record the complete process stream for the
+     * Monitor tool while keeping `onChunk` cheap for UI/progress.
+     *
+     * Receives the sanitized chunk verbatim; never receives the column-capped
+     * or minimized text. Implementations must be fast and side-effect-free
+     * relative to the sink (the sink does not catch errors from this callback).
+     */
+    onRawChunk?: (chunk: string) => void;
 }
 export interface TruncationResult {
     content: string;

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;
 }
@@ -74,6 +76,7 @@ export declare function isCanonicalGjcWorkflowSkill(skill: string): skill is Can
 export declare function listActiveSkills(raw: unknown): SkillActiveEntry[];
 export declare function normalizeSkillActiveState(raw: unknown): SkillActiveState | null;
 export declare function getSkillActiveStatePaths(cwd: string, sessionId?: string): SkillActiveStatePaths;
+export declare function collapsePlanningPipeline(entries: readonly SkillActiveEntry[]): SkillActiveEntry[];
 export declare function readVisibleSkillActiveState(cwd: string, sessionId?: string): Promise<SkillActiveState | null>;
 export declare function syncSkillActiveState(options: SyncSkillActiveStateOptions): Promise<void>;
 export interface ApplyHandoffOptions {

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;
 }
@@ -161,6 +161,7 @@ export interface AgentDefinition {
     autoloadSkills?: string[];
     hide?: boolean;
     forkContext?: ForkContextPolicy;
+    bashAllowedPrefixes?: string[];
     source: AgentSource;
     filePath?: string;
 }
@@ -170,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;
@@ -212,6 +213,7 @@ export interface AgentProgress {
     retryState?: {
         attempt: number;
         maxAttempts: number;
+        unbounded?: boolean;
         delayMs: number;
         errorMessage: string;
         startedAtMs: number;
@@ -260,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 */
@@ -298,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/bash-allowed-prefixes.d.ts

@@ -0,0 +1,5 @@
+export interface BashAllowedPrefixesCheck {
+    allowed: boolean;
+    reason?: string;
+}
+export declare function checkBashAllowedPrefixes(command: string, allowedPrefixes: readonly string[] | undefined): BashAllowedPrefixesCheck;

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

@@ -59,6 +59,30 @@ export declare class BashTool implements AgentTool<BashToolSchema, BashToolDetai
     readonly concurrency = "exclusive";
     readonly strict = true;
     constructor(session: ToolSession);
+    /**
+     * Start a background bash job for the Monitor tool. Reuses the full Bash
+     * pipeline (interceptors, internal-URL expansion, env, cwd, timeout); the
+     * public `monitor` tool itself is ACP-gated by `AgentSession` before this
+     * helper is called. The caller-supplied `onRawLine` callback is invoked once
+     * per newline-terminated stdout chunk, between turns, so the upstream Claude
+     * Code "Each stdout line is a task-notification event" semantics are preserved
+     * through the agent's existing background-task delivery path.
+     */
+    startMonitorJob(input: {
+        command: string;
+        cwd?: string;
+        timeout?: number;
+        env?: Record<string, string>;
+    }, opts?: {
+        ownerId?: string;
+        label?: string;
+        ctx?: AgentToolContext;
+        onRawLine?: (line: string, jobId: string) => void;
+    }): Promise<{
+        jobId: string;
+        label: string;
+        commandCwd: string;
+    }>;
     execute(_toolCallId: string, { command: rawCommand, env: rawEnv, timeout: rawTimeout, cwd, async: asyncRequested, pty }: BashToolInput, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<BashToolDetails>, ctx?: AgentToolContext): Promise<AgentToolResult<BashToolDetails>>;
 }
 export interface BashRenderArgs {

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

@@ -0,0 +1,110 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
+import * as z from "zod/v4";
+import type { ToolSession } from "./index";
+/** Maximum scheduled tasks per owner. Mirrors upstream Claude Code's 50-task cap. */
+export declare const MAX_CRON_TASKS_PER_OWNER = 50;
+/** Recurring tasks auto-expire 7 days after creation (mirrors upstream). */
+export declare const CRON_RECURRING_MAX_AGE_MS: number;
+declare const cronCreateSchema: z.ZodObject<{
+    cron_expression: z.ZodString;
+    prompt: z.ZodString;
+    recurring: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CronCreateParams = z.infer<typeof cronCreateSchema>;
+declare const cronListSchema: z.ZodObject<{}, z.core.$strip>;
+export type CronListParams = z.infer<typeof cronListSchema>;
+declare const cronDeleteSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type CronDeleteParams = z.infer<typeof cronDeleteSchema>;
+export interface CronJobSnapshot {
+    id: string;
+    cron_expression: string;
+    prompt: string;
+    recurring: boolean;
+    createdAt: number;
+    expiresAt?: number;
+    nextFireAt?: number;
+    humanSchedule: string;
+    ownerId?: string;
+}
+export interface CronListJobDetails {
+    id: string;
+    cron: string;
+    recurring: boolean;
+    prompt: string;
+    humanSchedule: string;
+}
+export interface CronCreateToolDetails {
+    id: string;
+    cron_expression: string;
+    recurring: boolean;
+    nextFireAt?: number;
+}
+export interface CronListToolDetails {
+    jobs: CronListJobDetails[];
+}
+export interface CronDeleteToolDetails {
+    id: string;
+    deleted: boolean;
+}
+/** Clear every schedule for an owner. Exported for tests + lifecycle teardown. */
+export declare function clearOwnerSchedules(ownerId: string | undefined): void;
+/** Reset every owner's schedule store. Test-only. */
+export declare function resetCronRegistryForTests(): void;
+export declare function validateCronExpression(expression: string): void;
+export declare function findNextCronMatchMs(expression: string, afterMs: number, deadlineMs?: number): number | undefined;
+export declare function calculateCronFireTimeMs(params: {
+    id: string;
+    cronExpression: string;
+    baseMatchMs: number;
+    recurring: boolean;
+    nowMs: number;
+    expiresAt?: number;
+}): number;
+export declare class CronCreateTool implements AgentTool<typeof cronCreateSchema, CronCreateToolDetails> {
+    private readonly session;
+    readonly name = "CronCreate";
+    readonly label = "CronCreate";
+    readonly summary = "Schedule a prompt on a 5-field cron expression";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        cron_expression: z.ZodString;
+        prompt: z.ZodString;
+        recurring: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): CronCreateTool | null;
+    execute(_toolCallId: string, params: CronCreateParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<CronCreateToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<CronCreateToolDetails>>;
+}
+export declare class CronListTool implements AgentTool<typeof cronListSchema, CronListToolDetails> {
+    private readonly session;
+    readonly name = "CronList";
+    readonly label = "CronList";
+    readonly summary = "List scheduled cron jobs";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{}, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): CronListTool | null;
+    execute(_toolCallId: string, _params: CronListParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<CronListToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<CronListToolDetails>>;
+}
+export declare class CronDeleteTool implements AgentTool<typeof cronDeleteSchema, CronDeleteToolDetails> {
+    private readonly session;
+    readonly name = "CronDelete";
+    readonly label = "CronDelete";
+    readonly summary = "Cancel a scheduled cron job by ID";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): CronDeleteTool | null;
+    execute(_toolCallId: string, params: CronDeleteParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<CronDeleteToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<CronDeleteToolDetails>>;
+}
+export {};

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

@@ -32,6 +32,7 @@ export * from "./bash";
 export * from "./browser";
 export * from "./calculator";
 export * from "./checkpoint";
+export * from "./cron";
 export * from "./debug";
 export * from "./eval";
 export * from "./find";
@@ -43,6 +44,7 @@ export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
 export * from "./job";
+export * from "./monitor";
 export * from "./read";
 export * from "./recipe";
 export * from "./render-mermaid";
@@ -118,6 +120,8 @@ export interface ToolSession {
     getToolByName?: (name: string) => AgentTool | undefined;
     /** Agent registry for IRC routing across live sessions. */
     agentRegistry?: AgentRegistry;
+    /** Optional restricted bash command prefixes for read-only role agents. */
+    bashAllowedPrefixes?: string[];
     /** Get artifacts directory for artifact:// URLs */
     getArtifactsDir?: () => string | null;
     /** Get the ArtifactManager backing this session (shared across parent + subagents). */

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

@@ -0,0 +1,54 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
+import * as z from "zod/v4";
+import type { ToolSession } from "./index";
+declare const monitorKindEnum: z.ZodEnum<{
+    log: "log";
+    other: "other";
+    poll: "poll";
+    watch: "watch";
+}>;
+declare const monitorSchema: z.ZodObject<{
+    command: z.ZodString;
+    kind: z.ZodEnum<{
+        log: "log";
+        other: "other";
+        poll: "poll";
+        watch: "watch";
+    }>;
+    description: z.ZodString;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    persistent: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type MonitorParams = z.infer<typeof monitorSchema>;
+export interface MonitorToolDetails {
+    taskId: string;
+    kind: z.infer<typeof monitorKindEnum>;
+    description: string;
+    command: string;
+    persistent: boolean;
+}
+export declare class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolDetails> {
+    private readonly session;
+    readonly name = "monitor";
+    readonly label = "Monitor";
+    readonly summary = "Start a background monitor that streams stdout lines as task notifications";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        command: z.ZodString;
+        kind: z.ZodEnum<{
+            log: "log";
+            other: "other";
+            poll: "poll";
+            watch: "watch";
+        }>;
+        description: z.ZodString;
+        timeout: z.ZodOptional<z.ZodNumber>;
+        persistent: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): MonitorTool | null;
+    execute(_toolCallId: string, params: MonitorParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<MonitorToolDetails>, context?: AgentToolContext): Promise<AgentToolResult<MonitorToolDetails>>;
+}
+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/dist/types/web/search/index.d.ts

@@ -40,6 +40,7 @@ export declare function runSearchQuery(params: SearchQueryParams, options?: {
     authStorage?: AuthStorage;
     sessionId?: string;
     signal?: AbortSignal;
+    activeModelProvider?: string;
 }): Promise<{
     content: Array<{
         type: "text";

package/dist/types/web/search/provider.d.ts

@@ -14,8 +14,15 @@ export declare const SEARCH_PROVIDER_ORDER: SearchProviderId[];
 /** Set the preferred web search provider from settings */
 export declare function setPreferredSearchProvider(provider: SearchProviderId | "auto"): void;
 /**
- * Determine which providers are configured and currently available.
- * Each candidate is loaded (and its `isAvailable()` called) only as the chain
- * is walked, so unconfigured providers never pay the load cost.
+ * Resolve the ordered provider chain for a search request.
+ *
+ * Resolution is active-model-gated, never credential-scanning:
+ *   1. An explicitly preferred provider (settings) that is available is primary.
+ *   2. Otherwise the active model's own native search is primary, but only when
+ *      that provider's own credentials are present (its `isAvailable()`).
+ *   3. DuckDuckGo (keyless) is always appended as the terminal fallback, so a
+ *      missing primary — or a primary runtime failure — still returns results
+ *      with zero configuration. Keyed standalone providers are never
+ *      auto-selected; they are reachable only via explicit selection (step 1).
  */
-export declare function resolveProviderChain(authStorage: AuthStorage, preferredProvider?: SearchProviderId | "auto"): Promise<SearchProvider[]>;
+export declare function resolveProviderChain(authStorage: AuthStorage, preferredProvider?: SearchProviderId | "auto", activeModelProvider?: string): Promise<SearchProvider[]>;

package/dist/types/web/search/providers/duckduckgo.d.ts

@@ -0,0 +1,57 @@
+/**
+ * DuckDuckGo Web Search Provider
+ *
+ * Keyless, permissionless web search. Scrapes DuckDuckGo's no-JavaScript HTML
+ * endpoints and maps anchors/snippets into the unified SearchResponse shape
+ * (sources only — DuckDuckGo does not synthesize an answer).
+ *
+ * This is the zero-config default/fallback backend: it requires no API key and
+ * no OAuth, so `isAvailable()` is always true. Because DuckDuckGo applies
+ * anti-bot rate limiting (HTTP 202 / 403 / empty responses) from datacenter and
+ * VPN IPs, the provider is best-effort: it retries with backoff, rotates the
+ * user-agent, and alternates between the `html` and `lite` endpoints. When every
+ * attempt fails it throws a {@link SearchProviderError} rather than returning an
+ * empty success — it never falls through to keyed providers.
+ *
+ * Endpoints:
+ *   https://html.duckduckgo.com/html/  (primary)
+ *   https://lite.duckduckgo.com/lite/  (fallback markup)
+ *
+ * The HTML markup is liable to drift; the parser is deliberately small and is
+ * pinned by fixture-driven tests (see test/tools/web-search-duckduckgo.test.ts).
+ */
+import type { AuthStorage } from "@gajae-code/ai";
+import type { SearchResponse } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+interface ParsedResult {
+    title: string;
+    url: string;
+    snippet?: string;
+}
+/**
+ * Resolve a DuckDuckGo result href to the real destination URL. DuckDuckGo wraps
+ * external links in a `/l/?uddg=<encoded>` redirect; `lite` sometimes links
+ * directly. Returns null for unusable or internal links (so ads/redirect shells
+ * are dropped).
+ */
+export declare function decodeResultUrl(href: string): string | null;
+/** Parse results from the `html.duckduckgo.com/html/` markup. */
+export declare function parseHtmlResults(html: string): ParsedResult[];
+/** Parse results from the `lite.duckduckgo.com/lite/` markup. */
+export declare function parseLiteResults(html: string): ParsedResult[];
+/** Execute a keyless DuckDuckGo web search with light resilience. */
+export declare function searchDuckDuckGo(params: {
+    query: string;
+    num_results?: number;
+    recency?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}): Promise<SearchResponse>;
+/** Keyless, permissionless web search provider backed by DuckDuckGo. */
+export declare class DuckDuckGoProvider extends SearchProvider {
+    readonly id = "duckduckgo";
+    readonly label = "DuckDuckGo";
+    isAvailable(_authStorage: AuthStorage): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+export {};

package/dist/types/web/search/types.d.ts

@@ -4,7 +4,7 @@
  * Unified types for web search responses across supported providers.
  */
 /** Supported web search providers */
-export type SearchProviderId = "exa" | "brave" | "jina" | "kimi" | "zai" | "anthropic" | "perplexity" | "gemini" | "codex" | "tavily" | "parallel" | "kagi" | "synthetic" | "searxng";
+export type SearchProviderId = "duckduckgo" | "exa" | "brave" | "jina" | "kimi" | "zai" | "anthropic" | "perplexity" | "gemini" | "codex" | "tavily" | "parallel" | "kagi" | "synthetic" | "searxng";
 export declare function isSearchProviderId(value: string): value is SearchProviderId;
 export declare function isSearchProviderPreference(value: string): value is SearchProviderId | "auto";
 /** Source returned by search (all providers) */