@wardby/cli 0.6.0 → 0.7.0

package/dist/providers/jobs/kubernetes.js

@@ -30,10 +30,10 @@ import { createHash } from "node:crypto";
 import { isIP } from "node:net";
 import { logger } from "../../core/logger.js";
 import { DISABLED_POWER, wakeTimeoutMs } from "../../core/power.js";
-import { MAX_CODING_ARTIFACT_BYTES, MAX_CODING_INPUT_BYTES, MAX_DEBUG_TRACE_LINE_BYTES, parseCodingAgentOutputJson, } from "../../coding/protocol.js";
+import { MAX_CODING_ARTIFACT_BYTES, MAX_CODING_INPUT_BYTES, MAX_DEBUG_TRACE_LINE_BYTES, parseCodingWorkerOutputJson, } from "../../coding/protocol.js";
 import { CODING_PROXY_DENY_PORT, CODING_PROXY_PORT } from "./docker-isolation.js";
 import { parseWorkerDiagnosticLine } from "./docker.js";
-import { KubernetesAlreadyExistsError, KubernetesConflictError } from "./kubernetes-api.js";
+import { KubernetesAlreadyExistsError, KubernetesConflictError, KubernetesQuotaExceededError, } from "./kubernetes-api.js";
 import { ENFORCEMENT_PROBE_DENY_REACHABLE, ENFORCEMENT_PROBE_PROVEN, ENFORCEMENT_PROBE_DENY_REFUSED, ENFORCEMENT_PROBE_PROXY_UNREACHABLE, KEEPER_CONTAINER, KEEPER_SEEDED_MARKER, KUBERNETES_ISOLATION_ERROR, STORAGE_ROOT, TOOL_RUNNER_CONTAINER, WORKER_CONTAINER, assertRunNetworkPolicyMatches, assertRunPodMatches, buildCapabilitySecret, buildRunNetworkPolicy, buildRunPod, enforcementStreakScript, kubernetesRunNames, kubernetesRunNamesForToken, runLabels, serviceContainerName, validateKubernetesSpec, } from "./kubernetes-isolation.js";
 import { claudeToolSetup } from "./claude-tool-setup.js";
 import { podQuotaUsage, quotaShortfall } from "./kubernetes-quota.js";
@@ -41,6 +41,7 @@ import { readProxyWitness } from "./kubernetes-witness.js";
 import { safeExtract } from "./safe-extract.js";
 import { reportServiceState, } from "./service-state.js";
 import { serviceUnreadyError } from "../../coding/services/wording.js";
+import { JobCapacityError, } from "./types.js";
 import { replaceDirectoryFromStaging } from "./workspace-swap.js";
 import { collectExclusions, normalizeCollectExclusions, tarExcludeArgs, } from "../../coding/collect-exclude.js";
 const BACKEND = "kubernetes";
@@ -184,10 +185,22 @@ const TOKEN = /^[a-f0-9]{20}$/;
 const WORKSPACE_STORAGE = `${STORAGE_ROOT}/workspace`;
 const INPUT_STORAGE = `${STORAGE_ROOT}/input`;
 const RESULT_PATH = `${STORAGE_ROOT}/output/result.json`;
+const TRANSCRIPT_PATH = `${STORAGE_ROOT}/output/session.jsonl`;
 /** Stands in for the proxy ClusterIP when building a pod only to count its resources. */
 const QUOTA_PROBE_PROXY_IP = "10.0.0.1";
+/** A Kubernetes object name (RFC 1123 subdomain). */
+const DNS_1123_NAME = /^[a-z0-9]([-a-z0-9.]{0,251}[a-z0-9])?$/;
 const kubernetesLog = logger.child({ module: "kubernetes-jobs" });
-const PHASES = new Set(["provisioning", "active", "succeeded", "failed", "stopped", "lost", "removed"]);
+const PHASES = new Set([
+    "provisioning",
+    "requeued",
+    "active",
+    "succeeded",
+    "failed",
+    "stopped",
+    "lost",
+    "removed",
+]);
 const TERMINAL_PHASES = new Set(["succeeded", "failed", "stopped", "lost", "removed"]);
 // ---------------------------------------------------------------------------
 // Pure helpers: the lifecycle rules.
