@oh-my-pi-zen/pi-coding-agent 16.3.6-zen.1

package/dist/types/advisor/__tests__/advisor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/advisor/__tests__/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/advisor/__tests__/emission-guard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/advisor/advise-tool.d.ts

@@ -0,0 +1,106 @@
+import type { AgentIdentity, AgentTelemetryConfig, AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi-zen/pi-agent-core";
+declare const adviseSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    note: string;
+    severity?: "blocker" | "concern" | "nit" | undefined;
+}, {}>;
+export type AdviseParams = typeof adviseSchema.infer;
+export type AdvisorSeverity = "nit" | "concern" | "blocker";
+export interface AdviseDetails {
+    note: string;
+    severity?: AdvisorSeverity;
+    /** Which configured advisor produced this note (omitted for the default advisor). */
+    advisor?: string;
+}
+/** One queued advice note. */
+export interface AdvisorNote {
+    note: string;
+    severity?: AdvisorSeverity;
+    /** Which configured advisor produced this note (omitted for the default advisor). */
+    advisor?: string;
+}
+/** Details payload on the batched `advisor` custom message rendered in the transcript. */
+export interface AdvisorMessageDetails {
+    notes: AdvisorNote[];
+}
+/**
+ * Render a batch of advisor notes as the agent-facing message body: one
+ * `<advisory>` element per note, severity as an attribute. Shared by the
+ * non-interrupting YieldQueue dispatcher and the interrupting steer path so both
+ * build byte-identical content.
+ */
+export declare function formatAdvisorBatchContent(notes: readonly AdvisorNote[]): string;
+/**
+ * Whether advice at this severity should interrupt the running agent (delivered
+ * via the steering channel, aborting in-flight tools) rather than ride the
+ * non-interrupting aside queue that lands at the next step boundary. `concern`
+ * and `blocker` interrupt; a plain `nit` queues.
+ */
+export declare function isInterruptingSeverity(severity: AdvisorSeverity | undefined): boolean;
+/** How an advisor note is routed to the primary. */
+export type AdvisorDeliveryChannel = "aside" | "steer" | "preserve";
+/** Half-open turn-count fence for the post-interrupt cooldown. */
+export declare function isAdvisorInterruptImmuneTurnActive(opts: {
+    completedTurns: number;
+    immuneTurnStart: number | undefined;
+    immuneTurns: number;
+}): boolean;
+/**
+ * Decide how one advisor note reaches the primary agent.
+ *
+ * - A non-interrupting `nit` always rides the non-interrupting aside queue.
+ * - An interrupting `concern`/`blocker` is normally steered into the agent: into
+ *   the live turn while one is streaming, or (when idle) a triggered turn so the
+ *   advice is acted on immediately.
+ * - After a deliberate user interrupt (`autoResumeSuppressed`) the advisor must
+ *   not auto-resume the stopped run. While the agent is idle — or still tearing
+ *   the interrupted turn down (`aborting`) — the note is preserved as a visible
+ *   card instead of restarting the run. But once a turn is actively streaming
+ *   again (a resume the user already drove), steering the note in does NOT
+ *   auto-resume anything, so it is delivered live. Parking it during an active
+ *   run instead strands it (it never reaches the running agent) and the withheld
+ *   notes dump as one burst at the next user prompt — the bug this guards.
+ * - During the post-interrupt immune-turn window, further `concern`/`blocker`
+ *   notes are downgraded to asides; suppression preservation still wins.
+ */
+export declare function resolveAdvisorDeliveryChannel(opts: {
+    severity: AdvisorSeverity | undefined;
+    autoResumeSuppressed: boolean;
+    streaming: boolean;
+    aborting: boolean;
+    interruptImmuneTurnActive?: boolean;
+}): AdvisorDeliveryChannel;
+/**
+ * Derive the advisor loop's telemetry from the primary session's config so the
+ * advisor model's GenAI spans and usage/cost hooks (onChatUsage, onCostDelta,
+ * costEstimator) fire under the same pipeline as every other model call —
+ * stamped with the advisor's own agent identity. `conversationId` is cleared so
+ * the advisor loop falls back to its own `-advisor` session id for
+ * `gen_ai.conversation.id` instead of inheriting the primary's conversation.
+ *
+ * Returns undefined when the primary has no telemetry (instrumentation off), so
+ * the advisor `Agent` stays a zero-overhead no-op as well.
+ */
+export declare function deriveAdvisorTelemetry(primaryTelemetry: AgentTelemetryConfig | undefined, identity: AgentIdentity): AgentTelemetryConfig | undefined;
+/**
+ * The tools an advisor receives by default when its config omits `tools` — the
+ * read-only investigative set. The full available pool is every built tool the
+ * session has (the advisor is a full agent); a config's `tools` selects from it.
+ */
+export declare const ADVISOR_DEFAULT_TOOL_NAMES: ReadonlySet<string>;
+export declare class AdviseTool implements AgentTool<typeof adviseSchema, AdviseDetails> {
+    #private;
+    private readonly onAdvice;
+    readonly name = "advise";
+    readonly label = "Advise";
+    readonly description: string;
+    readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
+        note: string;
+        severity?: "blocker" | "concern" | "nit" | undefined;
+    }, {}>;
+    readonly intent: "omit";
+    constructor(onAdvice: (note: string, severity?: AdviseDetails["severity"]) => void);
+    /** Clear delivered-note memory when the advisor starts a fresh conversation. */
+    resetDeliveredNotes(): void;
+    execute(_toolCallId: string, args: AdviseParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<AdviseDetails>, _context?: AgentToolContext): Promise<AgentToolResult<AdviseDetails>>;
+}
+export {};

