@deepstrike/sdk 0.2.62 → 0.2.64

package/dist/runtime/session-log.js

@@ -6,6 +6,65 @@ import { primitiveForKind } from "./kernel-event-log.js";
 import { KeyedSerialExecutor } from "./reliability.js";
 import { FileKernelJournal, InMemoryKernelJournal } from "./kernel-journal.js";
 import { decodeDurableContent } from "./durable-content.js";
+/**
+ * The registered session-event vocabulary (F9 / S3, P7-S4). This list is the single authority
+ * the cross-SDK manifest fixture pins: a kind added here without the same-commit update to
+ * `tests/fixtures/sdk-conformance/canonical/session-event-vocabulary.json` and the python/wasm
+ * vocabularies turns cross-SDK conformance red. Declared in `SessionEvent` union order.
+ */
+export const SESSION_EVENT_KINDS = [
+    "run_started",
+    "llm_completed",
+    "prompt_measured",
+    "provider_attempt",
+    "tool_requested",
+    "tool_completed",
+    "tool_argument_repaired",
+    "tool_denied",
+    "permission_requested",
+    "permission_resolved",
+    "compressed",
+    "page_out",
+    "semantic_archive_pending",
+    "semantic_archive_completed",
+    "semantic_archive_failed",
+    "page_in",
+    "rollbacked",
+    "capability_changed",
+    "context_renewed",
+    "suspended",
+    "resumed",
+    "tool_gated",
+    "signal_delivery_disposed",
+    "budget_exceeded",
+    "budget_usage_reported",
+    "operation_cancelled",
+    "milestone_advanced",
+    "milestone_blocked",
+    "checkpoint_taken",
+    "entropy_sample",
+    "entropy_alert",
+    "agent_process_changed",
+    "memory_written",
+    "memory_queried",
+    "memory_validation_failed",
+    "memory_write_failed",
+    "memory_query_failed",
+    "memory_retrieval_result",
+    "workflow_node_completed",
+    "workflow_nodes_submitted",
+    "workflow_batch_spawned",
+    "workflow_completed",
+    "kernel_observation",
+    "run_terminal",
+    "summary_upgraded",
+    "group_member_joined",
+    "group_budget_charged",
+    "round_started",
+    "round_paced",
+];
+const _vocabularyCoversUnion = true;
+void _vocabularyCoversUnion;
 /**
  * **Single-process dev/test implementation** of both capabilities (spec §9.4: one class may
  * implement several capabilities; the *interfaces* stay separate). Its `KernelJournal` half is
@@ -158,6 +217,15 @@ function decodePersistedSessionRecord(value) {
     if (event.kind === "llm_completed" && event.provider_replay !== undefined) {
         assertCanonicalProviderReplay(event.provider_replay);
     }
+    if (event.kind === "llm_completed" && event.wire_evidence !== undefined) {
+        assertCanonicalWireEvidence(event.wire_evidence);
+    }
+    if (event.kind === "run_started" && event.route !== undefined) {
+        assertCanonicalRoute(event.route);
+    }
+    if (event.kind === "provider_attempt") {
+        assertCanonicalProviderAttempt(event);
+    }
     if (event.kind === "tool_completed") {
         if (!Array.isArray(event.results))
             throw new Error("tool_completed results must be an array");
@@ -183,3 +251,79 @@ function assertCanonicalProviderReplay(value) {
     if (typeof replay.protocol !== "string" || replay.protocol.length === 0)
         throw new Error("provider replay protocol is required");
 }
+const WIRE_EVIDENCE_KEYS = new Set(["protocol", "request_fingerprint", "response_id", "raw_usage", "replay_state"]);
+/** P3 §3.3: raw_usage carries BoundedJson semantics — the 4KB cap is enforced at the boundary. */
+const WIRE_EVIDENCE_RAW_USAGE_MAX_BYTES = 4096;
+function assertCanonicalWireEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("wire evidence must be an object");
+    const evidence = value;
+    for (const key of Object.keys(evidence))
+        if (!WIRE_EVIDENCE_KEYS.has(key))
+            throw new Error(`wire evidence has unknown field ${key}`);
+    if (typeof evidence.protocol !== "string" || evidence.protocol.length === 0)
+        throw new Error("wire evidence protocol is required");
+    // G2: the fingerprint is mandatory non-empty — it is what binds this evidence to a request plan.
+    if (typeof evidence.request_fingerprint !== "string" || evidence.request_fingerprint.length === 0) {
+        throw new Error("wire evidence request_fingerprint is required");
+    }
+    if (evidence.response_id !== undefined && typeof evidence.response_id !== "string") {
+        throw new Error("wire evidence response_id must be a string");
+    }
+    if (evidence.raw_usage !== undefined
+        && new TextEncoder().encode(JSON.stringify(evidence.raw_usage)).byteLength > WIRE_EVIDENCE_RAW_USAGE_MAX_BYTES) {
+        throw new Error("wire evidence raw_usage exceeds the 4KB BoundedJson cap");
+    }
+    if (evidence.replay_state !== undefined)
+        assertCanonicalProviderReplay(evidence.replay_state);
+}
+function assertCanonicalRoute(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("route must be an object");
+    const route = value;
+    for (const field of ["routeId", "provider", "protocol", "model", "adapterVersion", "capabilitiesRef"]) {
+        if (typeof route[field] !== "string" || route[field].length === 0) {
+            throw new Error(`route ${field} must be a non-empty string`);
+        }
+    }
+    if (!route.endpoint || typeof route.endpoint !== "object" || Array.isArray(route.endpoint)) {
+        throw new Error("route endpoint must be an object");
+    }
+}
+const PROVIDER_ATTEMPT_KEYS = new Set([
+    "kind", "effect_id", "attempt_seq", "route", "request_fingerprint", "status", "transport_rungs",
+    "last_error_class", "started_at_ms", "finished_at_ms", "usage", "wire_evidence", "accounting_policy_id",
+]);
+const PROVIDER_ATTEMPT_STATUSES = new Set(["success", "transport_exhausted", "aborted", "rejected"]);
+function assertCanonicalProviderAttempt(event) {
+    for (const key of Object.keys(event))
+        if (!PROVIDER_ATTEMPT_KEYS.has(key))
+            throw new Error(`provider_attempt has unknown field ${key}`);
+    if (typeof event.effect_id !== "string" || event.effect_id.length === 0)
+        throw new Error("provider_attempt effect_id is required");
+    if (!Number.isInteger(event.attempt_seq) || event.attempt_seq < 1)
+        throw new Error("provider_attempt attempt_seq must be a positive integer");
+    assertCanonicalRoute(event.route);
+    if (typeof event.request_fingerprint !== "string" || event.request_fingerprint.length === 0) {
+        throw new Error("provider_attempt request_fingerprint is required");
+    }
+    if (typeof event.status !== "string" || !PROVIDER_ATTEMPT_STATUSES.has(event.status)) {
+        throw new Error("provider_attempt status must be success|transport_exhausted|aborted|rejected");
+    }
+    if (!Number.isInteger(event.transport_rungs) || event.transport_rungs < 0) {
+        throw new Error("provider_attempt transport_rungs must be a non-negative integer");
+    }
+    if (event.last_error_class !== undefined && typeof event.last_error_class !== "string") {
+        throw new Error("provider_attempt last_error_class must be a string");
+    }
+    for (const field of ["started_at_ms", "finished_at_ms"]) {
+        if (typeof event[field] !== "number" || !Number.isFinite(event[field])) {
+            throw new Error(`provider_attempt ${field} must be a finite number`);
+        }
+    }
+    if (event.wire_evidence !== undefined)
+        assertCanonicalWireEvidence(event.wire_evidence);
+    if (event.accounting_policy_id !== undefined && typeof event.accounting_policy_id !== "string") {
+        throw new Error("provider_attempt accounting_policy_id must be a string");
+    }
+}