@@ -206,6 +219,8 @@ function statusFor(record) {
     switch (record.phase) {
         case "provisioning":
             return { state: "pending" };
+        case "requeued":
+            return { state: "pending", capacityRefused: true };
         case "active":
             return { state: "running" };
         case "succeeded":
@@ -508,8 +523,9 @@ export class KubernetesJobLauncher {
         const handle = { backend: BACKEND, id: `${this.namespace}/${names.token}` };
         const specHash = stableSpecHash(spec);
         const existing = await this.readRecord(names);
-        if (existing)
+        if (existing && !this.isRequeued(existing, specHash)) {
             return this.existingLaunch(existing.record, specHash, handle);
+        }
         const createdAt = this.now();
         const record = {
             schemaVersion: RECORD_SCHEMA_VERSION,
@@ -521,22 +537,54 @@ export class KubernetesJobLauncher {
             phase: "provisioning",
             collectExclude: spec.collectExclude ?? collectExclusions([]),
         };
-        try {
-            // The record is the idempotency fence before any other cluster side effect.
-            await this.api.createConfigMap(this.namespace, this.recordConfigMap(names, record));
+        if (existing) {
+            // Replaces the requeued record; a conflict means another replica got there first.
+            try {
+                await this.api.replaceConfigMap(this.namespace, names.record, this.recordConfigMap(names, record, existing.resourceVersion));
+            }
+            catch (error) {
+                if (!(error instanceof KubernetesConflictError))
+                    throw error;
+                const raced = await this.readRecord(names);
+                if (!raced)
+                    throw error;
+                if (!this.isRequeued(raced, specHash))
+                    return this.existingLaunch(raced.record, specHash, handle);
+                // Requeued again by the other replica (its attempt was refused too): start over from that record.
+                return this.launch(spec);
+            }
         }
-        catch (error) {
-            if (!(error instanceof KubernetesAlreadyExistsError))
-                throw error;
-            const raced = await this.readRecord(names);
-            if (!raced)
-                throw error;
-            return this.existingLaunch(raced.record, specHash, handle);
+        else {
+            try {
+                // The record is the idempotency fence before any other cluster side effect. A quota refusing
+                // this create itself (a count/configmaps quota) is not a capacity refusal: it fails the run.
+                await this.api.createConfigMap(this.namespace, this.recordConfigMap(names, record));
+            }
+            catch (error) {
+                if (!(error instanceof KubernetesAlreadyExistsError))
+                    throw error;
+                const raced = await this.readRecord(names);
+                if (!raced)
+                    throw error;
+                if (!this.isRequeued(raced, specHash))
+                    return this.existingLaunch(raced.record, specHash, handle);
+                // Another replica requeued it between our read and create: start over from the requeued record.
+                return this.launch(spec);
+            }
         }
         try {
             await this.provision(spec, names, record);
         }
         catch (error) {
+            if (error instanceof KubernetesQuotaExceededError) {
+                // Capacity, not failure: leave a record a later launch() provisions afresh.
+                await this.updateRecord(names, () => ({ phase: "requeued" })).catch(() => undefined);
+                await this.cleanupRun(names, 0);
+                this.hintQuotaUnconfigured(error.quotaName);
+                throw new JobCapacityError("kubernetes_quota_exceeded: the namespace ResourceQuota has no room for this run", {
+                    cause: error,
+                });
+            }
             // Record the failure before deleting the pod, so a replica that observes "no pod" in between
             // can't record `lost` first and have this more specific outcome dropped.
             await this.updateRecord(names, () => ({
@@ -758,6 +806,22 @@ export class KubernetesJobLauncher {
             await this.sleep(ENFORCEMENT_POLL_MS);
         }
     }
+    /** True when `found` is a requeued record for this spec, which launch() replaces with a fresh one. */
+    isRequeued(found, specHash) {
+        if (found.record.phase !== "requeued")
+            return false;
+        if (found.record.specHash !== specHash)
+            throw new Error("job_spec_conflict");
+        return true;
+    }
+    /** Tells the operator once that a quota refused a pod while no quota is configured for the pre-launch check. */
+    hintQuotaUnconfigured(refusedQuota) {
+        if (this.options.config.resourceQuota)
+            return;
+        const name = refusedQuota !== undefined && DNS_1123_NAME.test(refusedQuota) ? refusedQuota : undefined;
+        this.warnOnce(`kubernetes_resource_quota_unconfigured: a pod was refused by ${name ? `ResourceQuota ${name}` : "a ResourceQuota"}; ` +
+            `set KUBERNETES_RESOURCE_QUOTA=${name ?? "<name>"} and grant the launcher get on that ResourceQuota so runs wait before they start`);
+    }
     existingLaunch(record, specHash, handle) {
         if (record.specHash !== specHash)
             throw new Error("job_spec_conflict");
@@ -957,7 +1021,8 @@ export class KubernetesJobLauncher {
     // Observation and collection
     /** Observes a non-terminal run against its pod and persists any transition; returns the stored record. */
     async refresh(names, record) {
-        if (isTerminal(record.phase))
+        // A requeued run has no pod by design; observing it would record it lost.
+        if (isTerminal(record.phase) || record.phase === "requeued")
             return record;
         const pod = await this.api.readPod(this.namespace, names.pod);
         const observed = observePod(pod, record, this.now(), this.readyTimeoutMs);
@@ -985,6 +1050,30 @@ export class KubernetesJobLauncher {
         }
         return undefined;
     }
+    async readTranscript(handle, maxBytes) {
+        const names = this.namesFor(handle);
+        const found = names && (await this.readRecord(names));
+        if (!names || !found)
+            return undefined;
+        const collector = new BoundedCollector(maxBytes);
+        let exitCode;
+        try {
+            exitCode = await this.api.exec(this.namespace, names.pod, KEEPER_CONTAINER, ["head", "-c", String(maxBytes + 1), TRANSCRIPT_PATH], { stdout: collector, timeoutMs: SHORT_EXEC_TIMEOUT_MS });
+            if (!collector.writableEnded)
+                collector.end();
+            await finished(collector);
+        }
+        catch {
+            // The pod is gone (a stopped run) or unreachable: there is nothing to collect.
+            collector.destroy();
+            return undefined;
+        }
+        if (exitCode !== 0)
+            return undefined;
+        if (collector.exceeded)
+            throw new Error("transcript_too_large");
+        return collector.text();
+    }
     async readResultArtifact(names, runId) {
         const collector = new BoundedCollector(MAX_CODING_ARTIFACT_BYTES);
         let raw;
@@ -1005,7 +1094,7 @@ export class KubernetesJobLauncher {
         }
         let output;
         try {
-            output = parseCodingAgentOutputJson(raw);
+            output = parseCodingWorkerOutputJson(raw);
         }
         catch (error) {
             throw errorWithCode("kubernetes_result_artifact_invalid", error);

package/dist/providers/jobs/types.d.ts

@@ -21,6 +21,14 @@ export interface JobSpec {
     /** Required only for Claude's credential-free repository tool container. */
     toolImage?: string;
     inputArtifact: string;
+    /** Set only when the run's dependency cache is on (CodingRun.dependencyCache); absent otherwise, never false. */
+    dependencyCache?: true;
+    /**
+     * Claude Code only, set only when the run keeps its session (CodingRun.sessionResume); absent otherwise,
+     * never false. The worker's SDK config dir, where the session file grows, gets its own size-limited
+     * scratch so a long session never fills the worker's shared /tmp.
+     */
+    sessionResume?: true;
     timeoutSec: number;
     limits: JobResourceLimits;
     labels: Record<string, string>;
@@ -42,6 +50,12 @@ export interface JobHandle {
 }
 export type JobStatus = {
     state: "pending" | "running";
+    /**
+     * Only ever on `pending`: the backend refused this job's launch for capacity (JobCapacityError)
+     * and nothing of it is running, nor will it start on its own. A caller that finds its job so
+     * may return the run to its queue and later `launch` the same spec again.
+     */
+    capacityRefused?: true;
 } | {
     state: "succeeded";
 } | {
@@ -61,11 +75,24 @@ export interface JobResult {
     /** Output-schema failure locations (`path:code`) that passed SAFE_CODING_OUTPUT_ISSUE; never values. */
     diagnosticIssues?: string[];
 }
+/**
+ * The backend has no room for this job right now (Kubernetes: the namespace ResourceQuota). No
+ * workload of the job is left running; the backend may keep a record of the refusal (Kubernetes
+ * does: its run record, which `status` then reports as `pending` with `capacityRefused`). The
+ * caller may launch the same spec again later.
+ */
+export declare class JobCapacityError extends Error {
+    readonly code = "coding_capacity_exceeded";
+    constructor(message: string, options?: ErrorOptions);
+}
 /**
  * Lifecycle invariants implemented by every launcher:
  *
  * - `launch` is idempotent by runId for an identical spec and rejects a
  *   different spec for the same runId.
+ * - `launch` may reject with JobCapacityError when the backend has no room for
+ *   the job; nothing of it is then left running, and a later `launch` of the
+ *   same spec provisions it afresh.
  * - pending may become running or terminal; running may become terminal;
  *   terminal states never change.
  * - `collect` is repeatable for a terminal job until `remove` succeeds.
@@ -100,6 +127,12 @@ export interface JobLauncher {
     launch: (spec: JobSpec) => Promise<JobHandle>;
     status: (handle: JobHandle) => Promise<JobStatus>;
     collect: (handle: JobHandle) => Promise<JobResult>;
+    /**
+     * The run's session transcript file (the worker's session.jsonl), at most `maxBytes`; undefined
+     * when there is none or the job's storage is gone (a stopped job). Throws `transcript_too_large`
+     * when larger. Never cached in the job record: it is not redacted yet. Call before `remove`.
+     */
+    readTranscript?: (handle: JobHandle, maxBytes: number) => Promise<string | undefined>;
     stop: (handle: JobHandle, reason?: string) => Promise<void>;
     remove: (handle: JobHandle) => Promise<void>;
 }

package/dist/providers/jobs/types.js

@@ -3,4 +3,16 @@
  * values are carried in a versioned input artifact, never expanded into an
  * arbitrary environment map or shell command.
  */
-export {};
+/**
+ * The backend has no room for this job right now (Kubernetes: the namespace ResourceQuota). No
+ * workload of the job is left running; the backend may keep a record of the refusal (Kubernetes
+ * does: its run record, which `status` then reports as `pending` with `capacityRefused`). The
+ * caller may launch the same spec again later.
+ */
+export class JobCapacityError extends Error {
+    code = "coding_capacity_exceeded";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "JobCapacityError";
+    }
+}

package/dist/providers/llm/anthropic.js

@@ -6,6 +6,7 @@
  */
 import Anthropic from "@anthropic-ai/sdk";
 import { ClaudeLlmProvider } from "./claude-provider.js";
+import { simulatorModelClientOptions } from "../../config/test-simulators.js";
 export function anthropicCredentialsPresent(env = process.env) {
     return Boolean(env.ANTHROPIC_API_KEY);
 }
@@ -14,6 +15,9 @@ export class AnthropicLlmProvider extends ClaudeLlmProvider {
         if (!client && !apiKey) {
             throw new Error("ANTHROPIC_API_KEY is not set — required by the Anthropic LlmProvider adapter.");
         }
-        super(client ?? new Anthropic({ apiKey }), lookup);
+        // WARDBY_TEST_SIMULATORS (test only): the scripted model, with a placeholder key the
+        // credential-free fetch drops; the real key never goes there.
+        const simulator = client ? null : simulatorModelClientOptions("anthropic");
+        super(client ?? new Anthropic(simulator ?? { apiKey }), lookup);
     }
 }

package/dist/providers/llm/bedrock.d.ts

@@ -1,15 +1,3 @@
-/**
- * Bedrock-Claude adapter for the LlmProvider seam. `@anthropic-ai/bedrock-sdk`
- * is imported only here; all protocol/pricing-dispatch logic lives in the
- * shared ClaudeLlmProvider base class (claude-provider.ts) — AnthropicBedrock
- * exposes the identical .messages.stream() surface as @anthropic-ai/sdk, so
- * this file's only job is constructing the right client.
- *
- * Named BedrockClaudeLlmProvider, not BedrockLlmProvider: Bedrock hosts
- * multiple model vendors, and this adapter only ever speaks the
- * Anthropic-native protocol for Claude models. A future non-Claude Bedrock
- * adapter gets its own name, not a rename of this one.
- */
 import { AnthropicBedrock } from "@anthropic-ai/bedrock-sdk";
 import { ClaudeLlmProvider } from "./claude-provider.js";
 import type { CatalogLookup } from "./catalog-lookup.js";

package/dist/providers/llm/bedrock.js

@@ -10,6 +10,7 @@
  * Anthropic-native protocol for Claude models. A future non-Claude Bedrock
  * adapter gets its own name, not a rename of this one.
  */
+import { refuseBedrockUnderTestSimulators } from "../../config/test-simulators.js";
 import { AnthropicBedrock } from "@anthropic-ai/bedrock-sdk";
 import { ClaudeLlmProvider } from "./claude-provider.js";
 export function bedrockCredentialsPresent(env = process.env) {
@@ -23,6 +24,9 @@ export class BedrockClaudeLlmProvider extends ClaudeLlmProvider {
         if (!client && !region) {
             throw new Error("BEDROCK_REGION (or AWS_REGION) is required by the Bedrock Claude LlmProvider adapter.");
         }
+        // WARDBY_TEST_SIMULATORS (test only) refuses Bedrock: AWS-signed calls cannot go to the simulator.
+        if (!client)
+            refuseBedrockUnderTestSimulators();
         super(client ?? new AnthropicBedrock({ awsRegion: region }), lookup);
     }
 }

package/dist/providers/llm/claude-messages.d.ts

@@ -106,5 +106,7 @@ export type ClaudeStreamEvent = {
 } | {
     type: "message_stop";
 };
-export declare function mapClaudeStream(events: AsyncIterable<ClaudeStreamEvent>, priceUsd: (usage: LlmUsage) => number): AsyncIterable<LlmStreamEvent>;
+export declare function mapClaudeStream(events: AsyncIterable<ClaudeStreamEvent>, priceUsd: (usage: LlmUsage) => number, 
+/** Called at message_start: the response has started, and output may be billed from here on. */
+onResponseStarted?: () => void): AsyncIterable<LlmStreamEvent>;
 export {};

package/dist/providers/llm/claude-messages.js

@@ -98,7 +98,9 @@ export function withCacheBreakpoints(req) {
     });
     return { ...req, ...(system ? { system } : {}), messages };
 }
-export async function* mapClaudeStream(events, priceUsd) {
+export async function* mapClaudeStream(events, priceUsd, 
+/** Called at message_start: the response has started, and output may be billed from here on. */
+onResponseStarted) {
     const toolBuffers = new Map();
     let start = {};
     let outputTokens = 0;
@@ -106,6 +108,7 @@ export async function* mapClaudeStream(events, priceUsd) {
     for await (const ev of events) {
         switch (ev.type) {
             case "message_start":
+                onResponseStarted?.();
                 start = ev.message.usage ?? {};
                 outputTokens = ev.message.usage?.output_tokens ?? 0;
                 break;

package/dist/providers/llm/claude-provider.d.ts

@@ -5,7 +5,7 @@
  * stays exactly what each concrete adapter (anthropic.ts, bedrock.ts) has in
  * common, and nothing more.
  */
-import type { LlmMessage, LlmRequest, LlmStreamEvent, LlmToolDef } from "./types.js";
+import type { LlmMessage, LlmRequest, LlmStreamEvent, LlmStreamHooks, LlmToolDef } from "./types.js";
 import { type CatalogLookup } from "./catalog-lookup.js";
 import type { CatalogEntry } from "./catalog-types.js";
 import type { CatalogLlmAdapter } from "./routing.js";
@@ -27,7 +27,7 @@ export declare class ClaudeLlmProvider implements CatalogLlmAdapter {
     private readonly lookup;
     constructor(client: ClaudeMessagesClient, lookup?: CatalogLookup);
     withEntry(entry: CatalogEntry): ClaudeLlmProvider;
-    stream(req: LlmRequest, signal?: AbortSignal): AsyncIterable<LlmStreamEvent>;
+    stream(req: LlmRequest, signal?: AbortSignal, hooks?: LlmStreamHooks): AsyncIterable<LlmStreamEvent>;
     countTokens(model: string, messages: LlmMessage[], tools?: LlmToolDef[]): Promise<number>;
     priceUsd(model: string, usage: {
         inputTokens: number;

package/dist/providers/llm/claude-provider.js

@@ -21,14 +21,14 @@ export class ClaudeLlmProvider {
     withEntry(entry) {
         return new ClaudeLlmProvider(this.client, pinnedLookup(entry));
     }
-    async *stream(req, signal) {
+    async *stream(req, signal, hooks) {
         // Defence in depth behind config-time validation: a level the model
         // doesn't accept would fail the whole call, so it is dropped here.
         const { effort, ...rest } = req;
         const accepted = effort && this.lookup(req.model).efforts.includes(effort);
         const claudeReq = withCacheBreakpoints(toClaudeRequest(accepted ? { ...rest, effort } : rest, DEFAULT_MAX_TOKENS));
         const raw = this.client.messages.stream({ model: req.model, ...claudeReq }, { signal });
-        yield* mapClaudeStream(raw, (usage) => this.priceUsd(req.model, usage));
+        yield* mapClaudeStream(raw, (usage) => this.priceUsd(req.model, usage), hooks?.onResponseStarted);
     }
     async countTokens(model, messages, tools) {
         this.lookup(model); // fail-closed on a model the catalog does not serve

package/dist/providers/llm/openai.d.ts

@@ -27,7 +27,7 @@
  *   apply.
  */
 import OpenAI from "openai";
-import type { LlmMessage, LlmRequest, LlmStreamEvent, LlmToolDef } from "./types.js";
+import type { LlmMessage, LlmRequest, LlmStreamEvent, LlmStreamHooks, LlmToolDef } from "./types.js";
 import { type CatalogLookup } from "./catalog-lookup.js";
 import type { CatalogEntry } from "./catalog-types.js";
 import type { CatalogLlmAdapter } from "./routing.js";
@@ -44,7 +44,7 @@ export declare class OpenAiLlmProvider implements CatalogLlmAdapter {
      */
     constructor(apiKey?: string, client?: OpenAI, lookup?: CatalogLookup);
     withEntry(entry: CatalogEntry): OpenAiLlmProvider;
-    stream(req: LlmRequest, signal?: AbortSignal): AsyncIterable<LlmStreamEvent>;
+    stream(req: LlmRequest, signal?: AbortSignal, hooks?: LlmStreamHooks): AsyncIterable<LlmStreamEvent>;
     /**
      * OpenAI reports both `cached_tokens` and `cache_write_tokens` as subsets
      * of `input_tokens`. wardby's LlmUsage convention (claude-messages.ts,

package/dist/providers/llm/openai.js

@@ -27,6 +27,7 @@
  *   apply.
  */
 import OpenAI from "openai";
+import { simulatorModelClientOptions } from "../../config/test-simulators.js";
 import { encode as encodeCl100kBase } from "gpt-tokenizer/encoding/cl100k_base";
 import { encode as encodeO200kBase } from "gpt-tokenizer/encoding/o200k_base";
 import { computeCost } from "./pricing-core.js";
@@ -133,12 +134,14 @@ export class OpenAiLlmProvider {
         if (!apiKey) {
             throw new Error("OPENAI_API_KEY is not set — required by the OpenAI LlmProvider adapter.");
         }
-        this.client = new OpenAI({ apiKey });
+        // WARDBY_TEST_SIMULATORS (test only): the scripted model, with a placeholder key the
+        // credential-free fetch drops; the real key never goes there.
+        this.client = new OpenAI(simulatorModelClientOptions("openai") ?? { apiKey });
     }
     withEntry(entry) {
         return new OpenAiLlmProvider("", this.client, pinnedLookup(entry));
     }
-    async *stream(req, signal) {
+    async *stream(req, signal, hooks) {
         const entry = this.lookup(req.model);
         // Effort is sent only at a level the catalog says the model accepts and
         // dropped otherwise (the LlmRequest.effort contract). Temperature only
@@ -157,6 +160,7 @@ export class OpenAiLlmProvider {
             ...(sendTemperature ? { temperature: req.temperature } : {}),
         };
         const stream = await this.client.responses.create(params, { signal });
+        hooks?.onResponseStarted?.();
         let sawToolCall = false;
         for await (const event of stream) {
             switch (event.type) {

package/dist/providers/llm/routing.d.ts

@@ -1,6 +1,6 @@
 import type { ModelCatalog } from "./catalog.js";
 import { type CatalogEntry, type ModelProvider, type ResolvedCatalogEntry } from "./catalog-types.js";
-import type { LlmEffort, LlmMessage, LlmProvider, LlmRequest, LlmStreamEvent, LlmToolDef } from "./types.js";
+import type { LlmEffort, LlmMessage, LlmProvider, LlmRequest, LlmStreamEvent, LlmStreamHooks, LlmToolDef } from "./types.js";
 /** Effort levels `model` accepts, from the current catalog; no credentials needed (config-time validation). */
 export declare function modelSupportedEfforts(model: string): readonly LlmEffort[];
 export declare function modelAcceptsEffort(model: string, effort: LlmEffort): boolean;
@@ -24,7 +24,7 @@ export declare class RoutingLlmProvider implements LlmProvider {
     /** A provider bound to one run's stored entry: prices and shapes requests from it, never the live catalog. */
     forRun(entry: CatalogEntry): LlmProvider;
     private resolve;
-    stream(req: LlmRequest, signal?: AbortSignal): AsyncIterable<LlmStreamEvent>;
+    stream(req: LlmRequest, signal?: AbortSignal, hooks?: LlmStreamHooks): AsyncIterable<LlmStreamEvent>;
     countTokens(model: string, messages: LlmMessage[], tools?: LlmToolDef[]): Promise<number>;
     priceUsd(model: string, usage: {
         inputTokens: number;

package/dist/providers/llm/routing.js

@@ -54,8 +54,8 @@ export class RoutingLlmProvider {
     resolve(model) {
         return this.byProvider.get(this.entryFor(model).provider);
     }
-    stream(req, signal) {
-        return this.resolve(req.model).stream(req, signal);
+    stream(req, signal, hooks) {
+        return this.resolve(req.model).stream(req, signal, hooks);
     }
     countTokens(model, messages, tools) {
         return this.resolve(model).countTokens(model, messages, tools);

package/dist/providers/llm/types.d.ts

@@ -68,7 +68,9 @@ export interface LlmUsage {
 export type LlmStreamEvent = {
     type: "text";
     delta: string;
-} | {
+}
+/** `id` must be unique within a run, not only within a turn: a delegation keys its child run on it. */
+ | {
     type: "tool_call";
     id: string;
     name: string;
@@ -78,8 +80,16 @@ export type LlmStreamEvent = {
     stopReason: string;
     usage: LlmUsage;
 };
+/** Observers of a stream's progress that its events do not show. */
+export interface LlmStreamHooks {
+    /**
+     * Called once the provider's response has started. From then on the provider
+     * may bill output (thinking or reasoning included) before any event is yielded.
+     */
+    onResponseStarted?: () => void;
+}
 export interface LlmProvider {
-    stream(req: LlmRequest, signal?: AbortSignal): AsyncIterable<LlmStreamEvent>;
+    stream(req: LlmRequest, signal?: AbortSignal, hooks?: LlmStreamHooks): AsyncIterable<LlmStreamEvent>;
     /**
      * Pre-flight token count for budget enforcement. `tools`, when passed,
      * must be counted too — a provider bills the serialized tool schemas as

package/dist/providers/review-host/github-events.d.ts

@@ -6,8 +6,16 @@ type Json = Record<string, unknown>;
  * counts: anyone can write the marker into their own PR's description.
  */
 export declare function appMarkerRunId(pr: Json | null, slug: string): string | undefined;
+/** Why a mention was dropped before routing; never carries the body. */
+export interface DroppedMention {
+    eventName: string;
+    repository: string;
+    association: string;
+    reason: "author_association" | "not_a_user";
+}
+/** `onDropped` hears about a mention the author pre-filter dropped, so the caller can log it. */
 export declare function normalizeGitHubEvent(eventName: string, payload: unknown, app: {
     id: number;
     slug: string;
-}): HostEvent | null;
+}, onDropped?: (dropped: DroppedMention) => void): HostEvent | null;
 export {};

package/dist/providers/review-host/github-events.js

@@ -4,8 +4,14 @@
  */
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { normalizeGitHubRepository } from "../../coding/protocol.js";
+import { withoutMarkdownCode } from "../../core/markdown-code.js";
 const PR_ACTIONS = new Set(["opened", "synchronize", "reopened", "ready_for_review"]);
-const TRUSTED_ASSOCIATIONS = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
+/**
+ * GitHub labels an organization member whose membership is private CONTRIBUTOR
+ * or NONE, so both pass; first-time authors and mannequins are drive-by
+ * accounts that cannot have access to a repository they never committed to.
+ */
+const TRUSTED_ASSOCIATIONS = new Set(["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR", "NONE"]);
 const SAFE_SHA = /^[0-9a-f]{40}$/;
 // GitHub's push payload includes at most 2048 commits.
 const PUSH_MAX_COMMITS = 2048;
@@ -37,9 +43,10 @@ function repositoryOf(payload) {
         return null;
     }
 }
+/** A mention of the App outside code: a mention quoted in code documents it, not requests a run. */
 function mentions(body, slug) {
     const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return new RegExp(`(^|[^\\w@.-])@${escaped}(?![\\w-])`, "i").test(body);
+    return new RegExp(`(^|[^\\w@.-])@${escaped}(?![\\w-])`, "i").test(withoutMarkdownCode(body));
 }
 const text = (value) => (typeof value === "string" ? value : "");
 function subjectOf(item) {
@@ -73,20 +80,27 @@ function priorRunIdOf(pr, slug) {
  * any org member, COLLABORATOR includes read and triage). The real gate is the
  * author's live repository permission, checked by id in core/host-events.ts.
  */
-function trustedHuman(association, user) {
-    return (typeof association === "string" &&
-        TRUSTED_ASSOCIATIONS.has(association) &&
-        user?.type === "User" &&
-        typeof user.login === "string" &&
-        int(user.id) !== null);
+function trustedHuman(association, user, drop) {
+    const label = typeof association === "string" ? association : "missing";
+    if (typeof association !== "string" || !TRUSTED_ASSOCIATIONS.has(association)) {
+        drop("author_association", label);
+        return false;
+    }
+    if (user?.type !== "User" || typeof user.login !== "string" || int(user.id) === null) {
+        drop("not_a_user", label);
+        return false;
+    }
+    return true;
 }
-export function normalizeGitHubEvent(eventName, payload, app) {
+/** `onDropped` hears about a mention the author pre-filter dropped, so the caller can log it. */
+export function normalizeGitHubEvent(eventName, payload, app, onDropped) {
     const p = obj(payload);
     if (!p)
         return null;
     const repository = repositoryOf(p);
     if (!repository)
         return null;
+    const drop = (reason, association) => onDropped?.({ eventName, repository, association, reason });
     if (eventName === "push") {
         const defaultBranch = obj(p.repository)?.default_branch;
         const { before, after } = p;
@@ -181,10 +195,10 @@ export function normalizeGitHubEvent(eventName, payload, app) {
             return null;
         const body = text(issue?.body);
         const user = obj(issue?.user);
-        if (!trustedHuman(issue?.author_association, user))
-            return null;
         if (!mentions(title, app.slug) && !mentions(body, app.slug))
             return null;
+        if (!trustedHuman(issue?.author_association, user, drop))
+            return null;
         if (p.action === "edited") {
             // Only the author's own edit, and only one that newly adds the mention — not every later edit.
             const sender = obj(p.sender);
@@ -209,6 +223,10 @@ export function normalizeGitHubEvent(eventName, payload, app) {
             body,
             author: user.login,
             authorId: String(user.id),
+            authorAssociation: String(issue?.author_association),
+            ...(typeof obj(p.repository)?.private === "boolean"
+                ? { repositoryPrivate: obj(p.repository)?.private }
+                : {}),
             subject: { title, body },
         };
     }
@@ -221,7 +239,7 @@ export function normalizeGitHubEvent(eventName, payload, app) {
         const commentId = int(comment?.id);
         if (typeof body !== "string" || !commentId || !mentions(body, app.slug))
             return null;
-        if (!trustedHuman(comment?.author_association, user))
+        if (!trustedHuman(comment?.author_association, user, drop))
             return null;
         const isInline = eventName === "pull_request_review_comment";
         const parent = obj(isInline ? p.pull_request : p.issue);
@@ -242,6 +260,10 @@ export function normalizeGitHubEvent(eventName, payload, app) {
             body,
             author: user.login,
             authorId: String(user.id),
+            authorAssociation: String(comment?.author_association),
+            ...(typeof obj(p.repository)?.private === "boolean"
+                ? { repositoryPrivate: obj(p.repository)?.private }
+                : {}),
             ...(subject ? { subject } : {}),
             ...(priorRunId ? { priorRunId } : {}),
         };