@sema-ai/core 1.275.1

package/dist/core/tools.js

@@ -0,0 +1,98 @@
+import { Value } from "typebox/value";
+import { formatToolError, formatZodValidationError } from "./tool-errors.js";
+function normalizeContent(ret) {
+    if (typeof ret === "string") {
+        return { content: [{ type: "text", text: ret }], details: undefined, terminate: false };
+    }
+    const raw = ret.content;
+    const content = typeof raw === "string" ? [{ type: "text", text: raw }] : raw;
+    return { content, details: ret.details, terminate: ret.terminate ?? false };
+}
+/** True when a tool produced no usable content — empty array, or only whitespace-only text blocks (and
+ *  no image). An empty `tool_result` confuses the model (it has nothing to react to and can wrongly
+ *  treat the turn as finished); we substitute a sentinel instead (CC's empty-output guard). */
+function isEmptyToolContent(content) {
+    if (content.length === 0)
+        return true;
+    return content.every((b) => b.type === "text" && (typeof b.text !== "string" || b.text.trim() === ""));
+}
+/** Adapt a friendly ToolSpec into the vendored AgentTool the agent loop expects. */
+export function defineTool(spec) {
+    // Batch execution mode — FAIL-CLOSED derivation (CC 2.1.206 `TOOL_DEFAULTS.isConcurrencySafe → false`,
+    // pretty.js:280839): a declared `effect:"read"` opts the tool into parallel batches (CC's statically-true
+    // read tools); write/idempotent AND undeclared effect map to sequential — an unannotated tool must not
+    // silently ride a parallel batch. Explicit `executionMode` wins over the derivation.
+    const executionMode = spec.executionMode ?? (spec.effect === "read" ? "parallel" : "sequential");
+    return {
+        name: spec.name,
+        ...(spec.aliases && spec.aliases.length > 0 ? { aliases: spec.aliases } : {}),
+        description: spec.description,
+        label: spec.label ?? spec.name,
+        parameters: spec.parameters,
+        executionMode,
+        ...(spec.isConcurrencySafe ? { isConcurrencySafe: spec.isConcurrencySafe } : {}),
+        // design/108: carry the declared `effect` onto the AgentTool so the Runner can sync `toolEffects` from the
+        // FINAL tool set (first-party tools pushed after the toolEffects build — present_plan/AskUserQuestion/… —
+        // would otherwise read as unknown→"write" and be over-rejected by the plan-mode write-deny).
+        ...(spec.effect ? { effect: spec.effect } : {}),
+        // design/136 §2.1.c: forward the pre-validation compat shim so the ENGINE path (agent-loop
+        // prepareToolCallArguments) adapts a legacy argument shape before its schema validation too.
+        ...(spec.prepareArguments ? { prepareArguments: spec.prepareArguments } : {}),
+        execute: async (toolCallId, rawParams, signal) => {
+            // design/136 §2.1.c: apply the compat shim on THIS path as well — direct AgentTool.execute callers
+            // (the durable-resume resolvePendingCall replaying a persisted old-shape pendingAction) never went
+            // through the engine's prepareArguments hook. The shim is contract-bound idempotent, so the engine
+            // path applying it twice is safe.
+            const params = spec.prepareArguments ? spec.prepareArguments(rawParams) : rawParams;
+            // Validate arguments against the tool's declared schema BEFORE running the tool body. A model
+            // that emits malformed arguments (wrong type / missing field — common with weaker models, and
+            // seen in the wild: a model passing `path` as an array crashed a tool's `path.resolve`) then
+            // gets a structured "invalid arguments" result it can correct, instead of the tool body
+            // crashing on bad input. Returned as a tool result (not thrown) so the loop lets the model retry.
+            if (!Value.Check(spec.parameters, params)) {
+                // Human-readable, leak-free validation message (design/64 §11.3 / §16.4): param name + expected
+                // type only — no internal path/stack/filesystem context.
+                const detail = formatZodValidationError(spec.parameters, params);
+                return {
+                    content: [{ type: "text", text: `${detail} Fix the arguments and call again.` }],
+                    details: { invalidArguments: true },
+                    terminate: false,
+                };
+            }
+            let ret;
+            try {
+                ret = await spec.execute(params, { toolCallId, signal });
+            }
+            catch (err) {
+                // A tool that THROWS (rather than returning an error string) reaches the vendored loop, which
+                // would encode only `error.message`. Format it here (exit code + stderr + stdout + truncation,
+                // design/64 §11.1/§11.2) and re-throw so the loop still marks the result isError — but now with a
+                // model-useful message. Tools that already RETURN formatted errors (fs/bash) never hit this path.
+                throw new Error(formatToolError(err));
+            }
+            const { content, details, terminate } = normalizeContent(ret);
+            // Empty-output guard: a tool that returned nothing usable gets a sentinel so the model has a
+            // token to react to (an empty tool_result can make it wrongly treat the turn as done) — CC parity.
+            const guarded = isEmptyToolContent(content)
+                ? [{ type: "text", text: `(${spec.name} completed with no output)` }]
+                : content;
+            return { content: guarded, details, terminate };
+        },
+    };
+}
+/**
+ * Adapt an object-form skill into the vendored Skill shape (synthetic in-memory path).
+ *
+ * @deprecated No longer used by the runner: `TaskSpec.skills` is served by the first-party
+ * disclosure block + `skill` tool (design/71 黑盒#5 fix), and the vendored consumers of this shape
+ * were deleted. Kept only for API stability.
+ */
+export function toSkill(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        content: spec.content,
+        filePath: `memory://skills/${spec.name}`,
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/core/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/core/tools.ts"],"names":[],"mappings":"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"}

package/dist/core/trace.d.ts

@@ -0,0 +1,340 @@
+/**
+ * Observability seam (1.37). core emits structured, **metadata-only** trace events; a deployment's
+ * hook bridges them to OTel / Prometheus. core never imports an APM SDK.
+ *
+ * Privacy: events carry NO prompt/completion/tool-argument content (OTel SHOULD-NOT-by-default). If
+ * content capture is ever added it will be a separate opt-in event the deployment redacts at collection.
+ *
+ * Delivery: best-effort, fire-and-forget. The hook returns `void` (callers can't synchronously await),
+ * MUST NOT throw (core wraps it) and MUST NOT do sync I/O on the hot path. Every event carries
+ * `version` so a hook can gracefully degrade on unknown fields.
+ */
+import type { TaskStatus, ToolEffect } from "./types.js";
+import type { ThinkingLevel } from "../internal/harness.js";
+export type TraceEvent = {
+    kind: "task.start";
+    version: 1;
+    taskId: string;
+    model: string;
+    ts: number;
+} | {
+    /**
+     * 提示词主权批 — the labelled composition of the assembled system prompt, emitted once right after
+     * `task.start`. Kills the "which blocks were actually in the prompt" black box: a deployment can
+     * assert the constitution/safety blocks are present (or that their absence was a deliberate
+     * `replaceAll`) instead of diagnosing missing-prompt incidents by archaeology. Metadata-only
+     * (block ids + sizes + short content hashes — never prompt text, per the file-header privacy rule).
+     */
+    kind: "prompt.assembled";
+    version: 1;
+    taskId: string;
+    /** Who owned the constitution layer: "core" (structural default) / "replaced" (provider
+     *  `replaceAll` opt-out) / "provider-assembled" (migration guard pass-through) / "legacy"
+     *  (free-form `PromptProvider.system`). */
+    constitution: "core" | "replaced" | "provider-assembled" | "legacy";
+    /** Ordered blocks: stable id (e.g. `role.base`, `harness.context`, `memory.safety`, `skills.block`,
+     *  `env.context`, `memory.tail`), size in chars, sha256-prefix content hash. */
+    blocks: Array<{
+        id: string;
+        chars: number;
+        hash: string;
+    }>;
+    totalChars: number;
+    ts: number;
+} | {
+    /**
+     * How a task's requested reasoning intensity RESOLVED against the model's real capability (design/96 S6).
+     * Emitted once at task start when thinking is on, so a deployment can SEE — not silently swallow (§E
+     * honesty red-line) — that a binary provider ignored the tier (`graded:false`) or that an effort endpoint
+     * clamped it down (`clamped:true`). Metadata-only (tiers + format + endpoint, never prompt content).
+     */
+    kind: "reasoning.resolved";
+    version: 1;
+    taskId: string;
+    /** The model whose endpoint resolved the intensity. */
+    model: string;
+    /** The intensity the task asked for. */
+    requested: ThinkingLevel;
+    /** The intensity actually in effect on the wire. */
+    effective: ThinkingLevel;
+    /** False = binary enable-only / no-effort endpoint: the tier was NOT honored as a gradient (intent only). */
+    graded: boolean;
+    /** True = `effective` differs from `requested` (the endpoint couldn't honor the request exactly). */
+    clamped: boolean;
+    /** The wire format the request uses (`openai`/`deepseek`/`qwen`/`budget`/…) — the reason for graded/clamped. */
+    format: string;
+    /** Coarse endpoint label (`model.api`, e.g. `openai-completions` / `anthropic-messages`). */
+    endpoint: string;
+    ts: number;
+} | {
+    kind: "task.end";
+    version: 1;
+    taskId: string;
+    status: TaskStatus;
+    errorCode?: string;
+    turns: number;
+    tokens: number;
+    costMicroUsd?: number;
+    durationMs: number;
+    /** True when the task finished with a structured output (`submit_output`); 1.41 observability. */
+    hasStructuredOutput?: boolean;
+    ts: number;
+} | {
+    kind: "turn.end";
+    version: 1;
+    taskId: string;
+    turn: number;
+    ts: number;
+} | {
+    kind: "brain.call";
+    version: 1;
+    taskId: string;
+    model: string;
+    provider?: string;
+    /** Normalized total input tokens (incl. cache). */
+    promptTokens: number;
+    completionTokens: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** Wall time from the brain request to its final message. */
+    latencyMs: number;
+    /** Time to the first content delta (excludes thinking) — maps to OTel time_to_first_chunk (×1000). */
+    firstTokenMs?: number;
+    costMicroUsd?: number;
+    /** design/130 P1: the wall-clock-derived per-call output cap applied to THIS call (absent = no shrink). */
+    callCap?: number;
+    /** design/130 P1 (codex ①): cap landed in [1024,2047] with budget-thinking requested → thinking skipped. */
+    capThinkingSkipped?: boolean;
+    /** TB telemetry B1 (service [397]): the NORMALIZED finish reason of this call (`StopReason`:
+     *  `"stop"`/`"length"`/`"toolUse"`/`"error"`/`"aborted"`). Post-normalization (Anthropic
+     *  `end_turn`/`stop_sequence`→`"stop"`, `max_tokens`→`"length"`). Judge `callCap` binding by
+     *  `stopReason==="length" && callCap !== undefined`. */
+    stopReason?: string;
+    ts: number;
+} | {
+    kind: "tool.call";
+    version: 1;
+    taskId: string;
+    name: string;
+    durationMs: number;
+    ok: boolean;
+    effect?: ToolEffect;
+    ts: number;
+} | {
+    /** Degenerate-repetition detector telemetry (clay 2026-07-10, 2e1c161 observability): a model
+     *  stream was CUT for a degenerate loop, or a repetition landed in a detection window but was
+     *  SPARED by a structural allowance (code-line shape / divider run). One event per detector hit. */
+    kind: "repetition.detected";
+    version: 1;
+    taskId: string;
+    turn: number;
+    action: "cut" | "spared";
+    rule: "char-run" | "unit-loop";
+    /** Repeating-unit length in chars (1 for a char run). */
+    period: number;
+    /** How many times the unit repeated. */
+    reps: number;
+    /** ≤120-char sample of the repeated unit/tail. */
+    segment: string;
+    ts: number;
+} | {
+    /** A task was **degraded** to a cheaper model (rate_limit / breaker-open / near-budget, plus
+     *  design/126 server_error / last_resort on the chain form). An alert-worthy operational event —
+     *  quality dropped. Emitted once, when first degraded. */
+    kind: "task.degraded";
+    version: 1;
+    taskId: string;
+    from: string;
+    to: string;
+    reason: "breaker_open" | "rate_limit" | "budget" | "server_error" | "last_resort";
+    atTurn: number;
+    ts: number;
+} | {
+    /** C1 — the failover brain served this call from a FALLBACK entry (`createFailoverBrain`): the
+     *  primary (and possibly earlier hops) failed cleanly upfront. Without this, same-model gateway
+     *  swaps are indistinguishable in `brain.call` (the model id doesn't change). */
+    kind: "brain.failover";
+    version: 1;
+    taskId: string;
+    /** Index of the brain that SERVED the call (0 = primary; ≥1 = a fallback hop). */
+    servedIndex: number;
+    /** Chain length. */
+    total: number;
+    /** Canonical `BrainErrorCode` of the LAST failed hop (the reason the switch happened), if coded. */
+    errorCode?: string;
+    ts: number;
+} | {
+    /** C5 — a circuit breaker changed phase (trip / half-open probe window / close). The breaker
+     *  previously mutated state with zero emit; only the fast-fail's generic error text was visible. */
+    kind: "breaker.transition";
+    version: 1;
+    taskId: string;
+    /** Breaker key (default `<provider>:<modelId>`). */
+    key: string;
+    phase: "open" | "half-open" | "closed";
+    /** Consecutive transient failures at the transition. */
+    failures: number;
+    ts: number;
+} | {
+    /** C6 — the connect/mid-stream retry loop retried a provider call. The DISCARDED attempt's cost is
+     *  UNKNOWABLE by construction (the usage frame never arrived — that's why the attempt failed), so
+     *  this reports the attempt count honestly instead of a fabricated cost figure. */
+    kind: "brain.retry";
+    version: 1;
+    taskId: string;
+    /** 1-based attempt number that was ABANDONED (the retry that follows is attempt+1). */
+    attempt: number;
+    phase: "connect" | "midstream";
+    ts: number;
+} | {
+    /** C2 — the agent loop drove one of its self-heal recoveries (malformed-tool retry / thinking-only
+     *  retry / truncated continue / degenerate cut / mid-stream partial continue / reactive compact /
+     *  walltime cutoff write-out). Previously test-only (LoopTraceSink was never wired in production);
+     *  the only artifact was a display:false nudge message. */
+    kind: "loop.recovery";
+    version: 1;
+    taskId: string;
+    reason: string;
+    ts: number;
+} | {
+    /** C3 — within-task compaction WANTED to fire (over threshold) but the anti-thrash floor
+     *  (design/64 §25.2 `minTokens`) suppressed it. Repeated suppression = the run is drifting into
+     *  the request-trim / prefix-cache-collapse band with zero signal (the success-only onCompaction
+     *  never fires on this path). */
+    kind: "compaction.suppressed";
+    version: 1;
+    taskId: string;
+    /** Estimated context tokens at the suppressed boundary. */
+    estTokens: number;
+    /** The anti-thrash floor that suppressed the pass. */
+    floor: number;
+    ts: number;
+} | {
+    /** design/134 复审 — a preCompact callback BLOCKED a compaction at a turn boundary (auto/manual
+     *  triggers only; "forced" ignores the block). Deliberate hook decision, NOT a failure: the
+     *  breaker is neither fed nor reset by it. This frame is what tells a blocked boundary apart
+     *  from a structural no-op (under threshold / no cut point). */
+    kind: "compaction.blocked";
+    version: 1;
+    taskId: string;
+    /** The trigger the blocked pass ran under (never "forced" — forced ignores blocks). */
+    trigger: "auto" | "manual";
+    ts: number;
+} | {
+    /** MF-18 修① [496]③ — a compaction pass FAILED: either a burned summary attempt threw
+     *  (summarizer error / empty summary / oversized-summary guard; counted toward the §17.4
+     *  breaker) or a manual /compact was drained against an ALREADY-OPEN breaker (no attempt).
+     *  Before this frame the only evidence was `Runner.onError(phase:"compaction")` — a service
+     *  that acked the manual verb (202) but saw no `compacted` event had ZERO stream/trace signal
+     *  about why (the [496]③ fingerprint). */
+    kind: "compaction.failed";
+    version: 1;
+    taskId: string;
+    /** The trigger of the failed pass. */
+    trigger: "auto" | "manual" | "forced";
+    /** Engine-authored failure detail (CompactionError / guard message), clipped. */
+    reason: string;
+    ts: number;
+} | {
+    /** MF-18 修① [496]③ — a manual /compact request was PROCESSED but MOOTED: the loop is dying
+     *  (abort fired / durable suspend / plan review in flight) so no compaction can run. The
+     *  compact() promise resolves "mooted"; this frame is the trace-side counterpart. */
+    kind: "compaction.mooted";
+    version: 1;
+    taskId: string;
+    reason: "task_ending";
+    ts: number;
+} | {
+    /** MF-18 修① [496]③ — a manual /compact attempt ran but found NOTHING to compact (no valid
+     *  cut point / empty history): `maybeCompact` returned a structural `{compacted:false}` on a
+     *  forced pass. Manual-only by design — an auto pass no-ops at nearly every boundary (spam). */
+    kind: "compaction.noop";
+    version: 1;
+    taskId: string;
+    ts: number;
+} | {
+    /** MF-18 修① [496]③ — a manual /compact was processed while compaction is DISABLED by the
+     *  task spec (`compaction.enabled:false`): the request can never be honored this run. */
+    kind: "compaction.disabled";
+    version: 1;
+    taskId: string;
+    ts: number;
+} | {
+    /** MF-18 修② [496]③ — the summarization INPUT was truncated to fit the compaction model's
+     *  context window (the 300K-session shape that previously guaranteed a prompt-too-long throw
+     *  at every boundary). Fidelity disclosure: oldest `droppedChars` characters of the serialized
+     *  conversation were omitted from the summary prompt. */
+    kind: "compaction.input_truncated";
+    version: 1;
+    taskId: string;
+    /** Which summary call was truncated: the history summary or the split-turn prefix summary. */
+    label: "history" | "turn_prefix";
+    droppedChars: number;
+    keptChars: number;
+    ts: number;
+} | {
+    /** MF-18 修③ [496]③ — a compaction landed at the run's FINAL boundary and the one-shot
+     *  post-compact announce latch (background-task snapshot, G1 [482]) was never consumed: the
+     *  next collected boundary it waits for never came. The announce is lost for THIS run (a
+     *  follow-up run on the same session re-arms it from the session tail — see the resume
+     *  re-arm seed in runtask). */
+    kind: "compaction.announce_dropped";
+    version: 1;
+    taskId: string;
+    ts: number;
+} | {
+    /** C9 — the request-layer context guard TRIMMED messages out of a request view (design/123
+     *  request-only trim; the session keeps them, but the model didn't see them this turn). */
+    kind: "context.trim";
+    version: 1;
+    taskId: string;
+    /** Messages dropped from THIS request view. */
+    dropped: number;
+    ts: number;
+} | {
+    /** C8 — the per-turn aggregate tool-result budget capped a result (offloaded to the store, or
+     *  degraded to a self-contained truncation preview when the store failed/absent). */
+    kind: "tool_result.capped";
+    version: 1;
+    taskId: string;
+    tool?: string;
+    /** Chars of the full result before capping. */
+    sizeChars: number;
+    /** True = store.put failed (or no store): the model lost read-back for this result. */
+    storeFallback: boolean;
+    ts: number;
+} | {
+    /** C4 — image blocks were replaced with text placeholders because the served model declares no
+     *  vision input (`ModelSpec.input` without "image"). Silent quality loss without this. */
+    kind: "vision.placeholder";
+    version: 1;
+    taskId: string;
+    /** Image blocks replaced in THIS request. */
+    count: number;
+    ts: number;
+} | {
+    /** C10 — a `preemptSignal` fired on a task that is NOT resource-suspend-eligible: the preempt is a
+     *  documented silent no-op, but the SCHEDULER that raised it needs to know it was ignored. */
+    kind: "preempt.ignored";
+    version: 1;
+    taskId: string;
+    ts: number;
+} | {
+    /** C11 — a tool requested a human plan review (`ctx.requestReview()`) but the deployment cannot
+     *  honor it (no checkpoint store / loop already terminating): the request was consumed + DROPPED
+     *  (headless degrade). The HITL ask vanished with zero signal before this. NO free-text reason
+     *  field (codex MED: `requestReview({reason})` carries tool/model-authored text — the file-header
+     *  metadata-only rule forbids it here; the fact of the drop is the signal). */
+    kind: "review.dropped";
+    version: 1;
+    taskId: string;
+    ts: number;
+};
+/**
+ * Best-effort, fire-and-forget trace sink. Returns `void` by contract so a caller cannot synchronously
+ * await it; the default (absent) hook is a no-op the JIT can elide. Must not throw or do sync I/O.
+ */
+export type TracerHook = (e: TraceEvent) => void;
+/** Invoke a tracer without ever letting it break the task (absent → no-op; throws swallowed). */
+export declare function emitTrace(tracer: TracerHook | undefined, build: () => TraceEvent): void;
+//# sourceMappingURL=trace.d.ts.map

package/dist/core/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"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"}

package/dist/core/trace.js

@@ -0,0 +1,12 @@
+/** Invoke a tracer without ever letting it break the task (absent → no-op; throws swallowed). */
+export function emitTrace(tracer, build) {
+    if (!tracer)
+        return; // default no-op fast path
+    try {
+        tracer(build());
+    }
+    catch {
+        /* best-effort: a broken tracer never breaks the task */
+    }
+}
+//# sourceMappingURL=trace.js.map

package/dist/core/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"AAkWA,iGAAiG;AACjG,MAAM,UAAU,SAAS,CAAC,MAA8B,EAAE,KAAuB;IAC/E,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,0BAA0B;IAC/C,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;AACH,CAAC"}