pi-loop-graph-sdk 0.2.0

package/dist/core/context.js

@@ -0,0 +1,229 @@
+/** Canonical, scope-owned context state for one Graph Invocation. */
+export class ContextState {
+    options;
+    graphLayers = Object.freeze([]);
+    contributions = new Map();
+    frameRevision;
+    memoryCache = null;
+    constructor(options) {
+        this.options = options;
+        this.frameRevision = options.frameRevision ?? { value: 0 };
+    }
+    async initialize() {
+        const { graph, graphInput, graphSkills } = this.options;
+        const background = await materializeProjection(graph.context.background, graphInput, {
+            graph: { id: graph.id, version: graph.version, goal: graph.goal },
+            skills: graphSkills,
+        }, defaultGraphRenderer);
+        this.graphLayers = Object.freeze([
+            ...(this.options.hostContent == null ? [] : [{
+                    name: "host",
+                    scopeId: this.options.rootRunId,
+                    retention: "sticky",
+                    content: this.options.hostContent,
+                }]),
+            ...(background == null ? [] : [{
+                    name: "graph",
+                    scopeId: this.options.graphInvocationId,
+                    retention: "sticky",
+                    content: background,
+                }]),
+        ]);
+    }
+    bumpMemoryRevision() {
+        this.frameRevision.value += 1;
+    }
+    async materializeNode(nodeVisitId, stageId, stage, nodeInput, nodeSkills) {
+        const memory = await this.materializeMemory();
+        const nodeLayer = stage.node.kind === "graph"
+            ? null
+            : await materializeNodeLayer(stage.node, stage, nodeInput, nodeSkills, nodeVisitId);
+        const layers = [...this.graphLayers];
+        if (memory != null) {
+            layers.push({
+                name: "memory",
+                scopeId: this.options.graphInvocationId,
+                retention: "foldable",
+                content: memory,
+            });
+        }
+        if (nodeLayer)
+            layers.push(nodeLayer);
+        return {
+            nodeVisitId,
+            stageId,
+            snapshot: this.snapshot(nodeVisitId, layers),
+        };
+    }
+    snapshot(nodeVisitId, layers = this.graphLayers) {
+        const contributions = [
+            ...(this.options.externalContributions?.(nodeVisitId) ?? []),
+            ...this.contributions.values(),
+        ];
+        const mechanismLayers = ["sticky", "foldable", "transient"].flatMap((retention) => {
+            const content = contributions
+                .filter((item) => item.retention === retention)
+                .flatMap((item) => typeof item.content === "string"
+                ? [{ type: "text", text: item.content }]
+                : item.content);
+            return content.length === 0 ? [] : [{
+                    name: "mechanism",
+                    scopeId: nodeVisitId ?? this.options.graphInvocationId,
+                    retention,
+                    content: Object.freeze(content.map((block) => Object.freeze({ ...block }))),
+                }];
+        });
+        const projectedLayers = [...layers, ...mechanismLayers];
+        return Object.freeze({
+            rootRunId: this.options.rootRunId,
+            graphInvocationId: this.options.graphInvocationId,
+            nodeVisitId,
+            graphId: this.options.graph.id,
+            graphVersion: this.options.graph.version,
+            memoryRevision: this.frameRevision.value,
+            layers: Object.freeze(projectedLayers.map((layer) => Object.freeze({ ...layer }))),
+            contributions: Object.freeze(contributions.map((item) => Object.freeze({ ...item }))),
+        });
+    }
+    refreshSnapshot(snapshot, agentRunId) {
+        return Object.freeze({
+            ...this.snapshot(snapshot.nodeVisitId, snapshot.layers.filter((layer) => layer.name !== "mechanism")),
+            ...(agentRunId === undefined ? {} : { agentRunId }),
+        });
+    }
+    addContribution(contribution) {
+        if (this.contributions.has(contribution.id))
+            throw new Error(`Context contribution already exists: ${contribution.id}`);
+        this.contributions.set(contribution.id, freezeContribution(contribution));
+        let active = true;
+        return Object.freeze({
+            id: contribution.id,
+            update: (content) => {
+                if (!active)
+                    throw new Error(`Context contribution is disposed: ${contribution.id}`);
+                const current = this.contributions.get(contribution.id);
+                if (!current)
+                    throw new Error(`Context contribution is unavailable: ${contribution.id}`);
+                this.contributions.set(contribution.id, freezeContribution({ ...current, content }));
+            },
+            dispose: () => {
+                if (!active)
+                    return;
+                active = false;
+                this.contributions.delete(contribution.id);
+            },
+        });
+    }
+    async materializeMemory() {
+        const projection = this.options.graph.context.memory ?? { select: "all" };
+        if (this.memoryCache?.revision === this.frameRevision.value)
+            return this.memoryCache.content;
+        const content = await materializeProjection(projection, this.options.frames, {
+            graph: { id: this.options.graph.id, version: this.options.graph.version },
+            revision: this.frameRevision.value,
+        }, defaultMemoryRenderer);
+        this.memoryCache = { revision: this.frameRevision.value, content };
+        return content;
+    }
+}
+function freezeContribution(contribution) {
+    const content = normalizeContextContent(contribution.content);
+    if (content == null)
+        throw new Error("Context contribution content cannot be empty");
+    return Object.freeze({ ...contribution, content });
+}
+async function materializeNodeLayer(node, stage, nodeInput, skills, nodeVisitId) {
+    const projection = node.context?.focus ?? (node.kind === "agent"
+        ? { select: "all" }
+        : { select: "none" });
+    const content = await materializeProjection(projection, nodeInput, {
+        node: {
+            kind: node.kind,
+            subGoal: node.subGoal,
+            identity: node.identity,
+        },
+        skills,
+        connections: stage.route.connections.map((connection) => ({
+            id: connection.id,
+            to: connection.to,
+        })),
+    }, defaultNodeRenderer);
+    return content == null ? null : {
+        name: "node",
+        scopeId: nodeVisitId,
+        retention: "sticky",
+        content,
+    };
+}
+export async function materializeProjection(projection, source, meta, fallback) {
+    const selected = projection.select === "all"
+        ? source
+        : projection.select === "none"
+            ? null
+            : await projection.select(source);
+    const frozen = selected == null ? null : deepFreeze(cloneJson(selected));
+    const rendered = projection.render
+        ? await projection.render({ selected: frozen, meta: Object.freeze(meta) })
+        : fallback({ selected: frozen, meta: Object.freeze(meta) });
+    return normalizeContextContent(rendered);
+}
+function defaultGraphRenderer(input) {
+    const lines = [`=== GRAPH GOAL ===\n${input.meta.graph.goal}`];
+    if (input.selected != null)
+        lines.push(`=== BACKGROUND ===\n${JSON.stringify(input.selected)}`);
+    for (const skill of input.meta.skills)
+        lines.push(skill.content);
+    return lines.join("\n");
+}
+function defaultMemoryRenderer(input) {
+    return input.selected == null || Array.isArray(input.selected) && input.selected.length === 0
+        ? null
+        : `=== COMPLETED WORK ===\n${JSON.stringify(input.selected)}`;
+}
+function defaultNodeRenderer(input) {
+    const lines = [
+        `=== NODE SUBGOAL ===\n${input.meta.node.subGoal}`,
+    ];
+    if (input.selected != null)
+        lines.push(`=== NODE FOCUS ===\n${JSON.stringify(input.selected)}`);
+    if (input.meta.connections.length)
+        lines.push(`=== CONNECTIONS ===\n${JSON.stringify(input.meta.connections)}`);
+    for (const skill of input.meta.skills)
+        lines.push(skill.content);
+    return lines.join("\n");
+}
+function normalizeContextContent(content) {
+    if (content == null)
+        return null;
+    const values = Array.isArray(content) ? content : [content];
+    const blocks = [];
+    for (const value of values) {
+        if (typeof value === "string")
+            blocks.push({ type: "text", text: value });
+        else if (isContextBlock(value))
+            blocks.push(Object.freeze({ ...value }));
+        else
+            throw new Error("Context renderer returned invalid content");
+    }
+    return Object.freeze(blocks.length === 1 && blocks[0].type === "text" ? blocks[0].text : blocks);
+}
+function isContextBlock(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const block = value;
+    return block.type === "text" && typeof block.text === "string"
+        || block.type === "image" && typeof block.data === "string" && typeof block.mimeType === "string";
+}
+function deepFreeze(value, seen = new WeakSet()) {
+    if (!value || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return value;
+    seen.add(value);
+    for (const child of Object.values(value))
+        deepFreeze(child, seen);
+    return Object.freeze(value);
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/core/graph.d.ts

@@ -0,0 +1,172 @@
+import type { TSchema, Static } from "typebox";
+import type { JsonSchema, JsonValue } from "./json.js";
+import type { ResolvedSkillView, SkillRef } from "./skill.js";
+import type { Mechanism } from "./mechanism.js";
+export type Awaitable<T> = T | Promise<T>;
+export type SchemaValue<S extends TSchema> = Static<S>;
+export interface GraphRef {
+    readonly id: string;
+    readonly version: string;
+}
+export interface NodeIdentity {
+    readonly name: string;
+    readonly version?: string;
+}
+export interface ContextBlockText {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface ContextBlockImage {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+}
+export type ContextBlock = ContextBlockText | ContextBlockImage;
+export type ContextContent = string | readonly ContextBlock[];
+export type ContextSelector<TSource, TSelected extends JsonValue> = "all" | "none" | ((source: Readonly<TSource>) => Awaitable<TSelected | null>);
+export interface ContextRenderInput<TSelected extends JsonValue, TMeta> {
+    readonly selected: Readonly<TSelected> | null;
+    readonly meta: Readonly<TMeta>;
+}
+export type ContextRenderer<TSelected extends JsonValue, TMeta> = (input: ContextRenderInput<TSelected, TMeta>) => Awaitable<ContextContent | readonly ContextContent[] | null>;
+export interface ContextProjection<TSource, TSelected extends JsonValue, TMeta> {
+    readonly select: ContextSelector<TSource, TSelected>;
+    readonly render?: ContextRenderer<TSelected, TMeta>;
+}
+export interface GraphContextMeta {
+    readonly graph: {
+        readonly id: string;
+        readonly version: string;
+        readonly goal: string;
+    };
+    readonly skills: readonly ResolvedSkillView[];
+}
+export interface GraphMemoryMeta {
+    readonly graph: {
+        readonly id: string;
+        readonly version: string;
+    };
+    readonly revision: number;
+}
+export interface NodeContextMeta {
+    readonly node: {
+        readonly kind: "agent" | "code" | "graph";
+        readonly subGoal: string;
+        readonly identity?: NodeIdentity;
+    };
+    readonly skills: readonly ResolvedSkillView[];
+    readonly connections: readonly ConnectionView[];
+}
+export interface ConnectionView {
+    readonly id: string;
+    readonly to: string | "__graph_finish__";
+}
+export interface GraphContextDefinition<TInput, TBackground extends JsonValue, TMemory extends JsonValue> {
+    readonly background: ContextProjection<TInput, TBackground, GraphContextMeta>;
+    readonly memory?: ContextProjection<readonly JsonValue[], TMemory, GraphMemoryMeta>;
+}
+export interface NodeContextDefinition<TInput, TFocus extends JsonValue = any> {
+    readonly focus: ContextProjection<TInput, TFocus, NodeContextMeta>;
+}
+export interface NodeCompletion<TResult = JsonValue> {
+    readonly result: TResult;
+}
+export interface CodeNodeExecution<TInput, TResult> {
+    readonly input: Readonly<TInput>;
+    readonly complete: (result: TResult) => TResult;
+    readonly runAgent: (request: AgentRunRequest) => Promise<NodeCompletion>;
+    /** Present during resume; use for idempotent-side-effect guards. */
+    readonly resumeAttempt?: number;
+    readonly nodeVisitId?: string;
+    readonly rootRunId?: string;
+}
+export interface AgentRunRequest {
+    readonly prompt: string;
+    readonly output?: JsonSchema;
+}
+export interface AgentNodeDefinition<TInputSchema extends TSchema = TSchema, TResultSchema extends TSchema = TSchema, TFocus extends JsonValue = any> {
+    readonly kind: "agent";
+    readonly subGoal: string;
+    readonly input: JsonSchema<TInputSchema>;
+    readonly output: JsonSchema<TResultSchema>;
+    readonly identity?: NodeIdentity;
+    readonly context?: NodeContextDefinition<SchemaValue<TInputSchema>, TFocus>;
+    readonly tools?: readonly string[] | "all";
+    readonly skills?: readonly SkillRef[];
+    readonly prompt?: string;
+    readonly mechanisms?: readonly Mechanism[];
+}
+export interface CodeNodeDefinition<TInputSchema extends TSchema = TSchema, TResultSchema extends TSchema = TSchema, TFocus extends JsonValue = any> {
+    readonly kind: "code";
+    readonly subGoal: string;
+    readonly input: JsonSchema<TInputSchema>;
+    readonly output: JsonSchema<TResultSchema>;
+    readonly identity?: NodeIdentity;
+    readonly context?: NodeContextDefinition<SchemaValue<TInputSchema>, TFocus>;
+    readonly tools?: readonly string[] | "all";
+    readonly skills?: readonly SkillRef[];
+    readonly execute: (execution: CodeNodeExecution<SchemaValue<TInputSchema>, SchemaValue<TResultSchema>>) => Awaitable<SchemaValue<TResultSchema>>;
+    readonly mechanisms?: readonly Mechanism[];
+}
+export interface GraphNodeDefinition<TInputSchema extends TSchema = TSchema, TResultSchema extends TSchema = TSchema> {
+    readonly kind: "graph";
+    readonly subGoal: string;
+    readonly input: JsonSchema<TInputSchema>;
+    readonly output: JsonSchema<TResultSchema>;
+    readonly identity?: NodeIdentity;
+    readonly graph: GraphRef;
+    readonly boundary: "call" | "compose" | "delegate";
+    readonly skills?: readonly SkillRef[];
+    readonly mechanisms?: readonly Mechanism[];
+}
+export type NodeDefinition = AgentNodeDefinition<any, any, any> | CodeNodeDefinition<any, any, any> | GraphNodeDefinition<any, any>;
+export interface Entry<TInput = JsonValue> {
+    readonly id: string;
+    readonly to: string;
+    readonly guard?: (input: Readonly<TInput>) => Awaitable<boolean>;
+    readonly mapInput?: (input: Readonly<TInput>) => JsonValue;
+}
+export interface Transition<TCompletion extends JsonValue = JsonValue, TFrame extends JsonValue = JsonValue, TInput extends JsonValue = JsonValue> {
+    readonly guard?: (input: Readonly<TCompletion>) => Awaitable<boolean>;
+    readonly frame?: (input: {
+        readonly completion: Readonly<NodeCompletion<TCompletion>>;
+    }) => TFrame;
+    readonly map?: (input: {
+        readonly completion: Readonly<NodeCompletion<TCompletion>>;
+    }) => TInput;
+    readonly output?: (input: {
+        readonly completion: Readonly<NodeCompletion<TCompletion>>;
+    }) => JsonValue;
+}
+export type ContextFrame = JsonValue;
+export interface Connection {
+    readonly id: string;
+    readonly to: string | "__graph_finish__";
+    readonly transition: Transition;
+}
+export interface Route {
+    readonly kind: "first-match" | "priority-first" | "agent-choice" | "custom";
+    readonly connections: readonly Connection[];
+}
+export interface Stage {
+    readonly node: NodeDefinition;
+    readonly route: Route;
+}
+export type GraphToolPolicy = readonly string[];
+export interface GraphDefinition<TInputSchema extends TSchema = TSchema, TOutputSchema extends TSchema = TSchema, TBackground extends JsonValue = any, TMemory extends JsonValue = any> {
+    readonly id: string;
+    readonly version: string;
+    readonly goal: string;
+    readonly input: JsonSchema<TInputSchema>;
+    readonly output: JsonSchema<TOutputSchema>;
+    readonly context: GraphContextDefinition<SchemaValue<TInputSchema>, TBackground, TMemory>;
+    readonly entries: readonly Entry<SchemaValue<TInputSchema>>[];
+    readonly stages: Readonly<Record<string, Stage>>;
+    readonly tools?: GraphToolPolicy;
+    readonly skills?: readonly SkillRef[];
+    readonly mechanisms?: readonly Mechanism[];
+}
+export type Graph<TInputSchema extends TSchema = TSchema, TOutputSchema extends TSchema = TSchema, TBackground extends JsonValue = any, TMemory extends JsonValue = any> = GraphDefinition<TInputSchema, TOutputSchema, TBackground, TMemory>;
+export declare function graphRef(id: string, version: string): GraphRef;
+export declare function defineGraph<TInputSchema extends TSchema, TOutputSchema extends TSchema, TBackground extends JsonValue, TMemory extends JsonValue = JsonValue>(graph: GraphDefinition<TInputSchema, TOutputSchema, TBackground, TMemory>): Graph<TInputSchema, TOutputSchema, TBackground, TMemory>;
+export declare function validateGraphDefinition<TInputSchema extends TSchema, TOutputSchema extends TSchema, TBackground extends JsonValue, TMemory extends JsonValue>(graph: GraphDefinition<TInputSchema, TOutputSchema, TBackground, TMemory>): void;

package/dist/core/graph.js

@@ -0,0 +1,57 @@
+export function graphRef(id, version) {
+    if (!id || !version)
+        throw new Error("GraphRef requires id and version");
+    return Object.freeze({ id, version });
+}
+export function defineGraph(graph) {
+    validateGraphDefinition(graph);
+    const stages = Object.fromEntries(Object.entries(graph.stages).map(([id, stage]) => [
+        id,
+        Object.freeze({
+            ...stage,
+            route: Object.freeze({
+                ...stage.route,
+                connections: Object.freeze(stage.route.connections.map((connection) => Object.freeze({
+                    ...connection,
+                    transition: Object.freeze({ ...connection.transition }),
+                }))),
+            }),
+        }),
+    ]));
+    return Object.freeze({
+        ...graph,
+        stages: Object.freeze(stages),
+        entries: Object.freeze(graph.entries.map((item) => Object.freeze({ ...item }))),
+    });
+}
+export function validateGraphDefinition(graph) {
+    if (!graph.id || !graph.version || !graph.goal)
+        throw new Error("Graph requires id, version, and goal");
+    if (!graph.entries.length)
+        throw new Error("Graph requires at least one entry");
+    const entryIds = new Set();
+    for (const entry of graph.entries) {
+        if (entryIds.has(entry.id))
+            throw new Error(`Duplicate Entry ID: ${entry.id}`);
+        entryIds.add(entry.id);
+    }
+    for (const [stageId, stage] of Object.entries(graph.stages)) {
+        if (!stageId)
+            throw new Error("Stage ID cannot be empty");
+        const connectionIds = new Set();
+        for (const connection of stage.route.connections) {
+            if (connectionIds.has(connection.id))
+                throw new Error(`Duplicate Connection ID in Stage "${stageId}": ${connection.id}`);
+            connectionIds.add(connection.id);
+            if (connection.to !== "__graph_finish__" && !(connection.to in graph.stages)) {
+                throw new Error(`Connection "${connection.id}" targets missing Stage "${connection.to}"`);
+            }
+            if (connection.to === "__graph_finish__" && !connection.transition.output) {
+                throw new Error(`Finish Connection "${connection.id}" requires an explicit output mapper`);
+            }
+        }
+    }
+    for (const entry of graph.entries)
+        if (!(entry.to in graph.stages))
+            throw new Error(`Entry "${entry.id}" targets missing Stage "${entry.to}"`);
+}

package/dist/core/json.d.ts

@@ -0,0 +1,8 @@
+import type { TSchema, Static } from "typebox";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type JsonSchema<T extends TSchema = TSchema> = T;
+export type JsonSchemaValue<T extends TSchema> = Static<T> & JsonValue;
+export declare function isJsonValue(value: unknown): value is JsonValue;

package/dist/core/json.js

@@ -0,0 +1,46 @@
+export function isJsonValue(value) {
+    return isJsonValueInternal(value, new WeakSet());
+}
+function isJsonValueInternal(value, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object")
+        return false;
+    if (ancestors.has(value))
+        return false;
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (Object.getOwnPropertySymbols(value).length > 0)
+                return false;
+            if (Object.getOwnPropertyNames(value).length !== value.length + 1)
+                return false;
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.hasOwn(value, index) || !isJsonValueInternal(value[index], ancestors))
+                    return false;
+            }
+            return true;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        if (Object.getOwnPropertySymbols(value).length > 0)
+            return false;
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        for (const descriptor of Object.values(descriptors)) {
+            if (!descriptor.enumerable || !("value" in descriptor))
+                return false;
+            if (!isJsonValueInternal(descriptor.value, ancestors))
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}

package/dist/core/limits.d.ts

@@ -0,0 +1,7 @@
+export interface InvocationLimits {
+    readonly maxGraphDepth: number;
+    readonly maxGraphInvocations: number;
+    readonly maxTotalNodeVisits: number;
+}
+export declare const DEFAULT_INVOCATION_LIMITS: InvocationLimits;
+export declare function resolveInvocationLimits(limits?: Partial<InvocationLimits>): InvocationLimits;

package/dist/core/limits.js

@@ -0,0 +1,14 @@
+export const DEFAULT_INVOCATION_LIMITS = Object.freeze({
+    maxGraphDepth: 8,
+    maxGraphInvocations: 64,
+    maxTotalNodeVisits: 500,
+});
+export function resolveInvocationLimits(limits = {}) {
+    const resolved = { ...DEFAULT_INVOCATION_LIMITS, ...limits };
+    for (const [name, value] of Object.entries(resolved)) {
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new Error(`${name} must be a positive integer`);
+        }
+    }
+    return Object.freeze(resolved);
+}

package/dist/core/mechanism.d.ts

@@ -0,0 +1,88 @@
+import type { ContextContent } from "./graph.js";
+import type { ContextLifetime, ContextRetention, ContextContributionHandle } from "./context.js";
+import type { JsonValue } from "./json.js";
+export type MechanismInstallation = "host" | "graph" | "node";
+export type MechanismFailurePolicy = "continue" | "fail-node" | "fail-graph";
+export type MechanismHookName = "onRootEnter" | "onRootExit" | "onGraphEnter" | "onGraphExit" | "onGraphError" | "onNodeEnter" | "onNodeExit" | "onNodeError" | "beforeAgentRun" | "afterAgentRun" | "validateCompletion";
+export interface MechanismScope {
+    readonly scopeId: string;
+    readonly installation: MechanismInstallation;
+    readonly signal: AbortSignal;
+    isActive(): boolean;
+    onCleanup(cleanup: () => void | Promise<void>): void;
+}
+export interface MechanismContextApi {
+    add(id: string, content: ContextContent, options?: {
+        readonly lifetime?: ContextLifetime;
+        readonly retention?: ContextRetention;
+    }): ContextContributionHandle;
+}
+export interface MechanismExecResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly truncated: boolean;
+}
+export interface MechanismExec {
+    run(file: string, args?: readonly string[], options?: {
+        readonly cwd?: string;
+        readonly timeoutMs?: number;
+    }): Promise<MechanismExecResult>;
+}
+export interface MechanismDecisionTrace {
+    readonly mechanismName: string;
+    readonly hook: MechanismHookName;
+    readonly decision: "allow" | "reject" | "fail-node" | "fail-graph";
+    readonly reason?: string;
+    readonly timestamp: number;
+}
+export interface MechanismContext<TState = JsonValue> {
+    readonly rootRunId: string;
+    readonly graphInvocationId?: string;
+    readonly nodeVisitId?: string;
+    readonly agentRunId?: string;
+    readonly stageId?: string;
+    readonly state: TState;
+    readonly scope: MechanismScope;
+    readonly context: MechanismContextApi;
+    readonly exec: MechanismExec;
+    /** Direct Host adapter access is unmanaged and generates a runtime warning when read. */
+    readonly pi?: unknown;
+}
+export type MechanismCompletionDecision = {
+    readonly action: "allow";
+    readonly verifiedResult?: JsonValue;
+} | {
+    readonly action: "reject" | "fail-node" | "fail-graph";
+    readonly reason: string;
+};
+export interface Mechanism<TState extends JsonValue = JsonValue> {
+    readonly name: string;
+    readonly allowMultiple?: boolean;
+    readonly failurePolicy?: MechanismFailurePolicy;
+    createState?(): TState;
+    snapshot?(state: Readonly<TState>): JsonValue;
+    restore?(snapshot: JsonValue): TState;
+    onRootEnter?(ctx: MechanismContext<TState>): void | Promise<void>;
+    onRootExit?(ctx: MechanismContext<TState>): void | Promise<void>;
+    onGraphEnter?(ctx: MechanismContext<TState>): void | Promise<void>;
+    onGraphExit?(ctx: MechanismContext<TState>): void | Promise<void>;
+    onGraphError?(ctx: MechanismContext<TState> & {
+        readonly error: unknown;
+    }): void | Promise<void>;
+    onNodeEnter?(ctx: MechanismContext<TState>): void | Promise<void>;
+    onNodeExit?(ctx: MechanismContext<TState> & {
+        readonly completion: JsonValue;
+    }): void | Promise<void>;
+    onNodeError?(ctx: MechanismContext<TState> & {
+        readonly error: unknown;
+    }): void | Promise<void>;
+    beforeAgentRun?(ctx: MechanismContext<TState> & {
+        readonly prompt: string;
+    }): void | Promise<void>;
+    afterAgentRun?(ctx: MechanismContext<TState>): void | Promise<void>;
+    validateCompletion?(ctx: MechanismContext<TState> & {
+        readonly completion: JsonValue;
+    }): MechanismCompletionDecision | Promise<MechanismCompletionDecision>;
+}
+export declare function defineMechanism<TState extends JsonValue>(mechanism: Mechanism<TState>): Mechanism<TState>;