package/dist/types/advisor/config.d.ts

@@ -0,0 +1,90 @@
+/**
+ * One advisor declared in a `WATCHDOG.yml` file. `model` is a model selector
+ * with an optional `:level` thinking suffix (e.g. `x-ai/grok-code-fast:high`),
+ * resolved exactly like any other model override; `tools` is a subset of
+ * `BUILTIN_TOOL_NAMES` — any built-in name, including mutating tools such as
+ * `edit`/`write`/`bash` (the advisor is a full agent). Omitted or empty falls
+ * back to the default `read`/`grep`/`glob` subset. `instructions` is the
+ * advisor's specialization, appended to the shared baseline.
+ */
+export interface AdvisorConfig {
+    name: string;
+    model?: string;
+    tools?: string[];
+    instructions?: string;
+}
+/**
+ * The result of walking the `WATCHDOG.yml`/`WATCHDOG.yaml` search path: the
+ * deduped advisor roster plus the concatenated top-level `instructions` baseline
+ * that is prepended (alongside `WATCHDOG.md`) to every advisor.
+ */
+export interface DiscoveredAdvisors {
+    advisors: AdvisorConfig[];
+    sharedInstructions: string | undefined;
+}
+/**
+ * Normalize an advisor name into a filesystem-/id-safe slug used for its
+ * transcript filename and session id: lowercase, non-alphanumerics collapsed to
+ * `-`, leading/trailing `-` trimmed. Falls back to `"advisor"` when nothing
+ * survives; callers dedupe collisions.
+ */
+export declare function slugifyAdvisorName(name: string): string;
+/**
+ * Discover advisor configs from `WATCHDOG.yml`/`WATCHDOG.yaml` files on the same
+ * user + project search path as `WATCHDOG.md`. Advisors are keyed by slug; a
+ * more-specific file (project leaf > project ancestor > user) replaces an earlier
+ * entry with the same slug. Top-level `instructions` across all files concatenate
+ * into the shared baseline. A malformed file is logged and skipped — never
+ * thrown — so a bad project config can't kill the session.
+ */
+export declare function discoverAdvisorConfigs(cwd: string, agentDir?: string): Promise<DiscoveredAdvisors>;
+/** Which level a `WATCHDOG.yml` lives at: the project root or the user agent dir. */
+export type AdvisorConfigScope = "project" | "user";
+/**
+ * The editable contents of a single `WATCHDOG.yml` file: the shared top-level
+ * `instructions` plus the advisor roster. Unlike {@link DiscoveredAdvisors}, this
+ * is one file's raw view (no cross-level merge, no `@import` expansion) so the
+ * config editor round-trips exactly what the user wrote.
+ */
+export interface WatchdogConfigDoc {
+    instructions?: string;
+    advisors: AdvisorConfig[];
+}
+/**
+ * Resolve the `WATCHDOG.yml` path for a scope: `project` → `<projectDir>/WATCHDOG.yml`
+ * (discovered by the project-level walk), `user` → `<agentDir>/WATCHDOG.yml` (the
+ * user-level candidate).
+ */
+export declare function advisorConfigFilePath(scope: AdvisorConfigScope, dirs: {
+    projectDir: string;
+    agentDir: string;
+}): string;
+/**
+ * Resolve which `WATCHDOG.{yml,yaml}` to edit for a scope: prefer the canonical
+ * `.yml`, but when only a `.yaml` exists for that scope, edit it in place so an
+ * existing `.yaml` user isn't shown a blank editor and left with two files at the
+ * same precedence. Falls back to `.yml` when neither exists.
+ */
+export declare function resolveAdvisorConfigEditPath(scope: AdvisorConfigScope, dirs: {
+    projectDir: string;
+    agentDir: string;
+}): Promise<string>;
+/**
+ * Load one `WATCHDOG.yml` file for editing — raw, un-merged, un-expanded. Missing,
+ * unparseable, or schema-invalid files yield an empty doc (never throws) so the
+ * editor opens cleanly on a fresh or broken file.
+ */
+export declare function loadWatchdogConfigFile(filePath: string): Promise<WatchdogConfigDoc>;
+/**
+ * Serialize an editable doc back to block-style `WATCHDOG.yml` text via Bun's
+ * `YAML.stringify` (the same API the repo uses for other hand-editable config),
+ * omitting empty fields. Round-trips through {@link loadWatchdogConfigFile}.
+ * Returns `""` for an empty doc.
+ */
+export declare function serializeWatchdogConfig(doc: WatchdogConfigDoc): string;
+/**
+ * Write an editable doc to `WATCHDOG.yml`. An empty doc removes the file so
+ * discovery falls back to the legacy single-advisor path rather than leaving an
+ * empty config behind.
+ */
+export declare function saveWatchdogConfigFile(filePath: string, doc: WatchdogConfigDoc): Promise<void>;

