@llblab/pi-kit 0.37.0 → 0.38.0

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

@@ -1,24 +1,27 @@
 import type { StateFlowMode } from "./snapshot.ts";
 import type { ScopeRevisions } from "./temporal.ts";
+import { type ScopeSelection } from "./selection.ts";
 export declare const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
 /** Resolve the package export or the compiled sibling-extension layout used in local development. */
 export declare function stateFlowTelegramSectionSpecifiers(moduleUrl?: string): string[];
 export interface StateFlowTelegramSnapshot {
     /** The current session's selected mode. */
     mode: StateFlowMode;
+    /** Wanted participating owners, not currently available bodies; omitted legacy ports retain all three. */
+    scopes?: ScopeSelection;
     /** Failed Active restoration fences inference without silently selecting an inactive mode. */
     inferenceBlocked?: boolean;
     /** Legacy branch step retained for existing adapter ports; current runtime ports also supply owner revisions. */
     step: number;
-    revisions?: ScopeRevisions;
+    revisions?: Partial<ScopeRevisions>;
     bootstrap: boolean;
     startPending: boolean;
 }
 export type StateFlowTelegramScope = "global" | "cwd" | "session" | "effective";
 export interface StateFlowTelegramState {
     artifacts?: Record<string, unknown>;
-    contract?: Record<string, unknown>;
-    working?: Record<string, unknown>;
+    strategy?: Record<string, unknown>;
+    tactics?: Record<string, unknown>;
     intents?: Record<string, unknown>;
     response?: string;
     lazy?: unknown;
@@ -87,7 +90,7 @@ export interface StateFlowTelegramControlResult {
 }
 export interface StateFlowTelegramInspection {
     state: StateFlowTelegramState;
-    revisions: ScopeRevisions;
+    revisions: Partial<ScopeRevisions>;
     /** A selection can revoke a completed observation before the adapter presents it. */
     signal?: AbortSignal;
 }
@@ -95,7 +98,7 @@ export interface StateFlowTelegramPort {
     snapshot(): StateFlowTelegramSnapshot;
     state(scope: StateFlowTelegramScope): StateFlowTelegramState;
     /** Optional additive capability; absent legacy ports retain their branch-step presentation. */
-    revisions?(): ScopeRevisions;
+    revisions?(): Partial<ScopeRevisions>;
     /** Active may need a settled native boundary; inactive modes apply immediately. */
     canStartNow(): boolean;
     /** Select the current session's mode through the same lifecycle owners as the terminal commands. */
@@ -114,9 +117,9 @@ export interface StateFlowTelegramAdapter {
 /** Main-menu section label shows only the current session mode. */
 export declare function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string;
 export declare const STATE_FLOW_MODES: readonly ["off", "passive", "active"];
-/** One radio-style mode row followed directly by read-only scope actions. */
+/** One radio-style mode row followed by the current participating owners' read-only actions. */
 export declare function buildStateFlowSectionView(snapshot: StateFlowTelegramSnapshot, callbackData: (action: string, payload?: string) => string): StateFlowTelegramView;
-export declare function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: ScopeRevisions, state: StateFlowTelegramState): StateFlowTelegramRichMessage;
+export declare function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: Partial<ScopeRevisions>, state: StateFlowTelegramState): StateFlowTelegramRichMessage;
 /** Default loader; injectable so tests and embedded hosts can control transport presence. */
 export declare function loadStateFlowTelegramModules(): Promise<StateFlowTelegramModules>;
 export declare function createStateFlowTelegramAdapter(options: {

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

@@ -12,6 +12,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { conciseDiagnostic, diagnosticText } from "./protocol.js";
 import { formatScopeRevisionVector } from "./status.js";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION } from "./selection.js";
 export const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
 /** Resolve the package export or the compiled sibling-extension layout used in local development. */
 export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url) {
@@ -35,8 +36,28 @@ function modeReceiptNotice(mode, result) {
         return undefined;
     return result.message;
 }
-/** One radio-style mode row followed directly by read-only scope actions. */
+function telegramScopes(snapshot) {
+    return captureScopeSelection(snapshot.scopes === undefined ? DEFAULT_SCOPE_SELECTION : snapshot.scopes);
+}
+function availableInspection(scope, scopes) {
+    return scope === "effective" ? scopes.length > 1 : scopes.includes(scope);
+}
+const STATE_FLOW_SCOPE_DESCRIPTIONS = {
+    global: "memory shared across projects and sessions.",
+    cwd: "memory shared by sessions in this directory.",
+    session: "private memory for this session, kept on resume.",
+};
+/** One radio-style mode row followed by the current participating owners' read-only actions. */
 export function buildStateFlowSectionView(snapshot, callbackData) {
+    const scopes = telegramScopes(snapshot);
+    const inspected = [...scopes, ...(scopes.length > 1 ? ["effective"] : [])];
+    const inspectionRows = [];
+    for (const [index, scope] of inspected.entries()) {
+        if (index % 2 === 0)
+            inspectionRows.push([]);
+        inspectionRows.at(-1).push({ text: STATE_FLOW_SCOPE_LABELS[scope], callback_data: callbackData("inspect", scope) });
+    }
+    const named = scopes.map(scope => `<code>${scope}</code>`).join(" → ");
     const modes = STATE_FLOW_MODES.map((mode) => ({
         text: `${mode === snapshot.mode ? STATE_FLOW_SELECTED_MARKERS[mode] : "⚫️"} ${STATE_FLOW_MODE_LABELS[mode]}`,
         callback_data: callbackData(mode),
@@ -52,22 +73,23 @@ export function buildStateFlowSectionView(snapshot, callbackData) {
             "<b>Mode</b> — choose a workflow (switching modes never erases stored memory):",
             "",
             "<code>-</code> <code>off</code> (default): regular chat without State Flow memory tools or context.",
-            "<code>-</code> <code>passive</code>: regular chat with memory tools; available combined memory enters the agent's context.",
+            `<code>-</code> <code>passive</code>: regular chat with memory tools; available memory from the selected ${scopes.length === 1 ? "scope" : "scopes"} enters the agent's context.`,
             "<code>-</code> <code>active</code>: same memory access; each completed answer closes a cycle, and the next request starts from saved state, not the full chat.",
             "",
-            "<b>Inspect memory</b> — view stored state even in Off:",
+            `<b>Participating scopes:</b> ${named}`,
+            ...(!scopes.includes("session") ? ["New answers are delivered, not stored: Session is excluded."] : []),
+            "",
+            "<b>Inspect participating memory</b> — view available stored state even in Off:",
             "",
-            "<code>-</code> <code>global</code>: memory shared across projects and sessions.",
-            "<code>-</code> <code>cwd</code>: memory shared by sessions in this directory.",
-            "<code>-</code> <code>session</code>: private memory for this session, kept on resume.",
-            "<code>-</code> <code>effective</code>: merged Global, CWD and Session state; the agent can use it when memory is enabled and available.",
+            ...scopes.map(scope => `<code>-</code> <code>${scope}</code>: ${STATE_FLOW_SCOPE_DESCRIPTIONS[scope]}`),
+            ...(scopes.length > 1
+                ? [`<code>-</code> <code>effective</code>: validated available ${named} overlay; excluded scopes do not contribute.`]
+                : ["This single scope is also the agent's effective state; no separate overlay is needed."]),
         ].join("\n"),
         parseMode: "html",
         replyMarkup: { inline_keyboard: [
                 modes,
-                ...[["global", "cwd"], ["session", "effective"]].map((row) => row.map((scope) => ({
-                    text: STATE_FLOW_SCOPE_LABELS[scope], callback_data: callbackData("inspect", scope),
-                }))),
+                ...inspectionRows,
             ] },
     };
 }
@@ -106,10 +128,10 @@ function renderStateFlowTelegramField(value) {
 }
 export function renderStateFlowRichState(scope, revisions, state) {
     const fields = scope === "global" || scope === "cwd"
-        ? ["intents", "contract", "working", "artifacts", "lazy"]
-        : ["intents", "contract", "working", "artifacts", "response", "lazy"];
+        ? ["intents", "strategy", "tactics", "artifacts", "lazy"]
+        : ["intents", "strategy", "tactics", "artifacts", "response", "lazy"];
     const revision = scope === "effective"
-        ? formatScopeRevisionVector(revisions)
+        ? formatScopeRevisionVector(revisions, captureScopeSelection(Object.keys(revisions)))
         : `#${revisions[scope]}`;
     return {
         blocks: [
@@ -149,10 +171,20 @@ function buildStateFlowTelegramSection(port, isActive) {
                 if (ctx.action === "inspect") {
                     if (!isStateFlowTelegramScope(ctx.payload))
                         throw new Error("Unknown State Flow scope");
+                    const scopes = telegramScopes(port.snapshot());
+                    if (!availableInspection(ctx.payload, scopes))
+                        throw new Error(ctx.payload === "effective"
+                            ? "Effective requires at least two participating scopes; inspect the single owner instead"
+                            : `State Flow ${ctx.payload} scope is excluded from this menu`);
+                    const checkSelection = () => {
+                        if (telegramScopes(port.snapshot()).join(" ") !== scopes.join(" "))
+                            throw new Error("State Flow inspection selection changed; select the scope again");
+                    };
                     let observation;
                     if ("inspect" in port) {
                         await ctx.answerCallback("Reading State Flow memory");
                         acknowledged = true;
+                        checkSelection();
                         observation = await port.inspect(ctx.payload);
                     }
                     else {
@@ -161,9 +193,13 @@ function buildStateFlowTelegramSection(port, isActive) {
                         observation = { state, revisions: port.revisions?.() ?? live.revisions ?? { global: live.step, cwd: live.step, session: live.step } };
                     }
                     observation.signal?.throwIfAborted();
+                    checkSelection();
                     if (request !== interaction || !isActive())
                         return "handled";
-                    await ctx.openRich(renderStateFlowRichState(ctx.payload, observation.revisions, observation.state));
+                    const revisions = ctx.payload === "effective"
+                        ? Object.fromEntries(scopes.filter(scope => Object.hasOwn(observation.revisions, scope)).map(scope => [scope, observation.revisions[scope]]))
+                        : observation.revisions;
+                    await ctx.openRich(renderStateFlowRichState(ctx.payload, revisions, observation.state));
                     if (!acknowledged)
                         await ctx.answerCallback();
                     return "handled";

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

@@ -1,4 +1,6 @@
+import { type ScopeSelection } from "./selection.ts";
 import { type RecentScopePatch } from "./history.ts";
+import { type RetainedModules } from "./semantic-module.ts";
 import { type MaterializedState, type SemanticState, type ScopedSemanticStates, type StateScope } from "./state.ts";
 /** Owns hot temporal algebra; excludes filesystem, Git, identity allocation, and Pi lifecycle. */
 export interface TransitionBoundary {
@@ -16,6 +18,8 @@ export interface TemporalPatch {
     patch: RecentScopePatch["patch"];
 }
 export interface ScopeStream {
+    /** Presence selects metadata4; absent preserves the legacy exact three-key stream. */
+    modules?: RetainedModules;
     /** Monotonic semantic revision owned by this scope; independent of branch-local boundary positions. */
     revision: number;
     checkpoint: ScopeCheckpoint;
@@ -26,27 +30,59 @@ export interface TemporalState {
     lineage: TransitionBoundary[];
     scopes: Record<StateScope, ScopeStream>;
 }
+/** Value-only witnesses copied from a validated cohort; not physical store/publication authority. */
+export interface ExcludedTransitionWitness {
+    transition: TransitionBoundary;
+    owners: ScopeSelection;
+}
+export interface SelectedTemporalState {
+    selection: ScopeSelection;
+    lineage: TransitionBoundary[];
+    scopes: Partial<Record<StateScope, ScopeStream>>;
+    /** Only excluded-owner witnesses for retained steps with no selected semantic patch. No values or patches. */
+    causalBasis: ExcludedTransitionWitness[];
+}
+type TemporalCohort = TemporalState | SelectedTemporalState;
 export type ScopeRevisions = Record<StateScope, number>;
 /** Replay validation is shared by disk codecs and active-lineage materialization. */
 export declare function validateScopeStream(value: unknown, scope: StateScope, historyLimit?: number): asserts value is ScopeStream;
 export declare function validateTemporalLineage(value: unknown, historyLimit?: number): asserts value is TransitionBoundary[];
 /** Bind one owned stream to its runtime lineage without requiring patches from unrelated scopes. */
 export declare function validateScopeLineage(stream: ScopeStream, scope: StateScope, lineage: readonly TransitionBoundary[], historyLimit?: number): void;
+/** Classify live shared drift only after both stream and lineage have passed their own validators. */
+export declare function scopeLineageMatches(stream: ScopeStream, scope: StateScope, lineage: readonly TransitionBoundary[], historyLimit?: number): boolean;
 /** Validate one revision-selected cohort. Its older ancestry must be bound by the durable loader. */
 export declare function validateTemporalState(view: TemporalState, historyLimit?: number): void;
+/** Structural consistency only: storage must additionally bind witnesses to accepted source authority. */
+export declare function validateSelectedTemporalState(view: SelectedTemporalState, historyLimit?: number): void;
 /** Adopt revision-proven inherited streams without rewriting their checkpoints or tails. */
 export declare function adoptTemporalStreams(scopes: Record<StateScope, ScopeStream>, id: string, historyLimit?: number): TemporalState;
 /** New or migrated state starts at a proven current boundary, with no invented past. */
 export declare function createTemporalState(states: ScopedSemanticStates, id: string, historyLimit?: number): TemporalState;
+/** Restrict a validated value cohort; expanding selection requires separately acquired current streams. */
+export declare function selectTemporalState(source: TemporalCohort, selection: ScopeSelection, historyLimit?: number): SelectedTemporalState;
+/** Complete retained witness skeleton, derived from validated semantic records/basis, never from lineage alone. */
+export declare function temporalCausalWitnesses(view: TemporalCohort, historyLimit?: number): ExcludedTransitionWitness[];
+/** Metadata syntax only; a skeleton is neither semantic replay nor acquisition/publication authority. */
+export declare function captureTemporalWitnesses(lineage: readonly TransitionBoundary[], witnesses: unknown, historyLimit?: number): ExcludedTransitionWitness[];
+/** Reconstruct selected values from caller-bound accepted evidence; this validates syntax/consistency, not physical authority. */
+export declare function restoreSelectedTemporalState(scopes: Partial<Record<StateScope, ScopeStream>>, selection: ScopeSelection, lineage: readonly TransitionBoundary[], witnesses: unknown, historyLimit?: number): SelectedTemporalState;
+/** Explicit selected values at a new origin; this constructor grants no initialization/acquisition permission. */
+export declare function createSelectedTemporalState(states: Partial<ScopedSemanticStates>, selection: ScopeSelection, id: string, historyLimit?: number): SelectedTemporalState;
+/** Adopt explicitly admitted selected streams at current values only, without invented aligned history. */
+export declare function adoptSelectedTemporalStreams(scopes: Partial<Record<StateScope, ScopeStream>>, selection: ScopeSelection, id: string, historyLimit?: number): SelectedTemporalState;
 /** Fold retained tails to a lower configured limit without inventing history. */
-export declare function constrainTemporalState(view: TemporalState, historyLimit: number): TemporalState;
+export declare function constrainTemporalState<T extends TemporalCohort>(view: T, historyLimit: number): T;
 /** Current independent scope revisions; Effective uses this vector rather than inventing a scalar owner. */
 export declare function temporalScopeRevisions(view: TemporalState): ScopeRevisions;
+export declare function temporalScopeRevisions(view: SelectedTemporalState): Partial<ScopeRevisions>;
 /** Exact scope semantics for authored staging; defaults must never become implicit writes. */
 export declare function readTemporalScopes(view: TemporalState, offset?: number, historyLimit?: number): ScopedSemanticStates;
+export declare function readTemporalScopes(view: SelectedTemporalState, offset?: number, historyLimit?: number): Partial<ScopedSemanticStates>;
 /** Sparse current/historical view: unknown planes and absent values never become effective data. */
-export declare function readTemporalView(view: TemporalState, offset?: number, scope?: StateScope, historyLimit?: number): SemanticState;
+export declare function readTemporalView(view: TemporalCohort, offset?: number, scope?: StateScope, historyLimit?: number): SemanticState;
 /** Internal defaulted materialization for consumers that require object registries. */
-export declare function readTemporalState(view: TemporalState, offset?: number, scope?: StateScope, historyLimit?: number): MaterializedState;
+export declare function readTemporalState(view: TemporalCohort, offset?: number, scope?: StateScope, historyLimit?: number): MaterializedState;
 /** Allocate the identity outside this algebra; only materially effective patches accept it. */
-export declare function advanceTemporalState(view: TemporalState, transitions: readonly RecentScopePatch[], id: string, historyLimit?: number): TemporalState;
+export declare function advanceTemporalState<T extends TemporalCohort>(view: T, transitions: readonly RecentScopePatch[], id: string, historyLimit?: number): T;
+export {};