@llblab/pi-kit 0.37.1 → 0.38.1

package/node_modules/@llblab/pi-state-flow/dist/lib/selection.d.ts

@@ -0,0 +1,10 @@
+import type { StateScope } from "./state.ts";
+export type ScopeSelection = readonly [StateScope, ...StateScope[]];
+/** Missing global configuration defaults to all owners; this is not a retained-session fallback. */
+export declare const DEFAULT_SCOPE_SELECTION: ScopeSelection;
+/** Validate an explicit value and detach it in canonical overlay order, without granting owner acquisition. */
+export declare function captureScopeSelection(value: unknown): ScopeSelection;
+/** Complete only the next unused owner; values replace the full argument prefix. */
+export declare function scopeSelectionArgumentCompletions(prefix: string): string[];
+/** Blank command arguments preserve policy; callers must not reinterpret them as all scopes. */
+export declare function parseScopeSelectionArguments(args: string): ScopeSelection | undefined;

package/node_modules/@llblab/pi-state-flow/dist/lib/selection.js

@@ -0,0 +1,32 @@
+const SCOPE_ORDER = ["global", "cwd", "session"];
+/** Missing global configuration defaults to all owners; this is not a retained-session fallback. */
+export const DEFAULT_SCOPE_SELECTION = Object.freeze([...SCOPE_ORDER]);
+/** Validate an explicit value and detach it in canonical overlay order, without granting owner acquisition. */
+export function captureScopeSelection(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > SCOPE_ORDER.length) {
+        throw new Error("State Flow scopes must be a nonempty unique array of global, cwd, session");
+    }
+    const requested = new Set();
+    for (let index = 0; index < value.length; index++) {
+        const scope = value[index];
+        if (!Object.hasOwn(value, index) || !SCOPE_ORDER.some((allowed) => allowed === scope) || requested.has(scope)) {
+            throw new Error("State Flow scopes must be a nonempty unique array of global, cwd, session");
+        }
+        requested.add(scope);
+    }
+    return Object.freeze(SCOPE_ORDER.filter((scope) => requested.has(scope)));
+}
+/** Complete only the next unused owner; values replace the full argument prefix. */
+export function scopeSelectionArgumentCompletions(prefix) {
+    const tokens = prefix.trimStart().split(/\s+/);
+    const partial = tokens.pop();
+    if (new Set(tokens).size !== tokens.length || tokens.some(token => !SCOPE_ORDER.some(scope => scope === token)))
+        return [];
+    return SCOPE_ORDER.filter(scope => !tokens.includes(scope) && scope.startsWith(partial))
+        .map(scope => [...tokens, scope].join(" "));
+}
+/** Blank command arguments preserve policy; callers must not reinterpret them as all scopes. */
+export function parseScopeSelectionArguments(args) {
+    const tokens = args.trim();
+    return tokens.length === 0 ? undefined : captureScopeSelection(tokens.split(/\s+/));
+}

package/node_modules/@llblab/pi-state-flow/dist/lib/semantic-module.d.ts