package/dist/types/advisor/emission-guard.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Per-session policy gate for advisor `advise()` calls.
+ *
+ * The advisor system prompt tells the watcher model:
+ *
+ * > at most one `advise` per update
+ * > NEVER repeat advice you already gave, and NEVER send the same advice twice
+ *
+ * Real advisor models violate this. Issue #3520 captured a session where
+ * `__advisor.jsonl` recorded 309 `advise` calls covering 92 unique notes —
+ * 114× `Stop.`, 52× `No issue; continue.`, 41× `Done.` — flooding the primary
+ * transcript with `<advisory severity="blocker">Stop.</advisory>` after the
+ * task was already complete. The fix is to make the rules load-bearing in code
+ * instead of prose: silently drop duplicates, content-free self-talk, and
+ * over-budget calls at the `enqueueAdvice` boundary so the primary stays
+ * clean even when the advisor misbehaves.
+ *
+ * The gate is intentionally invisible to the advisor model — `AdviseTool`
+ * still returns `Recorded.` for a suppressed call. Surfacing "suppressed"
+ * back into advisor context risks the model rephrasing the same useless note
+ * to bypass the dedupe ("Stop.", then "Halt." then "Stop now.").
+ */
+/**
+ * Case-insensitive, punctuation-folded normalization. Collapses every run of
+ * non-letter / non-digit characters into a single space and trims, so
+ * `"Stop."`, `"*Stop*"`, and `"  stop  "` all key to `stop`, while
+ * `"No issue; continue."` keys to `no issue continue`.
+ *
+ * Exported for tests.
+ */
+export declare function normalizeAdvisorNote(note: string): string;
+/**
+ * Decides whether an advisor `advise()` call should reach the primary agent.
+ *
+ * Enforces — in this order — the noise filter, session-scoped exact-text
+ * dedupe (FIFO-evicted at {@link DEFAULT_HISTORY_CAPACITY}), and a per-update
+ * rate limit of one accepted note per advisor model prompt. Suppressed calls
+ * never consume the per-update budget — a noise call doesn't burn the slot
+ * for a real concern that follows in the same update.
+ *
+ * Reset on advisor reset (compaction, session switch, `/new`) via
+ * {@link reset}. Per-update gate is cleared at the start of every advisor
+ * `agent.prompt()` cycle via {@link beginUpdate}.
+ */
+export declare class AdvisorEmissionGuard {
+    #private;
+    constructor(opts?: {
+        capacity?: number;
+    });
+    /**
+     * Drop all dedupe and per-update state. Called from
+     * `AgentSession#resetAdvisorSessionState()` whenever the advisor runtime is
+     * reset — same boundary as `yieldQueue.clear("advisor")`, so a re-primed
+     * advisor can re-raise old issues (the primary transcript was rewritten).
+     */
+    reset(): void;
+    /**
+     * Clear the per-update rate-limit gate. Called by `AdvisorRuntime` right
+     * before each `agent.prompt(batch)` invocation so the next advisor model
+     * cycle starts with a fresh budget of one advise.
+     */
+    beginUpdate(): void;
+    /**
+     * Whether the proposed note should reach the primary. On `true` the gate
+     * has already recorded the note (consumed the per-update budget and added
+     * it to the dedupe history) — caller delivers the note. On `false` the
+     * caller drops it.
+     *
+     * Empty / whitespace-only notes are suppressed; the model's
+     * tool-args contract still requires a non-empty string but defense-in-depth.
+     */
+    accept(note: string): boolean;
+}

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

