@vincemakes/kiso-runtime 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -31,6 +31,8 @@ export { disposeExtensions, loadExtensions, loadProjectExtensions } from "./exte
 export type { KisoExtension } from "./extensions.js";
 export { executionForCallId, executionLedger } from "./ledger.js";
 export type { ExecutionRecord, ExecutionStatus } from "./ledger.js";
+export { assessTasks } from "./task-assessment.js";
+export type { EvidenceVerdict, TaskAssessment, TaskClaim } from "./task-assessment.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

@@ -31,6 +31,9 @@ export { SessionStore, StaleWriterError, StoreCorruptionError } from "./store.js
 export { disposeExtensions, loadExtensions, loadProjectExtensions } from "./extensions.js";
 // ledger
 export { executionForCallId, executionLedger } from "./ledger.js";
+// task assessment (TV-1A) — the pure projection separating the model's
+// CLAIM from VERIFIED under Verified ⟹ evidenceSeq > lastMutationSeq
+export { assessTasks } from "./task-assessment.js";
 // trust
 export { kisoHome, projectArtifacts, recordTrust, trustFor } from "./trust.js";
 // usage — the canonical accounting schema (E2/1.3.0, R4b-1 ruling:

package/dist/run.d.ts

@@ -13,7 +13,7 @@ import { type AgentSession, type SessionConfig } from "./session.js";
 export declare class Run implements AsyncIterable<Event> {
     #private;
     runId: string;
-    constructor(store: SessionStore, adapter: Adapter, config: SessionConfig, session: AgentSession, input: string | undefined, externalSignal: AbortSignalLike | undefined, resume: boolean);
+    constructor(store: SessionStore, adapter: Adapter, config: SessionConfig, session: AgentSession, input: string | undefined, externalSignal: AbortSignalLike | undefined, resume: boolean, source?: import("@vincemakes/kiso-core").MessageSource);
     /** Cancel the run: propagates to the adapter (SDK) and future executions. */
     abort(): void;
     [Symbol.asyncIterator](): AsyncIterator<Event>;

package/dist/run.js

@@ -23,12 +23,17 @@ export class Run {
     #session;
     #input;
     #resume;
+    #source;
     #abort = new AbortController();
     #externalSignal;
     #decisionIds = [];
     #uncertaintyIds = [];
     #started = false;
-    constructor(store, adapter, config, session, input, externalSignal, resume) {
+    constructor(store, adapter, config, session, input, externalSignal, resume, 
+    // TV-1B: durable PROVENANCE for the input (e.g. the verification
+    // seed's source:"system") — who produced the line, never a
+    // provider-role escalation. Absent = plain user input.
+    source) {
         this.#store = store;
         this.#adapter = adapter;
         this.#config = config;
@@ -36,6 +41,7 @@ export class Run {
         this.#input = input;
         this.#externalSignal = externalSignal;
         this.#resume = resume;
+        this.#source = source;
         this.runId = crypto.randomUUID();
     }
     /** Cancel the run: propagates to the adapter (SDK) and future executions. */
@@ -244,7 +250,7 @@ export class Run {
             //    session. The prompt is also the first event the consumer
             //    sees, so what was asked and what happened live in the same
             //    stream.
-            const inputEvent = log.append({ type: "user_input", content: this.#input });
+            const inputEvent = log.append({ type: "user_input", content: this.#input, ...(this.#source !== undefined ? { source: this.#source } : {}) });
             await this.#session.persist(this.runId, inputEvent);
             yield inputEvent;
             // 2. The loop projects from the session log — multi-turn context
@@ -714,8 +720,8 @@ export class Run {
         }
         // ruling #12 correction one: the honest note rides the recovered failure too —
         // the receipt and the repaired tool_result reproduce the live path
-        // losslessly.
-        if (result.isError && tool?.idempotent !== true) {
+        // losslessly. WR-1-F1: precondition refusals excluded — nothing ran.
+        if (result.isError && result.errorKind !== "precondition" && tool?.idempotent !== true) {
             result = {
                 ...result,
                 content: `${result.content}\n[non-idempotent tool failed — its side effects may have partially applied; verify before retrying]`,

package/dist/session.d.ts

@@ -28,6 +28,7 @@
  * same package, same exports (index.ts re-exports all four).
  */
 import { EventLog, type AbortSignalLike, type Adapter, type Event, type KisoExtension, type Message, type PermissionDecision, type Tool } from "@vincemakes/kiso-core";
+import { type TaskAssessment } from "./task-assessment.js";
 import { type SessionStore } from "./store.js";
 import { Run } from "./run.js";
 /** TUI2-R3v2 ③ — one off-trajectory model request (session.sideQuery).
@@ -158,6 +159,7 @@ export declare class AgentSession {
     /** Run one user turn. Iterate to consume; `run.abort()` cancels. */
     run(input: string, options?: {
         signal?: AbortSignalLike;
+        source?: import("@vincemakes/kiso-core").MessageSource;
     }): Run;
     /**
      * Continue the interrupted run (Area 2): apply durable decisions,
@@ -220,6 +222,17 @@ export declare class AgentSession {
     approve(decisionId: string, allow: boolean, reason?: string): Promise<void>;
     /** Executions that started but never reported a result (crash window). */
     uncertainExecutions(): import("./ledger.js").ExecutionRecord[];
+    /**
+     * TV-1A — assess the task claims and their evidence freshness over THIS
+     * session's durable log. The shared-tool set comes from the live tools'
+     * own `effects.concurrency: "shared"` certificates (one direction of
+     * truth, never a second declaration); the evidence policy defaults to
+     * {"shell"} — the convention the task extension's own "make the LAST
+     * item a verification step" guidance produces.
+     */
+    assessTasks(opts?: {
+        readonly evidenceTools?: ReadonlySet<string>;
+    }): TaskAssessment;
     /**
      * The human's verdict on an interrupted execution, keyed by EXECUTION ID
      * (B group): "rerun" (the human says the side effect did NOT happen — the

package/dist/session.js

@@ -29,6 +29,11 @@
  */
 import { EventLog, projectMessages, } from "@vincemakes/kiso-core";
 import { executionLedger } from "./ledger.js";
+import { assessTasks } from "./task-assessment.js";
+/** TV-1A — the session-level evidence policy: the PURE projection defaults
+ *  to ∅ (never inventing evidence); the session names the one built-in
+ *  verification surface. Override per call for custom evidence tools. */
+const DEFAULT_EVIDENCE_TOOLS = new Set(["shell"]);
 import { denialResult } from "@vincemakes/kiso-core";
 import { DROP_PLACEHOLDER, estimateSummarySavings, KEEP_RECENT_ROUNDS, KEEP_TOKENS_DEFAULT, lastSummaryPoint, MAX_SUMMARY_FAILURES, policyTriggerFromWindow, serializeCovered, SUMMARY_MAX_OUTPUT, summarizeConversation, summaryBoundarySeq, } from "./summarize.js";
 import { canonicalizeUsage } from "./usage/canonical.js";
@@ -252,7 +257,7 @@ export class AgentSession {
     /** Run one user turn. Iterate to consume; `run.abort()` cancels. */
     run(input, options) {
         this.ensureHealthy();
-        return new Run(this.#store, this.#adapter, this.#config, this, input, options?.signal, false);
+        return new Run(this.#store, this.#adapter, this.#config, this, input, options?.signal, false, options?.source);
     }
     /**
      * Continue the interrupted run (Area 2): apply durable decisions,
@@ -528,6 +533,25 @@ export class AgentSession {
     uncertainExecutions() {
         return [...executionLedger(this.log.all).values()].filter((r) => r.status === "uncertain");
     }
+    /**
+     * TV-1A — assess the task claims and their evidence freshness over THIS
+     * session's durable log. The shared-tool set comes from the live tools'
+     * own `effects.concurrency: "shared"` certificates (one direction of
+     * truth, never a second declaration); the evidence policy defaults to
+     * {"shell"} — the convention the task extension's own "make the LAST
+     * item a verification step" guidance produces.
+     */
+    assessTasks(opts) {
+        const sharedTools = new Set();
+        for (const tool of this.#config.registry.list()) {
+            if (tool.effects?.concurrency === "shared")
+                sharedTools.add(tool.name);
+        }
+        return assessTasks(this.log.all, {
+            sharedTools,
+            evidenceTools: opts?.evidenceTools ?? DEFAULT_EVIDENCE_TOOLS,
+        });
+    }
     /**
      * The human's verdict on an interrupted execution, keyed by EXECUTION ID
      * (B group): "rerun" (the human says the side effect did NOT happen — the

package/dist/task-assessment.d.ts

@@ -0,0 +1,73 @@
+/**
+ * TV-1A — TaskAssessment as a PURE PROJECTION + Evidence Freshness.
+ *
+ * The task checklist the model maintains through task_set is a SELF-REPORT:
+ * an item is "done" because the model said so. This projection mechanically
+ * separates that CLAIM from VERIFIED, under one frozen sentence:
+ *
+ *   Verified ⟹ evidenceSeq > lastRelevantMutationSeq.
+ *
+ * No new event kind, no core diff — the projection reads the existing
+ * durable vocabulary (`deriveRecoveryPlan` is the shape precedent). The
+ * classifiers are maximally conservative and reuse EC-1's certificate
+ * direction verbatim:
+ *
+ * - MUTATION marker: `tool_execution_started` (intent-to-effect) of any
+ *   name NOT in `sharedTools`. Started — not the receipt — so failed and
+ *   crash-window executions invalidate too, and pre-EC-1 overlap eras are
+ *   covered by the same rule. Absence of a certificate is a mutation.
+ *   ONE proven exception (TV-1B, grounded in WR-1A): an execution whose
+ *   terminal receipt is failed(errorKind:"precondition") never counts —
+ *   that kind's frozen contract is "work refused BEFORE it starts".
+ * - EVIDENCE: only receipts (`tool_execution_succeeded`) of names in
+ *   `evidenceTools`. Default ∅ — the projection never invents evidence.
+ *   What TV-1A's verdict asserts is POSITIONAL: the arc's last
+ *   intent-to-effect was a successful evidence-class run — an "evidence",
+ *   never a "proof" (semantic knowledge is the TV-1B driver's).
+ * - task_set itself never invalidates: recording the claim after the check
+ *   is the natural arc (tests → mark done), and the claim-recording act
+ *   mutates nothing the evidence observed.
+ */
+import type { Event } from "@vincemakes/kiso-core";
+/** One item of the model's plan, exactly as last claimed. */
+export interface TaskClaim {
+    readonly text: string;
+    readonly status: "pending" | "active" | "done";
+}
+/** The freshness verdict. `stale` and `unreadable` NAME their cause. */
+export type EvidenceVerdict = {
+    readonly kind: "verified";
+    readonly evidenceSeq: number;
+} | {
+    readonly kind: "stale";
+    readonly evidenceSeq: number;
+    readonly invalidatedBySeq: number;
+} | {
+    readonly kind: "none";
+} | {
+    readonly kind: "unreadable";
+    readonly atSeq: number;
+    readonly reason: string;
+};
+export interface TaskAssessment {
+    /** The LAST successful task_set echo, parsed — the model's claims. */
+    readonly claims: readonly TaskClaim[];
+    /** True only for a non-empty plan whose every item is claimed done. */
+    readonly allClaimedDone: boolean;
+    readonly lastTaskSetSeq: number | null;
+    /** Seq of the last mutation-class `tool_execution_started`, if any. */
+    readonly lastMutationSeq: number | null;
+    readonly evidence: EvidenceVerdict;
+}
+/**
+ * Assess the task claims and their evidence freshness over a durable
+ * trajectory. Pure: same events, same options, same assessment.
+ */
+export declare function assessTasks(events: readonly Event[], opts?: {
+    /** Names whose executions never mutate (from `effects.concurrency:
+     *  "shared"` certificates). Default ∅ — everything mutates. */
+    readonly sharedTools?: ReadonlySet<string>;
+    /** Names whose successful receipts count as evidence. Default ∅ —
+     *  nothing does. */
+    readonly evidenceTools?: ReadonlySet<string>;
+}): TaskAssessment;

package/dist/task-assessment.js

@@ -0,0 +1,133 @@
+/**
+ * TV-1A — TaskAssessment as a PURE PROJECTION + Evidence Freshness.
+ *
+ * The task checklist the model maintains through task_set is a SELF-REPORT:
+ * an item is "done" because the model said so. This projection mechanically
+ * separates that CLAIM from VERIFIED, under one frozen sentence:
+ *
+ *   Verified ⟹ evidenceSeq > lastRelevantMutationSeq.
+ *
+ * No new event kind, no core diff — the projection reads the existing
+ * durable vocabulary (`deriveRecoveryPlan` is the shape precedent). The
+ * classifiers are maximally conservative and reuse EC-1's certificate
+ * direction verbatim:
+ *
+ * - MUTATION marker: `tool_execution_started` (intent-to-effect) of any
+ *   name NOT in `sharedTools`. Started — not the receipt — so failed and
+ *   crash-window executions invalidate too, and pre-EC-1 overlap eras are
+ *   covered by the same rule. Absence of a certificate is a mutation.
+ *   ONE proven exception (TV-1B, grounded in WR-1A): an execution whose
+ *   terminal receipt is failed(errorKind:"precondition") never counts —
+ *   that kind's frozen contract is "work refused BEFORE it starts".
+ * - EVIDENCE: only receipts (`tool_execution_succeeded`) of names in
+ *   `evidenceTools`. Default ∅ — the projection never invents evidence.
+ *   What TV-1A's verdict asserts is POSITIONAL: the arc's last
+ *   intent-to-effect was a successful evidence-class run — an "evidence",
+ *   never a "proof" (semantic knowledge is the TV-1B driver's).
+ * - task_set itself never invalidates: recording the claim after the check
+ *   is the natural arc (tests → mark done), and the claim-recording act
+ *   mutates nothing the evidence observed.
+ */
+const TASK_TOOL = "task_set";
+const STATUSES = new Set(["pending", "active", "done"]);
+const COUNT_LINE = /^\[task\] (\d+) items? — (\d+) pending, (\d+) active, (\d+) done$/;
+const ITEM_LINE = /^\[(\w+)\] (.*)$/;
+/** Parse the canonical task_set echo (the frozen content contract the
+ *  checklist cell also reads). Returns the claims, or the reason it
+ *  cannot — never a guess. */
+function parseEcho(content) {
+    const lines = content.split("\n");
+    const head = COUNT_LINE.exec(lines[0] ?? "");
+    if (head === null)
+        return { reason: "line 1 is not the [task] count line" };
+    const total = Number(head[1]);
+    const declared = { pending: Number(head[2]), active: Number(head[3]), done: Number(head[4]) };
+    const claims = [];
+    for (let i = 1; i < lines.length; i += 1) {
+        const m = ITEM_LINE.exec(lines[i]);
+        if (m === null || !STATUSES.has(m[1]))
+            return { reason: `line ${i + 1} is not a [pending|active|done] item line` };
+        claims.push({ text: m[2], status: m[1] });
+    }
+    const counts = { pending: 0, active: 0, done: 0 };
+    for (const c of claims)
+        counts[c.status] += 1;
+    if (claims.length !== total || counts.pending !== declared.pending || counts.active !== declared.active || counts.done !== declared.done) {
+        return { reason: "the count line disagrees with the item lines" };
+    }
+    return { claims };
+}
+/**
+ * Assess the task claims and their evidence freshness over a durable
+ * trajectory. Pure: same events, same options, same assessment.
+ */
+export function assessTasks(events, opts) {
+    const shared = opts?.sharedTools ?? new Set();
+    const evidenceNames = opts?.evidenceTools ?? new Set();
+    // TV-1B: PASS 1 — executions whose terminal receipt is a
+    // PRECONDITION failure are PROVEN no-mutation (WR-1A froze that
+    // contract: work refused before it starts). Everything else stays
+    // conservative: no receipt (crash window), fatal/transient/
+    // invalid_input, success, and legacy receipts with no errorKind.
+    // Two passes, no temporal rollback state — same events, same verdict.
+    const provenNoMutation = new Set();
+    for (const ev of events) {
+        if (ev.type === "tool_execution_failed" && ev.errorKind === "precondition") {
+            provenNoMutation.add(ev.executionId);
+        }
+    }
+    const nameByExecution = new Map();
+    let claims = [];
+    let lastTaskSetSeq = null;
+    let unreadable = null;
+    let lastMutationSeq = null;
+    let lastEvidenceSeq = null;
+    let staleBySeq = null;
+    for (const ev of events) {
+        if (ev.type === "tool_execution_started") {
+            nameByExecution.set(ev.executionId, ev.name);
+            if (ev.name !== TASK_TOOL && !shared.has(ev.name) && !provenNoMutation.has(ev.executionId)) {
+                lastMutationSeq = ev.seq;
+                if (lastEvidenceSeq !== null && staleBySeq === null)
+                    staleBySeq = ev.seq;
+            }
+        }
+        else if (ev.type === "tool_execution_succeeded") {
+            const name = nameByExecution.get(ev.executionId);
+            if (name === TASK_TOOL) {
+                const parsed = parseEcho(ev.result.content);
+                if ("reason" in parsed) {
+                    unreadable = { atSeq: ev.seq, reason: parsed.reason };
+                    claims = [];
+                    lastTaskSetSeq = ev.seq;
+                }
+                else {
+                    unreadable = null;
+                    claims = parsed.claims;
+                    lastTaskSetSeq = ev.seq;
+                }
+            }
+            else if (name !== undefined && evidenceNames.has(name)) {
+                // a fresh evidence receipt supersedes both the older evidence
+                // AND any staleness its own start incurred.
+                lastEvidenceSeq = ev.seq;
+                staleBySeq = null;
+            }
+        }
+    }
+    const allClaimedDone = claims.length > 0 && claims.every((c) => c.status === "done");
+    let evidence;
+    if (unreadable !== null) {
+        evidence = { kind: "unreadable", atSeq: unreadable.atSeq, reason: unreadable.reason };
+    }
+    else if (lastEvidenceSeq === null) {
+        evidence = { kind: "none" };
+    }
+    else if (staleBySeq !== null) {
+        evidence = { kind: "stale", evidenceSeq: lastEvidenceSeq, invalidatedBySeq: staleBySeq };
+    }
+    else {
+        evidence = { kind: "verified", evidenceSeq: lastEvidenceSeq };
+    }
+    return { claims, allClaimedDone, lastTaskSetSeq, lastMutationSeq, evidence };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-runtime",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "kiso runtime — durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
   "type": "module",
   "license": "MIT",
@@ -25,11 +25,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vincemakes/kiso-core": "0.13.0"
+    "@vincemakes/kiso-core": "0.14.0"
   },
   "peerDependencies": {
-    "@vincemakes/kiso-provider-anthropic": "0.13.0",
-    "@vincemakes/kiso-provider-openai": "0.13.0"
+    "@vincemakes/kiso-provider-anthropic": "0.14.0",
+    "@vincemakes/kiso-provider-openai": "0.14.0"
   },
   "peerDependenciesMeta": {
     "@vincemakes/kiso-provider-anthropic": {
@@ -40,7 +40,7 @@
     }
   },
   "devDependencies": {
-    "@vincemakes/kiso-evals": "0.13.0",
+    "@vincemakes/kiso-evals": "0.14.0",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"