@pikku/core 0.12.63 → 0.12.64

package/dist/wirings/rpc/rpc-runner.js

@@ -1,7 +1,9 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
+import { addonInstanceForNamespace } from './addon-runner.js';
 import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
+import { resolveRemoteAddonToken } from './remote-addon-auth.js';
 export class RPCNotFoundError extends PikkuError {
     rpcName;
     constructor(rpcName) {
@@ -14,8 +16,31 @@ addError(RPCNotFoundError, {
     mcpCode: -32601,
     message: 'RPC function not found.',
 });
+/** A `wireRemoteAddon` namespace is missing a usable `serverUrl`. */
+export class RemoteAddonConfigError extends PikkuError {
+    constructor(namespace, detail) {
+        super(`Remote addon '${namespace}' is misconfigured: ${detail}`);
+    }
+}
+addError(RemoteAddonConfigError, {
+    status: 500,
+    message: 'Remote addon is misconfigured.',
+});
+/** The hosted addon returned a non-2xx response for a remote RPC. */
+export class RemoteAddonRequestError extends PikkuError {
+    httpStatus;
+    constructor(namespace, fnName, status, detail) {
+        super(`Remote addon '${namespace}:${fnName}' returned ${status}${detail ? `: ${detail}` : ''}`);
+        this.httpStatus = status;
+    }
+}
+addError(RemoteAddonRequestError, {
+    status: 502,
+    message: 'Remote addon request failed.',
+});
 import { runAIAgent, resumeAIAgentSync } from '../ai-agent/ai-agent-runner.js';
 import { streamAIAgent, resumeAIAgent } from '../ai-agent/ai-agent-stream.js';
+import { wrapChannelWithAGUI } from '../ai-agent/ai-agent-agui.js';
 /**
  * Resolve a namespaced function reference to package and function names
  * Uses pikkuState to look up the namespace -> package mapping
@@ -130,12 +155,16 @@ export class ContextAwareRPCService {
         // 'namespace:func' boundary via invokeAddonFunction.
         try {
             const resolved = resolvePikkuFunction(funcName, this.packageName);
+            const addonInstance = resolved.packageName
+                ? addonInstanceForNamespace(this.wire.addonNamespace, resolved.packageName)
+                : undefined;
             return await runPikkuFunc('rpc', funcName, resolved.pikkuFuncId, {
                 auth: this.options.requiresAuth,
                 singletonServices: this.services,
                 data: () => data,
                 wire: updatedWire,
                 packageName: resolved.packageName,
+                addonInstance,
             });
         }
         catch (e) {
@@ -163,6 +192,12 @@ export class ContextAwareRPCService {
         if (!resolved) {
             throw new RPCNotFoundError(namespacedFunction);
         }
+        const namespace = namespacedFunction.slice(0, namespacedFunction.indexOf(':'));
+        // wireRemoteAddon: the addon ships as a devDependency (types only) and its
+        // handlers run on the host — dispatch over HTTP, not through local meta.
+        if (resolved.addonConfig?.remote) {
+            return this.invokeRemoteAddonFunction(namespace, resolved.function, data);
+        }
         // Get the function meta from the addon package
         // Addon packages use function meta, not RPC meta
         const addonFunctionMeta = pikkuState(resolved.package, 'function', 'meta');
@@ -176,6 +211,14 @@ export class ContextAwareRPCService {
             ...(resolved.addonConfig?.tags ?? []),
             ...(funcMeta.tags ?? []),
         ];
+        // The namespace is the consumer-facing wireAddon name; it selects the
+        // per-instance singleton services and secret/variable/credential overrides.
+        const addonInstance = {
+            namespace,
+            secretOverrides: resolved.addonConfig?.secretOverrides,
+            variableOverrides: resolved.addonConfig?.variableOverrides,
+            credentialOverrides: resolved.addonConfig?.credentialOverrides,
+        };
         // Execute the function using runPikkuFunc with the addon package's state
         // We use the parent services (this.services) since addon packages share services
         // Pass the function's tags so tag-based middleware/permissions are applied
@@ -186,7 +229,56 @@ export class ContextAwareRPCService {
             wire,
             packageName: resolved.package,
             tags,
+            addonInstance,
+        });
+    }
+    /**
+     * Dispatch a `wireRemoteAddon` RPC over HTTP to the hosting service.
+     *
+     * The consumer sends the addon's own function name (not the namespaced form)
+     * to the host's `/remote/rpc/:rpcName` endpoint, authenticating as a client
+     * with the token bound in `wireRemoteAddon({ auth })`. The addon's handlers
+     * live on the host, so there is no local function meta to resolve.
+     */
+    async invokeRemoteAddonFunction(namespace, fnName, data) {
+        const cfg = pikkuState(null, 'addons', 'packages').get(namespace);
+        if (!cfg?.remote) {
+            throw new RPCNotFoundError(`${namespace}:${fnName}`);
+        }
+        const serverUrl = typeof cfg.serverUrl === 'function'
+            ? await cfg.serverUrl(this.services)
+            : cfg.serverUrl;
+        if (!serverUrl) {
+            throw new RemoteAddonConfigError(namespace, 'serverUrl resolved empty');
+        }
+        const remoteFn = cfg.remoteName ? cfg.remoteName(fnName) : fnName;
+        const token = await resolveRemoteAddonToken(cfg.remoteAuth, this.services, this.wire, namespace);
+        const headers = {
+            'content-type': 'application/json',
+            accept: 'application/json',
+        };
+        if (token) {
+            headers.authorization = `Bearer ${token}`;
+        }
+        if (this.wire.traceId) {
+            headers['x-trace-id'] = this.wire.traceId;
+        }
+        const base = serverUrl.replace(/\/+$/, '');
+        const res = await fetch(`${base}/remote/rpc/${encodeURIComponent(remoteFn)}`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ rpcName: remoteFn, data }),
         });