@@ -0,0 +1,6 @@
+export * from "./advise-tool";
+export * from "./config";
+export * from "./emission-guard";
+export * from "./runtime";
+export * from "./transcript-recorder";
+export * from "./watchdog";

package/dist/types/advisor/runtime.d.ts

@@ -0,0 +1,76 @@
+import type { AgentMessage } from "@oh-my-pi-zen/pi-agent-core";
+import { type SecretObfuscator } from "../secrets/obfuscator";
+/**
+ * Minimal slice of `Agent` the runtime drives — satisfied by pi-agent-core
+ * `Agent`. `state.error` mirrors `Agent.state.error`: provider/stream failures
+ * the loop catches internally never reject `prompt()`, so the runtime reads
+ * this field after every prompt to detect a failed turn.
+ */
+export interface AdvisorAgent {
+    prompt(input: string): Promise<void>;
+    abort(reason?: unknown): void;
+    reset(): void;
+    /**
+     * Drop messages appended past `count`. Called after a failed `prompt()` so a
+     * retry doesn't replay the failed user batch + synthetic assistant-error
+     * turn `Agent.#runLoop` records on its internal state.
+     */
+    rollbackTo?(count: number): void;
+    readonly state: {
+        messages: AgentMessage[];
+        error?: string;
+    };
+}
+export interface AdvisorRuntimeHost {
+    /** Live primary transcript (use `agent.state.messages`). */
+    snapshotMessages(): AgentMessage[];
+    /** Surface one advice note to the primary (enqueues into the session YieldQueue). */
+    enqueueAdvice(note: string, severity?: "nit" | "concern" | "blocker"): void;
+    /** Redact primary transcript bytes before they reach the advisor model. */
+    obfuscator?: SecretObfuscator;
+    /**
+     * Pre-prompt context maintenance for the advisor's own append-only context.
+     * Promotes the advisor model to a larger sibling when its context nears the
+     * window (mirroring the primary's promote-first policy) and resolves `true`
+     * when the advisor should re-prime — reset and replay the current
+     * primary-bounded transcript — because promotion did not free enough room.
+     * Optional: hosts that omit it get no maintenance (context only shrinks when
+     * the primary's next compaction triggers {@link AdvisorRuntime.reset}).
+     */
+    maintainContext?(incomingTokens: number): Promise<boolean>;
+    /**
+     * Called immediately before each `agent.prompt(batch)` cycle. Lets the host
+     * clear per-update advisor state — currently the one-advise-per-update gate
+     * in {@link AdvisorEmissionGuard}, which the host owns because it is the
+     * one that routes `advise()` results back to the primary.
+     */
+    beginAdvisorUpdate?(): void;
+    /** Surface a non-recovering advisor failure to the host UI without adding model-visible context. */
+    notifyFailure?(error: unknown): void;
+}
+export declare class AdvisorRuntime {
+    #private;
+    private readonly agent;
+    private readonly host;
+    private readonly retryDelayMs;
+    disposed: boolean;
+    constructor(agent: AdvisorAgent, host: AdvisorRuntimeHost, retryDelayMs?: number);
+    get backlog(): number;
+    onTurnEnd(messages?: AgentMessage[]): void;
+    waitForCatchup(maxMs: number, threshold: number, signal?: AbortSignal): Promise<void>;
+    dispose(): void;
+    /**
+     * Re-prime the advisor after a history rewrite (compaction, session
+     * switch/resume, branch). Clears the advisor's own (non-persisted) context
+     * and rewinds the cursor to 0 so the NEXT turn replays the full current —
+     * post-compaction — transcript, giving the advisor fresh context instead of
+     * leaving it blind to everything before the rewrite.
+     */
+    reset(): void;
+    /**
+     * Seed the cursor to the current transcript length when the advisor is enabled
+     * mid-session. Prevents the next turn from replaying the entire history to the
+     * advisor (which would be expensive and likely stale).
+     */
+    seedTo(count: number): void;
+}