package/dist/core/mechanism.js

@@ -0,0 +1,5 @@
+export function defineMechanism(mechanism) {
+    if (!mechanism.name.trim())
+        throw new Error("Mechanism name is required");
+    return Object.freeze({ ...mechanism });
+}

package/dist/core/result.d.ts

@@ -0,0 +1,41 @@
+import type { JsonValue } from "./json.js";
+export type GraphFailureCode = "invalid-graph" | "invalid-input" | "entry-not-found" | "tool-unavailable" | "host-unavailable" | "agent-timeout" | "agent-ended-without-completion" | "validation-exhausted" | "max-steps-exceeded" | "no-route" | "transition-failed" | "mechanism-failed" | "persistence-failed" | "resume-incompatible" | "runtime-error" | "cancelled";
+export type GraphFailurePhase = "root" | "graph" | "entry" | "node" | "agent" | "route" | "transition" | "host";
+export interface GraphFailure {
+    readonly code: GraphFailureCode;
+    readonly phase: GraphFailurePhase;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly stageId?: string;
+    readonly cause?: unknown;
+}
+export type RecordingMode = "off" | "events" | "replay" | "forensic";
+export interface ReplayReference {
+    readonly mode: RecordingMode;
+    readonly status: "off" | "complete" | "incomplete" | "failed";
+    readonly location?: string;
+    readonly issues?: readonly string[];
+}
+export interface GraphRunCommon {
+    readonly rootRunId: string;
+    readonly graphId: string;
+    readonly graphVersion: string;
+    readonly steps: number;
+    readonly durationMs: number;
+    readonly replay: ReplayReference;
+}
+export interface CompletedGraphRun<TOutput = JsonValue> extends GraphRunCommon {
+    readonly status: "completed";
+    readonly output: TOutput;
+}
+export interface FailedGraphRun extends GraphRunCommon {
+    readonly status: "failed";
+    readonly failure: GraphFailure;
+}
+export interface CancelledGraphRun extends GraphRunCommon {
+    readonly status: "cancelled";
+    readonly failure: GraphFailure & {
+        readonly code: "cancelled";
+    };
+}
+export type GraphRunResult<TOutput = JsonValue> = CompletedGraphRun<TOutput> | FailedGraphRun | CancelledGraphRun;

package/dist/core/result.js

@@ -0,0 +1 @@
+export {};