@@ -0,0 +1,79 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { type JsonObject, type JsonValue } from "./json.ts";
+export type ModuleContextContribution = {
+    kind: "data";
+    value: JsonValue;
+} | {
+    kind: "conversation";
+    indices: readonly number[];
+};
+export interface ModuleFrame<Input> {
+    mode: "active" | "passive";
+    conversation: readonly AgentMessage[];
+    input: Input;
+}
+/** Internal trusted package code, not an effects sandbox or a stored-plane registration. */
+export interface SemanticModule<Content extends JsonValue, Input = undefined> {
+    readonly immutable: boolean;
+    readonly id: string;
+    validate(value: unknown): value is Content;
+    context(content: Content | undefined, frame: ModuleFrame<Input>): readonly ModuleContextContribution[];
+    produce?(content: Content | undefined, input: Input, signal: AbortSignal): Content | undefined | Promise<Content | undefined>;
+}
+/** Public host DTOs: shared owners receive neither native conversation nor current prompt. */
+export interface StateFlowModuleSource {
+    readonly mode: "active" | "passive";
+    readonly scope: "global" | "cwd" | "session";
+    readonly conversation: readonly AgentMessage[];
+    readonly prompt?: string;
+}
+export interface StateFlowModuleFrame<Input extends JsonValue = JsonValue> extends StateFlowModuleSource {
+    readonly input: Input | undefined;
+}
+export interface StateFlowModuleInput<Input extends JsonValue = JsonValue> {
+    readonly value: Input;
+    /** Verify only the captured source; throw if obsolete. No acquisition or async work. */
+    assertCurrent(): void;
+}
+/** Candidate public v1 contract; durable activation requires matching retained metadata. */
+export interface StateFlowModule<Content extends JsonObject = JsonObject, Input extends JsonValue = JsonValue> {
+    readonly immutable: boolean;
+    readonly id: string;
+    readonly apiVersion: 1;
+    readonly schemaVersion: number;
+    validate(value: unknown): value is Content;
+    captureInput?(frame: StateFlowModuleSource, signal: AbortSignal): StateFlowModuleInput<Input> | Promise<StateFlowModuleInput<Input>>;
+    context(content: Content | undefined, frame: StateFlowModuleFrame<Input>): readonly ModuleContextContribution[];
+    produce?(content: Content | undefined, frame: StateFlowModuleFrame<Input>, signal: AbortSignal): Content | undefined | Promise<Content | undefined>;
+}
+/** Durable identity only: retained even while a definition is unavailable or content deleted. */
+export interface RetainedModuleDescriptor {
+    schemaVersion: number;
+    immutable: boolean;
+}
+export type RetainedModules = Record<string, RetainedModuleDescriptor>;
+export declare function validateRetainedModules(value: unknown): asserts value is RetainedModules;
+/** Descriptors cannot be removed, recycled or implicitly change schema/policy. */
+export declare function assertRetainedModules(previous: unknown, next: unknown): void;
+export type EvaluatedModuleContext = {
+    kind: "data";
+    value: JsonValue;
+} | {
+    kind: "conversation";
+    messages: readonly AgentMessage[];
+};
+/** Raw durable planes use JSON object values, independent of any definition callback. */
+export declare function validateModuleObject(value: unknown): asserts value is JsonObject;
+/** Context consumes captured data; conversation selections retain the host's exact original messages. */
+export declare function evaluateModuleContext<Content extends JsonValue, Input>(module: SemanticModule<Content, Input>, content: unknown, frame: ModuleFrame<Input>): readonly EvaluatedModuleContext[];
+/** Isolated public input/context capture; grants neither native nor publication authority. */
+export interface PreparedModuleContext {
+    assertCurrent(): void;
+    evaluate(accepted?: {
+        content: unknown;
+    }): readonly EvaluatedModuleContext[];
+    produce(): Promise<JsonObject | undefined>;
+}
+export declare function prepareModuleContext<Content extends JsonObject, Input extends JsonValue>(module: StateFlowModule<Content, Input>, content: unknown, source: StateFlowModuleSource, signal: AbortSignal, checkCurrent: () => void): Promise<PreparedModuleContext>;
+/** Evaluate only: the host must separately bind the captured basis to its existing atomic acceptance. */
+export declare function produceModuleContent<Content extends JsonValue, Input>(module: SemanticModule<Content, Input>, content: unknown, input: Input, signal: AbortSignal, checkCurrent: () => void): Promise<Content | undefined>;

package/node_modules/@llblab/pi-state-flow/dist/lib/semantic-module.js

