@vincemakes/kiso-runtime 0.1.38 → 0.2.0

package/dist/agent.d.ts

@@ -62,6 +62,7 @@ export interface AgentDefinition {
      *  loop's policy chain. */
     readonly extensions?: readonly KisoExtension[];
 }
+/** @deprecated the canonical name is `Agent` (root export, 1.1.0); this alias is removed in the next major. */
 export declare class AgentRuntime {
     #private;
     constructor(definition: AgentDefinition);

package/dist/agent.js

@@ -13,6 +13,7 @@
  */
 import { EventLog, ToolRegistry } from "@vincemakes/kiso-core";
 import { AgentSession } from "./session.js";
+/** @deprecated the canonical name is `Agent` (root export, 1.1.0); this alias is removed in the next major. */
 export class AgentRuntime {
     #definition;
     #registry;
@@ -54,6 +55,7 @@ export class AgentRuntime {
         const adapter = await this.#adapterPromise;
         const config = {
             model: this.#definition.model,
+            ...(this.#definition.provider !== undefined ? { provider: this.#definition.provider } : {}),
             ...(this.#definition.systemPrompt !== undefined ? { systemPrompt: this.#definition.systemPrompt } : {}),
             registry: this.#registry,
             ...(this.#definition.permissionPolicy !== undefined || this.#definition.hooks !== undefined

package/dist/index.d.ts

@@ -1,11 +1,32 @@
-export * from "./agent.js";
-export * from "./session.js";
-export * from "./run.js";
-export * from "./recovery.js";
-export * from "./compose.js";
-export * from "./summarize.js";
-export * from "./store.js";
-export * from "./lock-adapter.js";
-export * from "./ledger.js";
-export * from "./extensions.js";
-export * from "./trust.js";
+/**
+ * The SDK surface — the curated root manifest (S1, 2026-08-12).
+ *
+ * Every name here is a review-approved contract: adding or removing one
+ * WITHOUT the ritual (the review's sign-off + a public-surface.json
+ * refresh) turns the public-surface gate red. See docs/sdk.md for the
+ * contract, the aliases, and what deliberately lives behind the
+ * first-party door.
+ *
+ * What is NOT here is not the SDK. The recovery / compose / summarize /
+ * lock-adapter machinery and buildAdapter live behind "./internal"
+ * (unstable, first-party only — see internal.ts).
+ *
+ * Canonical names: Agent = AgentRuntime, Session = AgentSession. The old
+ * names are deprecated aliases, removed in the next major (additive,
+ * ADR-0051 Amendment 1 — release rounds move the cli minor).
+ */
+export { AgentRuntime, AgentRuntime as Agent, createAgent } from "./agent.js";
+export type { AgentDefinition, PermissionPolicy, PermissionRule } from "./agent.js";
+export { AgentSession, AgentSession as Session } from "./session.js";
+export { PoisonedSessionError, ResumeBlockedError } from "./session.js";
+export type { ApprovalRequest, CompactInfo, SessionConfig, SummarizeResult } from "./session.js";
+export { Run } from "./run.js";
+export { SessionStore, StaleWriterError, StoreCorruptionError } from "./store.js";
+export type { Event, SessionMeta, StoreRecord } from "./store.js";
+export { disposeExtensions, loadExtensions, loadProjectExtensions } from "./extensions.js";
+export type { KisoExtension } from "./extensions.js";
+export { executionForCallId, executionLedger } from "./ledger.js";
+export type { ExecutionRecord, ExecutionStatus } from "./ledger.js";
+export { kisoHome, projectArtifacts, recordTrust, trustFor } from "./trust.js";
+export type { ProjectArtifact, ProjectArtifacts, TrustDecision, TrustRecord } from "./trust.js";
+export { canonicalizeUsage } from "./usage/canonical.js";

package/dist/index.js

@@ -1,11 +1,41 @@
-export * from "./agent.js";
-export * from "./session.js";
-export * from "./run.js";
-export * from "./recovery.js";
-export * from "./compose.js";
-export * from "./summarize.js";
-export * from "./store.js";
-export * from "./lock-adapter.js";
-export * from "./ledger.js";
-export * from "./extensions.js";
-export * from "./trust.js";
+/**
+ * The SDK surface — the curated root manifest (S1, 2026-08-12).
+ *
+ * Every name here is a review-approved contract: adding or removing one
+ * WITHOUT the ritual (the review's sign-off + a public-surface.json
+ * refresh) turns the public-surface gate red. See docs/sdk.md for the
+ * contract, the aliases, and what deliberately lives behind the
+ * first-party door.
+ *
+ * What is NOT here is not the SDK. The recovery / compose / summarize /
+ * lock-adapter machinery and buildAdapter live behind "./internal"
+ * (unstable, first-party only — see internal.ts).
+ *
+ * Canonical names: Agent = AgentRuntime, Session = AgentSession. The old
+ * names are deprecated aliases, removed in the next major (additive,
+ * ADR-0051 Amendment 1 — release rounds move the cli minor).
+ */
+// agent
+export { AgentRuntime, AgentRuntime as Agent, createAgent } from "./agent.js";
+// session
+export { AgentSession, AgentSession as Session } from "./session.js";
+export { PoisonedSessionError, ResumeBlockedError } from "./session.js";
+// run
+export { Run } from "./run.js";
+// store
+export { SessionStore, StaleWriterError, StoreCorruptionError } from "./store.js";
+// extensions
+export { disposeExtensions, loadExtensions, loadProjectExtensions } from "./extensions.js";
+// ledger
+export { executionForCallId, executionLedger } from "./ledger.js";
+// trust
+export { kisoHome, projectArtifacts, recordTrust, trustFor } from "./trust.js";
+// usage — the canonical accounting schema (E2/1.3.0, R4b-1 ruling:
+// additive minor, one function; the signature is frozen the moment this
+// line lands — changing it is a MAJOR ritual). R5b-④a set the final
+// shape at freeze time: the trailing `table?: PricingTable` injection
+// slot defaults to the builtin v1 table, so the R5a-1-commercial table
+// rides day one without ever widening this signature. Raw stays
+// provider observation; canonicalizeUsage derives at the accounting
+// boundary (R4 Case B — the frozen usage union does not move).
+export { canonicalizeUsage } from "./usage/canonical.js";

package/dist/internal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The FIRST-PARTY door — NOT part of the public SDK contract (S1,
+ * 2026-08-12, adjudicated).
+ *
+ * Unstable: anything here can move or vanish in any release without a
+ * major bump. External consumers must import the curated root
+ * (index.ts); this file exists for the in-repo consumers (apps/cli,
+ * extensions, tests) that need machinery the SDK deliberately does not
+ * expose — the recovery / compose / summarize / lock-adapter internals
+ * and buildAdapter.
+ *
+ * This is today's pre-S1 index.ts verbatim: removing the door would be a
+ * breaking change for the first-party consumers mid-migration.
+ */
+export * from "./agent.js";
+export * from "./session.js";
+export * from "./run.js";
+export * from "./recovery.js";
+export * from "./compose.js";
+export * from "./summarize.js";
+export * from "./store.js";
+export * from "./lock-adapter.js";
+export * from "./ledger.js";
+export * from "./extensions.js";
+export * from "./trust.js";

package/dist/internal.js

@@ -0,0 +1,25 @@
+/**
+ * The FIRST-PARTY door — NOT part of the public SDK contract (S1,
+ * 2026-08-12, adjudicated).
+ *
+ * Unstable: anything here can move or vanish in any release without a
+ * major bump. External consumers must import the curated root
+ * (index.ts); this file exists for the in-repo consumers (apps/cli,
+ * extensions, tests) that need machinery the SDK deliberately does not
+ * expose — the recovery / compose / summarize / lock-adapter internals
+ * and buildAdapter.
+ *
+ * This is today's pre-S1 index.ts verbatim: removing the door would be a
+ * breaking change for the first-party consumers mid-migration.
+ */
+export * from "./agent.js";
+export * from "./session.js";
+export * from "./run.js";
+export * from "./recovery.js";
+export * from "./compose.js";
+export * from "./summarize.js";
+export * from "./store.js";
+export * from "./lock-adapter.js";
+export * from "./ledger.js";
+export * from "./extensions.js";
+export * from "./trust.js";

package/dist/lock-adapter.js

@@ -61,6 +61,7 @@
  * pauses plus SIGSTOP/SIGCONT, and locate the freeze points via
  * ready-marker files (ADR-0050 §test affordances).
  */
+import { execFileSync } from "node:child_process";
 import { closeSync, fsyncSync, linkSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
@@ -78,14 +79,58 @@ export class LockUnavailableError extends Error {
         this.name = "LockUnavailableError";
     }
 }
+/**
+ * ADR-0050 Amendment 1 (Finding R-I-1): the liveness probe is
+ * state-aware. A dead holder can linger in the process table after a
+ * kill — the exiting state (STAT E on macOS: the kill landing while a
+ * pty syscall is blocked, the dead session's terminal left open) or an
+ * un-reaped zombie (STAT Z). POSIX reports BOTH alive to kill(pid, 0)
+ * (they exist until reaped), so the takeover refused a holder that can
+ * never execute another session write. Both states are probed and
+ * judged DEAD. A probe failure (unreadable state) maintains the
+ * pre-amendment behavior — alive, the fail-safe refusal (prefer a false
+ * refusal over a double-write). Live-process semantics and the PID-reuse
+ * rules do not move: a live foreign writer is still refused.
+ *
+ * ADR-0050 Amendment 2 (Finding R-I-p-3): the state letters are matched
+ * ANYWHERE in the state string, not as the first character. The
+ * exit-path linger's ps output is "?E" — the first character is the
+ * no-controlling-terminal marker "?", with the E sitting AFTER it — so
+ * first-character matching judged the finding's own documented shape
+ * alive. The ps state alphabet (macOS + Linux) has no flag letters
+ * "E"/"Z": an occurrence anywhere is the process-state code, and the
+ * holder is dead.
+ */
 function isAlive(pid) {
     try {
         process.kill(pid, 0);
-        return true;
     }
     catch (err) {
         return err.code === "EPERM";
     }
+    const state = processState(pid);
+    // A null state (probe failure) keeps the pre-amendment behavior —
+    // judged alive, the fail-safe refusal.
+    return state === null || (!state.includes("E") && !state.includes("Z"));
+}
+/**
+ * The process state via `ps -o state= -p <pid>` (macOS/Linux) — the
+ * whole state string (a multi-char string like "Ss+" or "?E" is a
+ * combined flag set; the E/Z process-state codes may sit after the "?"
+ * no-tty marker or other flag letters, so the matching in isAlive scans
+ * the whole string). An empty or unreadable state — the process
+ * vanished between the kill and the probe, or ps itself failed —
+ * returns null; isAlive's fail-safe branch then judges the holder alive
+ * (the pre-amendment behavior).
+ */
+function processState(pid) {
+    try {
+        const state = execFileSync("ps", ["-o", "state=", "-p", String(pid)], { encoding: "utf8" }).trim();
+        return state.length > 0 ? state : null;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Read a lock file's holder identity (round 4 formats, unchanged — the

package/dist/run.js

@@ -8,6 +8,8 @@ import { ABORTED, MergedSignal, abortable, openRunId } from "./recovery.js";
 import { deriveRecoveryPlan, invocationSeqOf } from "./recovery-plan.js";
 import { composeApprovalChain, composeSystemPrompt, composeToolTable, microcompactFor } from "./compose.js";
 import { truncationGuard } from "./truncation-guard.js";
+import { RequestTracer, traceGuard } from "./trace/guard.js";
+import { runtimeVersion } from "./trace/writer.js";
 import { ResumeBlockedError } from "./session.js";
 /**
  * A single turn. Async-iterable, so `for await (const ev of session.run(x))`
@@ -47,6 +49,7 @@ export class Run {
         // The WHOLE body is one try/finally: a consumer that abandons the
         // run at ANY yield (even the user_input one) must release the
         // session's single-run slot and its approval resolvers.
+        let tracer = null;
         try {
             // round 4: health is re-checked when the iterator ACTUALLY starts —
             // a run constructed before the session was poisoned must fail
@@ -54,6 +57,20 @@ export class Run {
             this.#session.ensureHealthy();
             this.#session.beginRun(this);
             const log = this.#session.log;
+            // E1 (1.2.0): the request tracer — the observation ledger. It
+            // sits at the adapter boundary; the model-visible byte stream is
+            // untouched (I6, trace-bytes.test.ts). Soft-fail: a degraded
+            // writer costs one stderr line and the run goes on.
+            tracer = new RequestTracer({
+                root: this.#store.root,
+                sessionId: this.#session.id,
+                runId: this.runId,
+                provider: this.#config.provider ?? "adapter",
+                model: this.#config.model,
+                adapterVersion: runtimeVersion(),
+                log: log.all,
+            });
+            tracer.init();
             const signal = this.#externalSignal ? new MergedSignal(this.#abort.signal, this.#externalSignal) : this.#abort.signal;
             // E2: the session's own microcompact wins; otherwise the FIRST
             // extension providing a compaction config supplies it.
@@ -75,7 +92,7 @@ export class Run {
             const loopConfig = () => ({
                 // 0.1.40 (R-C item 3): the truncation guard gates the model
                 // stream — a truncated turn's tool batch never executes.
-                adapter: truncationGuard(this.#adapter),
+                adapter: traceGuard(tracer, truncationGuard(this.#adapter)), // tracer assigned above, before loopConfig
                 model: this.#config.model,
                 sessionId: this.#session.id, // P3: tools see their session (ToolContext.sessionId)
                 ...(systemPrompt !== undefined ? { systemPrompt } : {}),
@@ -230,6 +247,9 @@ export class Run {
             for (const executionId of this.#uncertaintyIds) {
                 this.#session.dropUncertaintyResolver(executionId);
             }
+            // E1: the run's ledger story — the run_end lands synchronously
+            // (a killed run leaves no run_end, and the next init marks it).
+            tracer?.finishRun();
             this.#session.endRun(this);
         }
     }

package/dist/session.d.ts

@@ -71,6 +71,7 @@ export interface CompactInfo {
     /** The covered content's estimated tokens (the chars/4 proxy). */
     readonly tokens: number;
 }
+/** @deprecated the canonical name is `Session` (root export, 1.1.0); this alias is removed in the next major. */
 export declare class AgentSession {
     #private;
     readonly id: string;
@@ -97,6 +98,11 @@ export declare class AgentSession {
      * turns (dispatch's /model), never mid-run.
      */
     setAdapter(adapter: Adapter): void;
+    /** E2: the adapter identity ("anthropic" | "openai-compat") — the route
+     *  key the canonical consumer (CLI usage, the trace block) keys on. The
+     *  per-run tracer reads the SAME #config.provider; one source, one
+     *  route — the CLI and the trace can never disagree. */
+    get provider(): "anthropic" | "openai-compat" | undefined;
     /** Run one user turn. Iterate to consume; `run.abort()` cancels. */
     run(input: string, options?: {
         signal?: AbortSignalLike;
@@ -178,6 +184,9 @@ export declare class AgentSession {
 }
 export interface SessionConfig {
     readonly model: string;
+    /** E1: the adapter identity ("anthropic" | "openai-compat") — trace
+     *  provenance, additive (S1 surface untouched: type-only, optional). */
+    readonly provider?: "anthropic" | "openai-compat";
     readonly systemPrompt?: string;
     readonly tools?: readonly Tool<any>[];
     readonly registry: import("@vincemakes/kiso-core").ToolRegistry;

package/dist/session.js

@@ -54,6 +54,7 @@ export class ResumeBlockedError extends Error {
         this.uncertain = uncertain;
     }
 }
+/** @deprecated the canonical name is `Session` (root export, 1.1.0); this alias is removed in the next major. */
 export class AgentSession {
     id;
     log;
@@ -154,6 +155,13 @@ export class AgentSession {
     setAdapter(adapter) {
         this.#adapter = adapter;
     }
+    /** E2: the adapter identity ("anthropic" | "openai-compat") — the route
+     *  key the canonical consumer (CLI usage, the trace block) keys on. The
+     *  per-run tracer reads the SAME #config.provider; one source, one
+     *  route — the CLI and the trace can never disagree. */
+    get provider() {
+        return this.#config.provider;
+    }
     /** Run one user turn. Iterate to consume; `run.abort()` cancels. */
     run(input, options) {
         this.ensureHealthy();

package/dist/trace/analyze.d.ts

@@ -0,0 +1,35 @@
+/**
+ * E1 (1.2.0) — slice 4, the cache-break derivation (proposal §4, ruling
+ * R4b: per-segment hashes + prefix fingerprint; the BREAK COUNT is an
+ * analysis-side derivation, never a recorded field).
+ *
+ * The cacheable prefix is every segment that is NOT the current turn —
+ * freshness "fresh" is the boundary (manifest.ts). `cacheableHashes`
+ * pairs the manifest segments 1:1 with the per-segment hashes and
+ * drops the fresh tail, so the fingerprint and the break derivation
+ * share one boundary by construction: a current-turn change alone
+ * never moves the fingerprint and never counts a break.
+ *
+ * `prefixBreak` compares two adjacent requests' cacheable prefixes:
+ * the first differing segment is the break, at its (0-based) depth;
+ * a prefix that merely GREW (a new turn joined) breaks at the old
+ * length. Unchanged prefixes → null (0 breaks). This is what
+ * bench/trace-report.mjs and the bench render per-request (slice 5).
+ */
+import type { TraceSegment } from "./record.js";
+/** The cacheable-prefix hashes: segments[i] ↔ hashes[i], dropping every
+ *  freshness "fresh" segment (the current turn). */
+export declare function cacheableHashes(segments: readonly TraceSegment[], hashes: readonly string[]): string[];
+export interface PrefixBreak {
+    /** 0-based segment index within the cacheable prefix where the
+     *  prefix first diverges (depth 0 = the system prompt). */
+    readonly depth: number;
+}
+/** R4b: compare two adjacent requests' cacheable prefixes. null = the
+ *  prefix is unchanged (0 breaks). A prefix that grew breaks at the old
+ *  length — the new segment is where caching can no longer attach. */
+export declare function prefixBreak(prev: readonly string[], next: readonly string[]): PrefixBreak | null;
+/** Per-request breaks across a run's request sequence: request k's
+ *  break is relative to request k−1; the first request has no
+ *  predecessor (null). */
+export declare function deriveBreaks(requests: readonly (readonly string[])[]): (PrefixBreak | null)[];

package/dist/trace/analyze.js

@@ -0,0 +1,51 @@
+/**
+ * E1 (1.2.0) — slice 4, the cache-break derivation (proposal §4, ruling
+ * R4b: per-segment hashes + prefix fingerprint; the BREAK COUNT is an
+ * analysis-side derivation, never a recorded field).
+ *
+ * The cacheable prefix is every segment that is NOT the current turn —
+ * freshness "fresh" is the boundary (manifest.ts). `cacheableHashes`
+ * pairs the manifest segments 1:1 with the per-segment hashes and
+ * drops the fresh tail, so the fingerprint and the break derivation
+ * share one boundary by construction: a current-turn change alone
+ * never moves the fingerprint and never counts a break.
+ *
+ * `prefixBreak` compares two adjacent requests' cacheable prefixes:
+ * the first differing segment is the break, at its (0-based) depth;
+ * a prefix that merely GREW (a new turn joined) breaks at the old
+ * length. Unchanged prefixes → null (0 breaks). This is what
+ * bench/trace-report.mjs and the bench render per-request (slice 5).
+ */
+/** The cacheable-prefix hashes: segments[i] ↔ hashes[i], dropping every
+ *  freshness "fresh" segment (the current turn). */
+export function cacheableHashes(segments, hashes) {
+    const out = [];
+    for (let i = 0; i < segments.length; i++) {
+        if (segments[i].freshness !== "fresh")
+            out.push(hashes[i]);
+    }
+    return out;
+}
+/** R4b: compare two adjacent requests' cacheable prefixes. null = the
+ *  prefix is unchanged (0 breaks). A prefix that grew breaks at the old
+ *  length — the new segment is where caching can no longer attach. */
+export function prefixBreak(prev, next) {
+    const shared = Math.min(prev.length, next.length);
+    for (let i = 0; i < shared; i++) {
+        if (prev[i] !== next[i])
+            return { depth: i };
+    }
+    if (prev.length !== next.length)
+        return { depth: shared };
+    return null;
+}
+/** Per-request breaks across a run's request sequence: request k's
+ *  break is relative to request k−1; the first request has no
+ *  predecessor (null). */
+export function deriveBreaks(requests) {
+    const out = [];
+    for (let k = 0; k < requests.length; k++) {
+        out.push(k === 0 ? null : prefixBreak(requests[k - 1], requests[k]));
+    }
+    return out;
+}

package/dist/trace/guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * E1 (1.2.0) — slice 3, the request tracer (the guard).
+ *
+ * One TraceRecord per adapter call, settled when the stream ends. The
+ * guard lives AT the adapter boundary (run.ts wires
+ * truncationGuard(traceGuard(tracer, adapter))): the kernel, the log,
+ * and the model-visible byte stream are untouched (I6 — pinned by
+ * trace-bytes.test.ts). retryAttempt counts prior calls in this run
+ * with an identical contextHash — the loop re-streams the SAME messages
+ * array on retry (loop.ts), so an identical hash is exactly "same
+ * request, retried" (§1.4).
+ *
+ * Soft-fail: any failure in trace assembly (never expected — hashes and
+ * the manifest cannot throw today) marks the request ABSENT rather than
+ * breaking the stream; the writer's own degradation covers I/O.
+ *
+ * Usage is provider-raw, never normalized (E2's job): openai-compat
+ * reports input TOTAL (fresh = input − cacheRead); anthropic's
+ * input_tokens is ALREADY fresh-only (the trace records it as-is).
+ * A request that settles with NO usage data records the quartet as
+ * zeros with cacheWrite null — "0 = unknown", documented at record.ts;
+ * the honest nullable quartet is a schema bump, deferred.
+ */
+import type { Adapter, AdapterEvent, Event, StreamOptions } from "@vincemakes/kiso-core";
+export interface RequestTracerDeps {
+    root: string;
+    sessionId: string;
+    runId: string;
+    provider: string;
+    model: string;
+    /** The adapter contract's implementation version (the runtime's own),
+     *  resolved once at tracer init; null on failure (soft-fail). */
+    adapterVersion?: string | null;
+    /** The session log — the manifest's seqRange pointers derive from it. */
+    log: readonly Event[];
+}
+export declare class RequestTracer {
+    #private;
+    constructor(deps: RequestTracerDeps);
+    init(): void;
+    wrap(options: StreamOptions, upstream: AsyncIterable<AdapterEvent>): AsyncIterable<AdapterEvent>;
+    /** Clean-settle marking for the whole run. */
+    finishRun(): void;
+}
+/** Wrap the adapter so every stream() call settles a trace record. */
+export declare function traceGuard(tracer: RequestTracer, adapter: Adapter): Adapter;