package/dist/runtime/session-repair.d.ts

@@ -1,4 +1,4 @@
-import type { Message, ProviderReplay, ToolCall } from "../types.js";
+import type { Message, ProviderReplay, ProviderWireEvidence, ToolCall } from "../types.js";
 import type { SessionEvent } from "./session-log.js";
 import type { WorkflowNodeStatus } from "../types/agent.js";
 export { REPLAY_CONTENT_MAX_BYTES as RECOVERY_CONTENT_MAX_BYTES } from "./replay-sanitize.js";
@@ -10,6 +10,10 @@ export { REPLAY_CONTENT_MAX_BYTES as RECOVERY_CONTENT_MAX_BYTES } from "./replay
  * provider-neutral and must never synthesize protocol-specific replay shapes
  * (e.g. Anthropic `native_blocks`). Canonical replay seeding for a given protocol
  * is the responsibility of that provider's `seedProviderReplay`.
+ *
+ * The P3-S2/P4-S1 evidence fields (`effect_id`, `invocation_id`, `wire_evidence`)
+ * likewise pass through verbatim: they are host evidence joining this projection to
+ * the journal effect chain, and recovery must not rewrite evidence.
  */
 export declare function normalizeLlmCompleted(event: Extract<SessionEvent, {
     kind: "llm_completed";
@@ -31,6 +35,9 @@ export declare function buildLlmCompletedEvent(input: {
     tokenCount?: number;
     toolCalls: ToolCall[];
     providerReplay?: ProviderReplay;
+    effectId?: string;
+    invocationId?: string;
+    wireEvidence?: ProviderWireEvidence;
 }): Extract<SessionEvent, {
     kind: "llm_completed";
 }>;

package/dist/runtime/session-repair.js

@@ -11,6 +11,10 @@ function estimateTokenCount(text) {
  * provider-neutral and must never synthesize protocol-specific replay shapes
  * (e.g. Anthropic `native_blocks`). Canonical replay seeding for a given protocol
  * is the responsibility of that provider's `seedProviderReplay`.
+ *
+ * The P3-S2/P4-S1 evidence fields (`effect_id`, `invocation_id`, `wire_evidence`)
+ * likewise pass through verbatim: they are host evidence joining this projection to
+ * the journal effect chain, and recovery must not rewrite evidence.
  */
 export function normalizeLlmCompleted(event, maxBytes) {
     const content = sanitizeReplayText(event.content ?? "", maxBytes);
@@ -23,6 +27,9 @@ export function normalizeLlmCompleted(event, maxBytes) {
         tool_calls: toolCalls,
         token_count: event.token_count ?? estimateTokenCount(content),
         ...(providerReplay ? { provider_replay: providerReplay } : {}),
+        ...(event.effect_id !== undefined ? { effect_id: event.effect_id } : {}),
+        ...(event.invocation_id !== undefined ? { invocation_id: event.invocation_id } : {}),
+        ...(event.wire_evidence !== undefined ? { wire_evidence: event.wire_evidence } : {}),
     };
 }
 /** Repair event log for recovery minimum set before preload/wake. */
@@ -42,6 +49,9 @@ export function buildLlmCompletedEvent(input) {
         tool_calls: input.toolCalls ?? [],
         token_count: input.tokenCount,
         provider_replay: input.providerReplay,
+        ...(input.effectId !== undefined ? { effect_id: input.effectId } : {}),
+        ...(input.invocationId !== undefined ? { invocation_id: input.invocationId } : {}),
+        ...(input.wireEvidence !== undefined ? { wire_evidence: input.wireEvidence } : {}),
     });
 }
 /** Build run_terminal with required recovery fields. */

package/dist/types.d.ts

@@ -445,6 +445,31 @@ export interface ProviderReplay {
     native_message?: unknown;
     tool_calls?: unknown[];
 }
+/**
+ * P3 §3.3 (D1): the wire-level evidence bundle for one provider call — what was actually
+ * asked (fingerprint) and what came back (response id, raw usage). SessionLog evidence only;
+ * nothing here ever crosses into kernel state (B1/B4).
+ */
+export interface ProviderWireEvidence {
+    protocol: import("./providers/protocol-capabilities.js").GenerationProtocol;
+    /** → ProviderRequestPlan.fingerprint. Mandatory non-empty (G2). */
+    request_fingerprint: string;
+    /** G3: OpenAI response id / Anthropic message id / protocol equivalent, when the wire exposes one. */
+    response_id?: string;
+    /** BoundedJson semantics: producers truncate to ≤4KB before landing it here. */
+    raw_usage?: unknown;
+    /** The former `llm_completed.provider_replay` field, carried verbatim (P3-S2 migration). */
+    replay_state?: ProviderReplay;
+}
+/**
+ * P4 §1.2: host-observed transport facts for one provider execution. `rungs` counts the HTTP
+ * attempts inside the provider's transport ladder (1 when the call path never retries, e.g.
+ * streaming); rung-level detail stays in adapter debug logs, never in SessionLog.
+ */
+export interface ProviderTransportTelemetry {
+    rungs: number;
+    responseId?: string;
+}
 /** Result of a pre-flight reasoning-replay assessment for a target provider. */
 export interface ReplayabilityAssessment {
     /** True when every reasoning-requiring tool-call turn has replay available. */
@@ -506,6 +531,13 @@ export interface LLMProvider {
     runtimePolicy?(): RuntimePolicy;
     /** Read provider-native replay fields captured after the most recent assistant turn. */
     peekProviderReplay?(message: Pick<Message, "content" | "toolCalls">): ProviderReplay | undefined;
+    /**
+     * P4-S1: read the transport facts captured during the most recent execution (HTTP rung count,
+     * wire response id). Optional — a provider without it simply omits the telemetry and the
+     * runner falls back to `rungs: 1` with no response id. Pure host evidence (B7); the values
+     * never feed kernel input.
+     */
+    peekTransportTelemetry?(): ProviderTransportTelemetry | undefined;
     /** Restore provider-native replay fields when rebuilding history from SessionLog. */
     seedProviderReplay?(message: Pick<Message, "content" | "toolCalls">, replay: ProviderReplay): void;
     /**

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.62",
+  "version": "0.2.64",
   "description": "DeepStrike Node.js SDK",
+  "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -72,7 +73,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.62",
+    "@deepstrike/core": "0.2.64",
     "@google/generative-ai": "^0.24.1",
     "openai": "^7.5.0"
   },