package/dist/types/advisor/transcript-recorder.d.ts

@@ -0,0 +1,63 @@
+import type { AgentMessage } from "@oh-my-pi-zen/pi-agent-core";
+/**
+ * Reserved transcript stem for advisor session files. Chosen so it cannot
+ * collide with a task subagent's `<id>.jsonl` (task ids are reserved against
+ * this exact stem in {@link AgentOutputManager}).
+ */
+export declare const ADVISOR_TRANSCRIPT_STEM = "__advisor";
+export declare const ADVISOR_TRANSCRIPT_FILENAME = "__advisor.jsonl";
+/**
+ * Transcript filename for an advisor: `__advisor.jsonl` for the legacy/default
+ * advisor (empty slug), `__advisor.<slug>.jsonl` for a named advisor. The `.`
+ * separator keeps named files out of the output manager's `-<n>` bump namespace.
+ */
+export declare function advisorTranscriptFilename(slug: string): string;
+/** Whether a filename is any advisor transcript (`__advisor.jsonl` or `__advisor.<slug>.jsonl`). */
+export declare function isAdvisorTranscriptName(name: string): boolean;
+/**
+ * Append-only persister for an advisor agent's transcript.
+ *
+ * The advisor is a passive reviewer with its own model usage, so — like a task
+ * subagent — its turns are written to a JSONL inside the owning session's
+ * artifacts dir (`<session>/__advisor.jsonl`, `<session>/<SubId>/__advisor.jsonl`
+ * for subagent advisors). That single file gives the advisor model proper usage
+ * attribution in `omp stats` (the stats parser scans the session dir
+ * recursively) and a read-only transcript in the Agent Hub, without making the
+ * advisor a registered, messageable peer.
+ *
+ * The target is derived from the *session file* (`getSessionFile()`), never
+ * `getArtifactsDir()` — subagents adopt the parent's artifact manager, so the
+ * artifacts dir points at the parent root and every subagent advisor would
+ * collide. The file path is resolved synchronously when a message finalizes and
+ * captured for the queued write, so a `/new`, resume, or session switch in
+ * flight can never misattribute an old advisor turn into the new session's file.
+ * On such a switch the previous writer is closed and the new file opened on the
+ * next recorded turn. The recorder never truncates: the advisor's in-memory
+ * context resets/compacts independently, but every billed turn is appended here.
+ */
+export declare class AdvisorTranscriptRecorder {
+    #private;
+    private readonly resolveSessionFile;
+    private readonly resolveCwd;
+    /**
+     * @param filename Transcript filename within the session dir. Defaults to
+     *   `__advisor.jsonl`; named advisors pass `__advisor.<slug>.jsonl` via
+     *   {@link advisorTranscriptFilename}.
+     * @param after Optional barrier the queue starts behind — used on the advisor
+     *   on→off→on toggle so a fresh recorder's first `open` waits for the prior
+     *   recorder's `close` and the two never hold the same file at once.
+     */
+    constructor(resolveSessionFile: () => string | undefined, resolveCwd: () => string, filename?: string, after?: Promise<unknown>);
+    /**
+     * Persist one finalized advisor message. Assistant turns carry the usage the
+     * stats parser reads; tool results round out the Hub transcript; user deltas
+     * (the advisor's "session update" prompts) are persisted but flagged
+     * `synthetic`/agent-attributed so they never inflate user-message metrics.
+     * Non-conversational message kinds are skipped.
+     */
+    record(message: AgentMessage): void;
+    /** Flush pending writes (best-effort). */
+    flush(): Promise<void>;
+    /** Flush and close the writer, releasing the session file. */
+    close(): Promise<void>;
+}