@@ -0,0 +1,187 @@
+import { isJsonValue, isObject } from "./json.js";
+export function validateRetainedModules(value) {
+    if (!isObject(value) || !isJsonValue(value) || !losslessStoredJson(value))
+        throw new Error("Invalid State Flow retained modules");
+    for (const [id, descriptor] of Object.entries(value)) {
+        if (!/^x_[a-z][a-z0-9_]*$/.test(id) || !isObject(descriptor)
+            || Object.keys(descriptor).sort().join(",") !== "immutable,schemaVersion"
+            || !Number.isSafeInteger(descriptor.schemaVersion) || descriptor.schemaVersion <= 0
+            || typeof descriptor.immutable !== "boolean")
+            throw new Error(`Invalid State Flow retained module descriptor: ${id}`);
+    }
+}
+/** Descriptors cannot be removed, recycled or implicitly change schema/policy. */
+export function assertRetainedModules(previous, next) {
+    validateRetainedModules(previous);
+    validateRetainedModules(next);
+    for (const [id, descriptor] of Object.entries(previous)) {
+        if (!Object.hasOwn(next, id) || next[id].schemaVersion !== descriptor.schemaVersion
+            || next[id].immutable !== descriptor.immutable)
+            throw new Error(`State Flow retained module descriptor changed: ${id}`);
+    }
+}
+function dense(value) {
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++)
+            if (!Object.hasOwn(value, index) || !dense(value[index]))
+                return false;
+    }
+    else if (isObject(value))
+        return Object.values(value).every(dense);
+    return true;
+}
+function losslessStoredJson(value) {
+    if (value === null || typeof value !== "object")
+        return true;
+    const keys = Reflect.ownKeys(value);
+    if (Array.isArray(value) && keys.length !== value.length + 1)
+        return false;
+    return keys.every(key => {
+        if (Array.isArray(value) && key === "length")
+            return true;
+        const property = Object.getOwnPropertyDescriptor(value, key);
+        return typeof key === "string" && property.enumerable === true && "value" in property && losslessStoredJson(property.value);
+    });
+}
+/** Raw durable planes use JSON object values, independent of any definition callback. */
+export function validateModuleObject(value) {
+    if (!isObject(value) || !isJsonValue(value) || !dense(value) || !losslessStoredJson(value))
+        throw new Error("State Flow external content must be a finite dense JSON object");
+}
+function capture(value) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        throw new Error("Semantic module inputs must be detachable data");
+    }
+}
+function captureJson(value) {
+    if (!isJsonValue(value) || !dense(value))
+        throw new Error("Semantic module content must be finite dense JSON data");
+    const copy = capture(value);
+    if (!isJsonValue(copy) || !dense(copy))
+        throw new Error("Semantic module content must be finite dense JSON data");
+    return copy;
+}
+function contentFor(module, value) {
+    if (value === undefined)
+        return undefined;
+    const copy = captureJson(value), validation = capture(copy);
+    if (module.validate(validation) !== true || !isJsonValue(validation) || !dense(validation))
+        throw new Error(`Invalid content for semantic module ${module.id}`);
+    // Validators neither transform the content nor retain the returned candidate.
+    return capture(copy);
+}
+/** Context consumes captured data; conversation selections retain the host's exact original messages. */
+export function evaluateModuleContext(module, content, frame) {
+    if (frame.mode !== "active" && frame.mode !== "passive")
+        throw new Error("Semantic module context requires Active or Passive mode");
+    const original = [...frame.conversation];
+    const result = module.context(contentFor(module, content), { mode: frame.mode, conversation: capture(original), input: capture(frame.input) });
+    if (!Array.isArray(result))
+        throw new Error("Semantic module context must return a contribution array");
+    let last = -1;
+    return Array.from(result, contribution => {
+        if (!isObject(contribution))
+            throw new Error("Invalid semantic module context contribution");
+        const keys = Object.keys(contribution).sort().join(",");
+        if (contribution.kind === "data" && keys === "kind,value")
+            return { kind: "data", value: captureJson(contribution.value) };
+        if (contribution.kind !== "conversation" || keys !== "indices,kind" || !Array.isArray(contribution.indices)) {
+            throw new Error("Invalid semantic module context contribution");
+        }
+        const messages = Array.from(contribution.indices, index => {
+            if (typeof index !== "number" || !Number.isSafeInteger(index) || index <= last || index >= original.length)
+                throw new Error("Semantic module conversation indices must be ordered, unique and in range");
+            last = index;
+            const message = original[index];
+            if (!message || !["user", "assistant", "toolResult"].includes(message.role))
+                throw new Error("Semantic modules may select conversation messages, not protocol frames");
+            return message;
+        });
+        return { kind: "conversation", messages };
+    });
+}
+async function cancelableModuleWork(work, signal, checkCurrent) {
+    const check = () => { signal.throwIfAborted(); checkCurrent(); signal.throwIfAborted(); };
+    check();
+    let abort;
+    const canceled = new Promise((_resolve, reject) => { abort = () => reject(signal.reason); signal.addEventListener("abort", abort, { once: true }); });
+    try {
+        return await Promise.race([Promise.resolve().then(() => { check(); return work(); }).then(value => { check(); return value; }), canceled]);
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+    }
+}
+export async function prepareModuleContext(module, content, source, signal, checkCurrent) {
+    const { mode, scope, prompt } = source;
+    if (mode !== "active" && mode !== "passive" || !["global", "cwd", "session"].includes(scope))
+        throw new Error("Invalid State Flow module source frame");
+    if (scope !== "session" && (source.conversation.length || prompt !== undefined))
+        throw new Error("Shared module frames cannot acquire Session conversation or prompt");
+    const conversation = [...source.conversation];
+    const frameSource = { mode, scope, conversation, ...(prompt === undefined ? {} : { prompt }) };
+    const adapter = { id: module.id, immutable: module.immutable,
+        validate: value => module.validate(value),
+        context: (value, frame) => module.context(value, { mode, scope, conversation: frame.conversation, input: frame.input, ...(prompt === undefined ? {} : { prompt }) }) };
+    const check = () => { signal.throwIfAborted(); checkCurrent(); signal.throwIfAborted(); };
+    check();
+    const previous = contentFor(adapter, content);
+    const receipt = module.captureInput ? await cancelableModuleWork(() => module.captureInput(capture(frameSource), signal), signal, check) : undefined;
+    if (module.captureInput && receipt === undefined || receipt !== undefined && (!isObject(receipt) || typeof receipt.assertCurrent !== "function" || !Object.hasOwn(receipt, "value"))) {
+        throw new Error("State Flow module input requires value and synchronous assertCurrent");
+    }
+    const currentInput = receipt?.assertCurrent.bind(receipt);
+    const assertCurrent = () => {
+        check();
+        const result = currentInput?.();
+        if (result !== undefined) {
+            if (result && typeof result.then === "function")
+                void Promise.resolve(result).catch(() => { });
+            throw new Error("State Flow module input assertion must synchronously throw or return void");
+        }
+        check();
+    };
+    assertCurrent();
+    const input = receipt === undefined ? undefined : captureJson(receipt.value);
+    assertCurrent();
+    return Object.freeze({ assertCurrent, produce: async () => {
+            assertCurrent();
+            if (mode !== "active")
+                throw new Error("State Flow module producers require Active mode");
+            if (!module.produce)
+                return undefined;
+            const producing = { id: module.id, immutable: module.immutable,
+                validate: (value) => isObject(value) && (Object.keys(value).length === 0 || module.validate(value)),
+                context: () => [], produce: (value, frame, activeSignal) => module.produce(value, frame, activeSignal) };
+            const candidate = await produceModuleContent(producing, previous, { ...frameSource, input }, signal, assertCurrent);
+            if (candidate !== undefined)
+                validateModuleObject(candidate);
+            assertCurrent();
+            return candidate;
+        }, evaluate: (accepted) => {
+            assertCurrent();
+            const result = evaluateModuleContext(adapter, accepted === undefined ? previous : accepted.content, { mode, conversation, input });
+            if (scope !== "session" && result.some(item => item.kind === "conversation"))
+                throw new Error("Shared modules cannot replace Session conversation");
+            assertCurrent();
+            return result;
+        } });
+}
+/** Evaluate only: the host must separately bind the captured basis to its existing atomic acceptance. */
+export async function produceModuleContent(module, content, input, signal, checkCurrent) {
+    const check = () => { signal.throwIfAborted(); checkCurrent(); signal.throwIfAborted(); };
+    check();
+    const produce = module.produce?.bind(module);
+    if (!produce)
+        return undefined;
+    const previous = contentFor(module, content), captured = capture(input);
+    check();
+    return cancelableModuleWork(async () => {
+        const value = await produce(previous, captured, signal);
+        check();
+        return contentFor(module, value);
+    }, signal, check);
+}