+        if (!res.ok) {
+            // Best-effort body read to enrich the thrown error (mirrors postRpc).
+            const detail = (await res.text().catch(() => '')).slice(0, 300);
+            throw new RemoteAddonRequestError(namespace, remoteFn, res.status, detail);
+        }
+        if (res.status === 204) {
+            return undefined;
+        }
+        const text = await res.text();
+        return (text ? JSON.parse(text) : undefined);
     }
     async rpcWithWire(rpcName, data, wire) {
         const mergedWire = {
@@ -198,12 +290,16 @@ export class ContextAwareRPCService {
         }
         try {
             const resolved = resolvePikkuFunction(rpcName, this.packageName);
+            const addonInstance = resolved.packageName
+                ? addonInstanceForNamespace(this.wire.addonNamespace, resolved.packageName)
+                : undefined;
             return await runPikkuFunc('rpc', rpcName, resolved.pikkuFuncId, {
                 auth: this.options.requiresAuth,
                 singletonServices: this.services,
                 data: () => data,
                 wire: mergedWire,
                 packageName: resolved.packageName,
+                addonInstance,
             });
         }
         catch (e) {
@@ -250,16 +346,26 @@ export class ContextAwareRPCService {
                 const channel = this.wire.channel;
                 if (!channel)
                     throw new Error('No channel available for streaming');
-                await streamAIAgent(agentName, input, channel, {
+                let currentRunId;
+                await streamAIAgent(agentName, input, wrapChannelWithAGUI(channel, {
+                    threadId: input.threadId,
+                    getRunId: () => currentRunId,
+                }), {
                     sessionService: this.options.sessionService,
                     getCredential: this.wire.getCredential?.bind(this.wire),
-                }, undefined, options);
+                }, undefined, {
+                    ...options,
+                    onRunCreated: (runId) => {
+                        currentRunId = runId;
+                        options?.onRunCreated?.(runId);
+                    },
+                });
             },
             resume: async (runId, input, options) => {
                 const channel = this.wire.channel;
                 if (!channel)
                     throw new Error('No channel available for streaming');
-                await resumeAIAgent({ runId, ...input }, channel, {
+                await resumeAIAgent({ runId, ...input }, wrapChannelWithAGUI(channel, { runId }), {
                     sessionService: this.options.sessionService,
                     getCredential: this.wire.getCredential?.bind(this.wire),
                 }, options);

package/dist/wirings/rpc/rpc-types.d.ts

@@ -1,4 +1,4 @@
-export type PikkuRPC<Invoke extends Function = any, Remote extends Function = any, startWorkflow extends Function = any, AgentRun extends Function = any, AgentStream extends Function = any> = {
+export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Remote extends (...args: any[]) => any = (...args: any[]) => any, startWorkflow extends (...args: any[]) => any = (...args: any[]) => any, AgentRun extends (...args: any[]) => any = (...args: any[]) => any, AgentStream extends (...args: any[]) => any = (...args: any[]) => any> = {
     depth: number;
     global: boolean;
     invoke: Invoke;
@@ -41,5 +41,19 @@ export interface ResolvedFunction {
         auth?: boolean;
         tags?: string[];
         rpcEndpoint?: string;
+        secretOverrides?: Record<string, string>;
+        variableOverrides?: Record<string, string>;
+        credentialOverrides?: Record<string, string>;
+        /** Set by `wireRemoteAddon`: dispatch this namespace's RPCs over HTTP */
+        remote?: boolean;
+        serverUrl?: string | ((services: any) => string | Promise<string>);
+        remoteAuth?: {
+            credentialId: string;
+        } | {
+            secretId: string;
+        } | {
+            resolve: (services: any, wire: any) => string | Promise<string>;
+        };
+        remoteName?: (fn: string) => string;
     };
 }

package/dist/wirings/rpc/wire-addon.js

@@ -5,5 +5,14 @@ export const wireAddon = (config) => {
         rpcEndpoint: config.rpcEndpoint,
         auth: config.auth,
         tags: config.tags,
+        ...(config.secretOverrides
+            ? { secretOverrides: config.secretOverrides }
+            : {}),
+        ...(config.variableOverrides
+            ? { variableOverrides: config.variableOverrides }
+            : {}),
+        ...(config.credentialOverrides
+            ? { credentialOverrides: config.credentialOverrides }
+            : {}),
     });
 };

package/dist/wirings/rpc/wire-remote-addon.d.ts

@@ -0,0 +1,47 @@
+import type { CoreServices, PikkuWire } from '../../types/core.types.js';
+/**
+ * How the consumer supplies the token the hosted addon's auth expects.
+ *
+ * This is a CLIENT authenticating to a hosted library — NOT pikku's trusted
+ * machine-to-machine mesh (which uses `PIKKU_REMOTE_SECRET`). The consumer binds
+ * the addon's declared auth requirement to a local source:
+ *  - `credentialId` — per-user credential, resolved via `wire.getCredential(id)`
+ *  - `secretId`     — platform key, resolved via the secrets service
+ *  - `resolve`      — custom escape hatch
+ * Omit entirely when the addon declares its remote surface is public.
+ *
+ * The value is sent `Authorization: Bearer <token>` by default; a non-default
+ * header is declared once by the addon (its meta), never chosen here.
+ */
+export type RemoteAddonAuth = {
+    credentialId: string;
+} | {
+    secretId: string;
+} | {
+    resolve: (services: CoreServices, wire: PikkuWire) => string | Promise<string>;
+};
+export type WireRemoteAddonConfig = {
+    /** Consumer-facing namespace, e.g. `registry` → `rpc('registry:getOpenApi')` */
+    name: string;
+    /**
+     * The addon package. Installed as a **devDependency** (types only — its
+     * handlers run on the host); `pikku verify` enforces this.
+     */
+    package: string;
+    /** Base URL of the host serving the addon's remote surface. */
+    serverUrl: string | ((services: CoreServices) => string | Promise<string>);
+    /** Bind the addon's declared auth to a local source. Omit if the surface is public. */
+    auth?: RemoteAddonAuth;
+    /** Map a consumer-facing fn name → the remote fn name, when they differ (rare). */
+    remoteName?: (fn: string) => string;
+    tags?: string[];
+};
+/**
+ * Consume a hosted addon's `remote: true` RPCs transparently over HTTP.
+ *
+ * Unlike `wireAddon` (which bundles the addon's functions in-process, a
+ * production dependency), `wireRemoteAddon` dispatches `rpc('name:fn')` to the
+ * host at `serverUrl`, fully typed — the addon ships as a devDependency (types
+ * only). See {@link RemoteAddonAuth} for how auth is bound.
+ */
+export declare const wireRemoteAddon: (config: WireRemoteAddonConfig) => void;

package/dist/wirings/rpc/wire-remote-addon.js

@@ -0,0 +1,19 @@
+import { pikkuState } from '../../pikku-state.js';
+/**
+ * Consume a hosted addon's `remote: true` RPCs transparently over HTTP.
+ *
+ * Unlike `wireAddon` (which bundles the addon's functions in-process, a
+ * production dependency), `wireRemoteAddon` dispatches `rpc('name:fn')` to the
+ * host at `serverUrl`, fully typed — the addon ships as a devDependency (types
+ * only). See {@link RemoteAddonAuth} for how auth is bound.
+ */
+export const wireRemoteAddon = (config) => {
+    pikkuState(null, 'addons', 'packages').set(config.name, {
+        package: config.package,
+        tags: config.tags,
+        remote: true,
+        serverUrl: config.serverUrl,
+        ...(config.auth ? { remoteAuth: config.auth } : {}),
+        ...(config.remoteName ? { remoteName: config.remoteName } : {}),
+    });
+};

package/dist/wirings/scope/index.d.ts

@@ -0,0 +1,3 @@
+export { wireScope } from './wire-scope.js';
+export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
+export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta, ScopeDefinitions, ScopeNodeMeta, } from './scope.types.js';

package/dist/wirings/scope/index.js

@@ -0,0 +1,2 @@
+export { wireScope } from './wire-scope.js';
+export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';

package/dist/wirings/scope/scope.types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A node within a scope tree. Every node is itself a grantable scope — given
+ * `admin` containing `invoices` containing `create`, all three of `admin`,
+ * `admin:invoices` and `admin:invoices:create` are valid scope ids.
+ */
+export type CoreScopeNode = {
+    /** Short human-readable name, e.g. "Administration". */
+    displayName?: string;
+    /** Longer-form description, surfaced in the console when granting. */
+    description?: string;
+    /** Nested scopes, keyed by their segment. */
+    scopes?: Record<string, CoreScopeNode>;
+};
+/**
+ * Scope trees to declare, keyed by their root segment. A root is just a node —
+ * it is named by its key, exactly like every node beneath it. A key must not
+ * contain `:` or be `*`.
+ */
+export type CoreScopes = Record<string, CoreScopeNode>;
+export type ScopeNodeMeta = {
+    displayName?: string;
+    description?: string;
+    scopes?: Record<string, ScopeNodeMeta>;
+};
+export type ScopeDefinitionMeta = {
+    name: string;
+    displayName?: string;
+    description?: string;
+    scopes?: Record<string, ScopeNodeMeta>;
+    sourceFile?: string;
+};
+export type ScopeDefinitions = ScopeDefinitionMeta[];
+export type ScopeDefinitionsMeta = Record<string, ScopeDefinitionMeta>;
+/** A single scope, flattened out of the declared tree. */
+export type FlatScope = {
+    /** Colon-delimited id, e.g. `admin:invoices:create`. */
+    id: string;
+    description?: string;
+};

package/dist/wirings/scope/scope.types.js

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

package/dist/wirings/scope/validate-scope-definitions.d.ts

@@ -0,0 +1,16 @@
+import type { FlatScope, ScopeDefinitions, ScopeDefinitionsMeta } from './scope.types.js';
+/**
+ * Flattens declared scope trees into the full list of grantable scope ids,
+ * depth-first. Every node is emitted, including intermediate ones.
+ *
+ * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
+ * the declared set into its store.
+ */
+export declare const flattenScopeDefinitions: (definitions: ScopeDefinitions) => FlatScope[];
+/**
+ * Validates declared scopes and keys them by name.
+ *
+ * Definitions sharing a name must be identical; a conflicting redeclaration is
+ * a hard error naming both source files.
+ */
+export declare function validateAndBuildScopeDefinitionsMeta(definitions: ScopeDefinitions): ScopeDefinitionsMeta;

package/dist/wirings/scope/validate-scope-definitions.js

@@ -0,0 +1,76 @@
+const SEPARATOR = ':';
+const WILDCARD = '*';
+const assertSegment = (segment, scopeName) => {
+    if (segment.includes(SEPARATOR)) {
+        throw new Error(`Scope segment '${segment}' in '${scopeName}' contains the '${SEPARATOR}' separator. ` +
+            `Nest scopes with the 'scopes' property instead of embedding '${SEPARATOR}' in a name.`);
+    }
+    if (segment === WILDCARD) {
+        throw new Error(`Scope segment '${segment}' in '${scopeName}' is the wildcard. ` +
+            `'${WILDCARD}' is reserved for granting a scope and its descendants, and cannot be declared.`);
+    }
+    if (segment.length === 0) {
+        throw new Error(`Scope '${scopeName}' contains an empty segment.`);
+    }
+};
+const assertNodesValid = (nodes, scopeName) => {
+    for (const [segment, node] of Object.entries(nodes ?? {})) {
+        assertSegment(segment, scopeName);
+        assertNodesValid(node.scopes, scopeName);
+    }
+};
+const flattenNodes = (nodes, prefix, out) => {
+    for (const [segment, node] of Object.entries(nodes ?? {})) {
+        const id = `${prefix}${SEPARATOR}${segment}`;
+        out.push({ id, description: node.description });
+        flattenNodes(node.scopes, id, out);
+    }
+};
+/**
+ * Flattens declared scope trees into the full list of grantable scope ids,
+ * depth-first. Every node is emitted, including intermediate ones.
+ *
+ * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
+ * the declared set into its store.
+ */
+export const flattenScopeDefinitions = (definitions) => {
+    const out = [];
+    for (const def of definitions) {
+        out.push({ id: def.name, description: def.description });
+        flattenNodes(def.scopes, def.name, out);
+    }
+    return out;
+};
+/**
+ * Validates declared scopes and keys them by name.
+ *
+ * Definitions sharing a name must be identical; a conflicting redeclaration is
+ * a hard error naming both source files.
+ */
+export function validateAndBuildScopeDefinitionsMeta(definitions) {
+    const meta = {};
+    for (const def of definitions) {
+        assertSegment(def.name, def.name);
+        assertNodesValid(def.scopes, def.name);
+        const existing = meta[def.name];
+        if (existing) {
+            const sameShape = JSON.stringify(existing.scopes ?? {}) ===
+                JSON.stringify(def.scopes ?? {});
+            if (!sameShape) {
+                throw new Error(`Scope '${def.name}' is declared with different nested scopes.\n` +
+                    `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
+                    `  Second declaration: ${def.sourceFile ?? 'unknown'}\n` +
+                    `Scopes sharing a name must declare the same tree.`);
+            }
+            continue;
+        }
+        meta[def.name] = {
+            name: def.name,
+            displayName: def.displayName,
+            description: def.description,
+            scopes: def.scopes,
+            sourceFile: def.sourceFile,
+        };
+    }
+    return meta;
+}

package/dist/wirings/scope/wire-scope.d.ts

@@ -0,0 +1,33 @@
+import type { CoreScopes } from './scope.types.js';
+/**
+ * No-op function for declaring scopes.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `ScopeId` union,
+ * so a function referencing an undeclared scope fails the build.
+ *
+ * Scopes are keyed by segment at every level: a scope is named by its key, and
+ * its value describes it. Every node is grantable — the declaration below
+ * yields `admin`, `admin:invoices`, `admin:invoices:create`,
+ * `admin:invoices:void` and `billing`.
+ *
+ * @example
+ * ```typescript
+ * wireScope({
+ *   admin: {
+ *     displayName: 'Administration',
+ *     description: 'Administrative access',
+ *     scopes: {
+ *       invoices: {
+ *         description: 'Invoice management',
+ *         scopes: {
+ *           create: { description: 'Create invoices' },
+ *           void: { description: 'Void invoices' },
+ *         },
+ *       },
+ *     },
+ *   },
+ *   billing: {},
+ * })
+ * ```
+ */
+export declare const wireScope: (_config: CoreScopes) => void;

package/dist/wirings/scope/wire-scope.js

@@ -0,0 +1,32 @@
+/**
+ * No-op function for declaring scopes.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `ScopeId` union,
+ * so a function referencing an undeclared scope fails the build.
+ *
+ * Scopes are keyed by segment at every level: a scope is named by its key, and
+ * its value describes it. Every node is grantable — the declaration below
+ * yields `admin`, `admin:invoices`, `admin:invoices:create`,
+ * `admin:invoices:void` and `billing`.
+ *
+ * @example
+ * ```typescript
+ * wireScope({
+ *   admin: {
+ *     displayName: 'Administration',
+ *     description: 'Administrative access',
+ *     scopes: {
+ *       invoices: {
+ *         description: 'Invoice management',
+ *         scopes: {
+ *           create: { description: 'Create invoices' },
+ *           void: { description: 'Void invoices' },
+ *         },
+ *       },
+ *     },
+ *   },
+ *   billing: {},
+ * })
+ * ```
+ */
+export const wireScope = (_config) => { };

package/dist/wirings/workflow/dsl/index.d.ts

@@ -2,4 +2,4 @@
  * DSL (Domain Specific Language) workflow exports
  */
 export { addWorkflow } from './workflow-runner.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -2,6 +2,7 @@
  * DSL (Domain Specific Language) workflow types
  * These types define the step-based workflow format extracted by the inspector
  */
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { WorkflowRun } from '../workflow.types.js';
 import type { ScenarioActor } from '../../../services/scenario-actors-service.js';
 /**
@@ -64,6 +65,43 @@ export type WorkflowWireSleep = (stepName: string, duration: string) => Promise<
  * loops, like dynamic `do()` step names.
  */
 export type WorkflowWireSuspend = (reason: string) => Promise<void>;
+/**
+ * Options for workflow.approval().
+ */
+export interface WorkflowApprovalOptions<TSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    /**
+     * Schema the decision payload is validated against. This is a VALUE, not a
+     * type generic: the payload arrives from an untrusted caller over the approve
+     * wire, and a generic is erased at compile time — it would validate nothing.
+     * Any standard-schema library (zod, valibot, arktype) satisfies this.
+     */
+    schema: TSchema;
+    /**
+     * Give up waiting after this long (e.g. '3d'), yielding `{ status: 'expired' }`
+     * instead of waiting forever. Evaluated on replay from a recorded deadline, so
+     * the answer is correct even if the wake-up timer is never delivered.
+     */
+    expiry?: string | number;
+}
+/**
+ * The result of an approval gate. A union rather than a throw so that callers
+ * must handle the deadline case, and so "skip it and carry on" stays trivial.
+ * `decided` means a human answered — whether that answer was yes or no is
+ * carried in `data` and is the application's business, not the framework's.
+ */
+export type ApprovalOutcome<T> = {
+    status: 'decided';
+    data: T;
+} | {
+    status: 'expired';
+};
+/**
+ * Type signature for workflow.approval() - used by inspector.
+ * Like {@link WorkflowWireSuspend}, `reason` is the approval point's stable
+ * durable identity. Unlike suspend, the gate stays closed until a decision is
+ * recorded against it, and the decision is handed back to the caller.
+ */
+export type WorkflowWireApproval = <TSchema extends StandardSchemaV1>(reason: string, options: WorkflowApprovalOptions<TSchema>) => Promise<ApprovalOutcome<StandardSchemaV1.InferOutput<TSchema>>>;
 /**
  * Input source for step arguments in DSL workflows
  */
@@ -272,6 +310,18 @@ export interface SuspendStepMeta {
     /** Reason string passed to workflow.suspend() — becomes the durable step key */
     reason: string;
 }
+/**
+ * Approval step metadata (workflow.approval())
+ */
+export interface ApprovalStepMeta {
+    type: 'approval';
+    /** Reason string passed to workflow.approval() — becomes the durable step key */
+    reason: string;
+    /** Output variable name (if assigned) */
+    outputVar?: string;
+    /** Expiry duration, when one was given */
+    expiry?: string | number;
+}
 /**
  * Filter step metadata (array.filter)
  */
@@ -305,7 +355,7 @@ export interface ArrayPredicateStepMeta {
 /**
  * Workflow step metadata (extracted by inspector)
  */
-export type WorkflowStepMeta = RpcStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SuspendStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
+export type WorkflowStepMeta = RpcStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SuspendStepMeta | ApprovalStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
 /**
  * Workflow step wire context for RPC functions
  * Provides step-level metadata including retry attempt tracking
@@ -355,6 +405,8 @@ export interface PikkuWorkflowWire {
     sleep: WorkflowWireSleep;
     /** Suspend workflow until explicitly resumed */
     suspend: WorkflowWireSuspend;
+    /** Suspend workflow until a human records a decision against this gate */
+    approval: WorkflowWireApproval;
 }
 export interface PikkuScenarioWire extends PikkuWorkflowWire {
     /**

package/dist/wirings/workflow/graph/graph-node.d.ts

@@ -93,6 +93,8 @@ type GraphNodeConfigMap<FuncMap extends Record<string, string>, RPCMap extends R
         onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[];
         retries?: number;
         retryDelay?: string | number;
+        /** Free-text node documentation. Non-semantic — excluded from graphHash. */
+        notes?: string;
     };
 };
 /**

package/dist/wirings/workflow/graph/graph-runner.js

@@ -246,6 +246,9 @@ function resolveTemplate(template, nodeResults) {
 }
 function resolveValue(value, nodeResults) {
     if (isDataRef(value)) {
+        if (value.$ref === '$item') {
+            return value;
+        }
         const source = nodeResults[value.$ref];
         return value.path ? getValueAtPath(source, value.path) : source;
     }

package/dist/wirings/workflow/graph/wire-workflow-graph.d.ts

@@ -5,11 +5,17 @@ export interface PikkuWorkflowGraphConfig<FuncMap extends Record<string, string>
     tags?: string[];
     nodes: FuncMap;
     config?: T;
+    /**
+     * Graph-level free-text notes (e.g. imported sticky notes). Non-semantic:
+     * excluded from the graph topology hash.
+     */
+    notes?: string[];
 }
 export interface PikkuWorkflowGraphResult {
     __type: 'pikkuWorkflowGraph';
     name?: string;
     description?: string;
     tags?: string[];
+    notes?: string[];
 }
 export declare function pikkuWorkflowGraph<const FuncMap extends Record<string, string>>(config: PikkuWorkflowGraphConfig<FuncMap, any>): PikkuWorkflowGraphResult;

package/dist/wirings/workflow/graph/wire-workflow-graph.js

@@ -4,5 +4,6 @@ export function pikkuWorkflowGraph(config) {
         name: config.name,
         description: config.description,
         tags: config.tags,
+        notes: config.notes,
     };
 }