package/dist/types/advisor/watchdog.d.ts

@@ -0,0 +1,38 @@
+import type { ActiveRepoContext } from "../utils/active-repo-context";
+export declare function formatActiveRepoWatchdogPrompt(activeRepoContext: ActiveRepoContext): string;
+/**
+ * Render the project context files (AGENTS.md and the like) into a block for the
+ * advisor's system prompt, mirroring how the primary agent receives them. Gives
+ * the read-only reviewer the user's standing project instructions so it can hold
+ * the driving agent to them instead of advising against project conventions it
+ * cannot otherwise see. Returns undefined when there are no context files.
+ */
+export declare function formatAdvisorContextPrompt(contextFiles: ReadonlyArray<{
+    path: string;
+    content: string;
+}>): string | undefined;
+/**
+ * A readable config candidate discovered on the watchdog/advisor search path,
+ * with raw (un-expanded) content and its position metadata.
+ */
+export interface ConfigCandidate {
+    path: string;
+    content: string;
+    level: "user" | "project";
+    depth: number;
+}
+/**
+ * Walk the watchdog/advisor config search path — the user agent dir plus every
+ * directory from `cwd` up to the repo root (or home), probing both `<F>` and
+ * `.omp/<F>` for each given filename — and return the readable candidates with
+ * their raw content, sorted user-first then project ancestor→leaf (depth
+ * descending, so the leaf directory is most specific/last). Shared by
+ * {@link discoverWatchdogFiles} and `discoverAdvisorConfigs`. Content is returned
+ * verbatim (no `@import` expansion); callers expand what they need.
+ */
+export declare function collectConfigCandidates(cwd: string, agentDir: string | undefined, filenames: string[]): Promise<ConfigCandidate[]>;
+/**
+ * Discover and load WATCHDOG.md files walking up from cwd, project .omp folder, and user agent dir.
+ * Returns formatted watchdog file blocks ready to be appended to the advisor system prompt.
+ */
+export declare function discoverWatchdogFiles(cwd: string, agentDir?: string): Promise<string[]>;

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

@@ -0,0 +1 @@
+export * from "./job-manager";

package/dist/types/async/job-manager.d.ts