package/node_modules/@llblab/pi-state-flow/dist/lib/session.d.ts

@@ -1,5 +1,59 @@
-import { type InactiveMode, type StateFlowMode } from "./snapshot.ts";
+import { type InactiveMode, type StateFlowMode, type RetainedPolicyMigrationCandidate } from "./snapshot.ts";
+import { type ScopeSelection } from "./selection.ts";
 export declare const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
+/** Requested native policy, not proof of accepted memory or acquisition permission. */
+export interface SelectedNativeRequestPolicy {
+    readonly cwd: string;
+    readonly owner: string;
+    readonly mode: StateFlowMode;
+    readonly scopes: ScopeSelection;
+}
+/** Cancelable pre-provider turn, including Off bookkeeping; not memory/acquisition authority. */
+export type NativeContextRequest = Pick<SelectedPolicyRequest, "signal" | "revalidate">;
+export interface SelectedPolicyRequest {
+    readonly policy: SelectedNativeRequestPolicy;
+    readonly signal: AbortSignal;
+    /** Synchronous in-memory recheck, suitable for the selected runtime's native-policy port. */
+    revalidate(): void;
+}
+/** Owns policy-bound cancellation only; no storage, attachment, source acquisition or slot registry. */
+export declare class SelectedPolicyLifetime {
+    #private;
+    get policy(): SelectedNativeRequestPolicy | undefined;
+    /** Cancellation only, including Off; unlike capture(), this grants no enabled memory receipt. */
+    get signal(): AbortSignal;
+    /** Same captured policy preserves independent owners; a real choice revokes all old requests. */
+    select(value: SelectedNativeRequestPolicy): void;
+    /** Capture at admission, before any source acquisition, asynchronous wait or queued work. */
+    capture(): SelectedPolicyRequest;
+    /** Same-policy branch movement/Abort may revoke requests without inventing a different selection. */
+    invalidate(): void;
+    /** Shutdown cannot be reopened by a late selection or abort listener. */
+    end(): void;
+}
+/** One SDK turn and its finalized assistant batch; IDs are evidence only within this owned turn. */
+export declare class NativeToolRequestCorrelation {
+    #private;
+    begin(request: SelectedPolicyRequest | undefined, signal: AbortSignal | undefined, currentIdentity: () => boolean, controlSignal?: AbortSignal): void;
+    /** Stable lease from turn_start through provider preparation, before assistant finalization. */
+    preparing(): NativeContextRequest;
+    /** Provider-only revalidation of captured context data; callbacks must neither acquire nor recurse into this request. */
+    bindPreparedContext(check: () => void): void;
+    finalize(calls: readonly {
+        id: string;
+        name: string;
+    }[]): void;
+    get active(): boolean;
+    /** Identify the ambient model owner; deciding which Abort cause to forward belongs to the native port. */
+    ownsOperation(signal: AbortSignal | undefined): boolean;
+    has(id: string): boolean;
+    current(): SelectedPolicyRequest;
+    check(id: string, name: string): SelectedPolicyRequest;
+    /** Only explicit SDK parent evidence, never an ID prefix or branch-history guess. */
+    nested(id: string, name: string, parent: string): void;
+    take(id: string, name: string): SelectedPolicyRequest;
+    end(): void;
+}
 interface BranchEntry {
     type?: unknown;
     customType?: unknown;
@@ -40,6 +94,49 @@ export declare function findBranchPolicy(branch: readonly BranchEntry[], session
     mode: StateFlowMode;
     persistenceError?: string;
 } | undefined;
+/** Checkpoint-only preflight: no Stop/fork precedence, installation or authority. Invalid owned data cannot fall back. */
+export declare function prepareBranchCheckpointPolicy(branch: readonly BranchEntry[], legacySelection: ScopeSelection, inactiveMode?: InactiveMode): RetainedPolicyMigrationCandidate | undefined;
+/** Native-only policy/bookkeeping. This marker never grants canonical memory or parent-copy authority. */
+export interface SelectedNativePolicyMarker {
+    version: 2;
+    owner: string;
+    mode: StateFlowMode;
+    scopes: ScopeSelection;
+    reset?: true;
+    forkPending?: true;
+    at?: number;
+    from?: number;
+    preserveContext?: true;
+    persistenceError?: string;
+    memoryDeferred?: true;
+}
+/** Closed v2 writer value. Legacy records are translated only in branch context, never given a fabricated owner. */
+export declare function captureSelectedNativeMarker(value: unknown): SelectedNativePolicyMarker;
+export interface SelectedBranchPolicyOptions {
+    owner: string;
+    markerEntryType: string;
+    /** The caller chooses new-session versus inactive fallback mode; absence itself grants no acquisition. */
+    defaults: {
+        mode: StateFlowMode;
+        scopes: ScopeSelection;
+    };
+    inactiveMode?: InactiveMode;
+    /** Native fresh-fork fact only; no parent header or store lookup belongs in this resolver. */
+    fork?: boolean;
+}
+export interface SelectedBranchPolicyCandidate {
+    mode: StateFlowMode;
+    scopes: ScopeSelection;
+    source: "default" | "checkpoint" | "marker";
+    forkPending: boolean;
+    stop?: PassiveStopBoundary;
+    persistenceError?: string;
+    requiresCapture: boolean;
+    /** Policy-only capture preserves fences; only a separately owned acceptance may append reset/checkpoint. */
+    capture: SelectedNativePolicyMarker;
+}
+/** Complete native branch admission only; never read canonical/parent files, attach policy or confer memory authority. */
+export declare function prepareSelectedBranchPolicy(branch: readonly BranchEntry[], options: SelectedBranchPolicyOptions): SelectedBranchPolicyCandidate;
 /** Native policy bookkeeping retains an unacquired fork across extension reloads. */
 export declare function hasPendingFork(branch: readonly BranchEntry[], sessionId: string, entryType: string): boolean;
 export declare function snapshotDataNewestFirst(branch: readonly BranchEntry[]): unknown[];