@@ -0,0 +1,121 @@
+export interface AsyncJob {
+    id: string;
+    type: "bash" | "task";
+    status: "running" | "completed" | "failed" | "cancelled";
+    startTime: number;
+    label: string;
+    abortController: AbortController;
+    promise: Promise<void>;
+    resultText?: string;
+    errorText?: string;
+    /**
+     * Registry id of the agent that registered the job (e.g. "Main",
+     * "AuthLoader"). Used by scoped cancel/list APIs so a subagent's teardown
+     * does not cancel its parent's jobs. Undefined for callers that don't
+     * supply an id (e.g. legacy tests, SDK consumers without an agent context).
+     */
+    ownerId?: string;
+    /**
+     * Job is registered but parked behind a caller-managed gate (e.g. a task
+     * batch semaphore). Queued jobs do not count toward the running-job limit
+     * until the caller invokes `markRunning()` from the run context.
+     */
+    queued?: boolean;
+}
+export interface AsyncJobManagerOptions {
+    onJobComplete: (jobId: string, text: string, job?: AsyncJob) => void | Promise<void>;
+    maxRunningJobs?: number;
+    retentionMs?: number;
+}
+export interface AsyncJobDeliveryState {
+    queued: number;
+    delivering: boolean;
+    nextRetryAt?: number;
+    pendingJobIds: string[];
+}
+export interface AsyncJobRegisterOptions {
+    id?: string;
+    /** Registry id of the agent that owns this job; used to scope cancelAll. */
+    ownerId?: string;
+    onProgress?: (text: string, details?: Record<string, unknown>) => void | Promise<void>;
+    /** Register the job in queued state; see {@link AsyncJob.queued}. */
+    queued?: boolean;
+}
+/**
+ * Filter applied to job query/cancel APIs. With `ownerId`, results are
+ * restricted to jobs registered by that agent (registry id from
+ * `AgentRegistry`, e.g. "Main", "AuthLoader").
+ */
+export interface AsyncJobFilter {
+    ownerId?: string;
+}
+export declare class AsyncJobManager {
+    #private;
+    /** Process-global instance shared by internal URL protocol handlers and tools. */
+    static instance(): AsyncJobManager | undefined;
+    /** Install or clear the process-global instance. */
+    static setInstance(value: AsyncJobManager | undefined): void;
+    /** Reset the process-global instance. Test-only. */
+    static resetForTests(): void;
+    constructor(options: AsyncJobManagerOptions);
+    /** True when the running-job count has reached the configured cap. */
+    get atCapacity(): boolean;
+    register(type: "bash" | "task", label: string, run: (ctx: {
+        jobId: string;
+        signal: AbortSignal;
+        reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
+        /** Clear the queued flag once the job actually starts executing. */
+        markRunning: () => void;
+    }) => Promise<string>, options?: AsyncJobRegisterOptions): string;
+    /**
+     * Cancel a single job by id. When `filter.ownerId` is set and does not
+     * match the job's owner, the call is treated as not-found (returns false)
+     * so cross-agent cancellation is rejected at the manager level.
+     */
+    cancel(id: string, filter?: AsyncJobFilter): boolean;
+    getJob(id: string): AsyncJob | undefined;
+    getRunningJobs(filter?: AsyncJobFilter): AsyncJob[];
+    getRecentJobs(limit?: number, filter?: AsyncJobFilter): AsyncJob[];
+    getAllJobs(filter?: AsyncJobFilter): AsyncJob[];
+    getDeliveryState(filter?: AsyncJobFilter): AsyncJobDeliveryState;
+    hasPendingDeliveries(filter?: AsyncJobFilter): boolean;
+    watchJobs(jobIds: string[]): number;
+    unwatchJobs(jobIds: string[]): number;
+    /**
+     * Compute the next adaptive ("smart") wait (ms) for a blocking `job` poll by
+     * the given owner. Consecutive polls — those starting within
+     * POLL_ESCALATION_RESET_MS of the previous poll returning — climb
+     * POLL_WAIT_LADDER_MS so a tight wait loop backs off; a longer gap means the
+     * agent left to do real work, so the wait resets to the floor. Pair each call
+     * with `recordPollWaitEnd()` once the wait returns.
+     */
+    nextPollWaitMs(ownerId: string | undefined, now?: number): number;
+    /**
+     * Mark a blocking poll wait as finished so the idle-reset window is measured
+     * from now. Polling again before POLL_ESCALATION_RESET_MS elapses keeps
+     * climbing the ladder; waiting longer resets it to the floor.
+     */
+    recordPollWaitEnd(ownerId: string | undefined, now?: number): void;
+    acknowledgeDeliveries(jobIds: string[]): number;
+    /**
+     * Lift a foreground-wait suppression set via `acknowledgeDeliveries`. If the
+     * job already finished while suppressed (its delivery enqueue was skipped),
+     * re-enqueue the completion so the result is still delivered exactly once.
+     */
+    resumeDeliveries(jobIds: string[]): void;
+    /**
+     * Cancel running jobs. With `filter.ownerId` set, cancels only jobs the
+     * matching agent registered; with no filter, cancels every running job
+     * (used by `dispose()` to nuke the manager's state).
+     */
+    cancelAll(filter?: AsyncJobFilter): void;
+    waitForAll(): Promise<void>;
+    drainDeliveries(options?: {
+        timeoutMs?: number;
+        filter?: AsyncJobFilter;
+    }): Promise<boolean>;
+    dispose(options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    isDeliverySuppressed(jobId: string): boolean;
+}

package/dist/types/auto-thinking/classifier.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-prompt difficulty classifier for the `auto` thinking level.
+ *
+ * Picks a coding-difficulty bucket for a user prompt and maps it to a concrete
+ * {@link Effort}, clamped into the active model's supported range (never below
+ * {@link Effort.Low}). Two backends, selected by `providers.autoThinkingModel`:
+ *
+ * - `online` (default): a smol model classifies into `low|medium|high|xhigh`.
+ * - a local key: an on-device memory model classifies into the coarser
+ *   `trivial|moderate|hard` scheme (3-class is more reliable than 4-way ordinal
+ *   on sub-2B models), mapped to `low|high|xhigh`.
+ *
+ * Throws on any failure (no model, no key, unparseable output, abort/timeout);
+ * the caller falls back to a concrete level and continues the turn.
+ */
+import { Effort, type Model } from "@oh-my-pi-zen/pi-ai";
+import type { ModelRegistry } from "../config/model-registry";
+import type { Settings } from "../config/settings";
+export interface ClassifyDifficultyDeps {
+    settings: Settings;
+    registry: ModelRegistry;
+    model: Model;
+    sessionId?: string;
+    signal?: AbortSignal;
+    metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+}
+/**
+ * Classify `promptText` and return a concrete effort clamped to `deps.model`,
+ * or `undefined` when the model has no controllable effort surface (auto has
+ * nothing to pick — the caller leaves the prior reasoning level in place).
+ * @throws when the backend cannot produce a usable classification.
+ */
+export declare function classifyDifficulty(promptText: string, deps: ClassifyDifficultyDeps): Promise<Effort | undefined>;
+/** Map the online 4-way level keyword to an {@link Effort}; earliest match wins. */
+export declare function parseDifficultyLevel(text: string): Effort | undefined;
+/** Map the local 3-way bucket keyword to an {@link Effort}; earliest match wins. */
+export declare function parseDifficultyBucket(text: string): Effort | undefined;

package/dist/types/autolearn/controller.d.ts

@@ -0,0 +1,25 @@
+import type { Settings } from "../config/settings";
+import type { AgentSession } from "../session/agent-session";
+/**
+ * Build the standing auto-learn guidance for the system prompt from the tools
+ * actually present in the active set, or null when `manage_skill` is absent.
+ *
+ * Driven by tool presence rather than live settings: the `learn`/`manage_skill`
+ * registry is built ONCE at session start (and only for top-level sessions), so
+ * keying the guidance on `autolearn.enabled` would let a mid-session enable — or
+ * a subagent that filtered the tools out — inject guidance pointing at tools the
+ * session never built. The `learn` addendum is included only when the `learn`
+ * tool is present (it requires a memory backend).
+ */
+export declare function buildAutoLearnInstructions(available: {
+    manageSkill: boolean;
+    learn: boolean;
+}): string | null;
+export interface AutoLearnControllerOptions {
+    session: AgentSession;
+    settings: Settings;
+}
+export declare class AutoLearnController {
+    #private;
+    constructor(options: AutoLearnControllerOptions);
+}