@pikku/core 0.12.70 → 0.12.72

package/dist/wirings/http/pikku-fetch-http-request.js

@@ -1,6 +1,12 @@
 import { parse as parseQuery } from 'picoquery';
 import { parse as parseCookie } from 'cookie';
-import { UnprocessableContentError } from '../../errors/errors.js';
+import { PayloadTooLargeError, UnprocessableContentError, } from '../../errors/errors.js';
+/**
+ * The largest request body read into memory when no limit is configured. Ample
+ * for JSON APIs and typical uploads while keeping a single request's memory
+ * footprint bounded.
+ */
+export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
 /**
  * Abstract class representing a pikku request.
  * @template In - The type of the request body.
@@ -14,9 +20,11 @@ export class PikkuFetchHTTPRequest {
     #rawBodyText;
     #rawBodyBuffer;
     #rawBufferPromise;
-    constructor(request) {
+    #maxBodySize;
+    constructor(request, { maxBodySize = DEFAULT_MAX_BODY_SIZE } = {}) {
         this.request = request;
         this.#url = new URL(request.url);
+        this.#maxBodySize = maxBodySize;
     }
     method() {
         return this.request.method.toLowerCase();
@@ -68,12 +76,65 @@ export class PikkuFetchHTTPRequest {
                 `toWebRequest just for headers) should be removed.`);
             return this.#rawBufferPromise;
         }
-        this.#rawBufferPromise = this.request.arrayBuffer().then((buf) => {
+        this.#rawBufferPromise = this.#readBoundedBuffer().then((buf) => {
             this.#rawBodyBuffer = buf;
             return buf;
         });
         return this.#rawBufferPromise;
     }
+    /**
+     * Reads the body while refusing to buffer more than `maxBodySize` bytes. The
+     * declared `content-length` is rejected up front so an oversized body is never
+     * transferred, and the stream is measured as it arrives because that header is
+     * both optional and attacker-controlled.
+     */
+    async #readBoundedBuffer() {
+        const contentLength = this.request.headers.get('content-length');
+        if (contentLength !== null) {
+            const declaredSize = Number(contentLength);
+            if (Number.isFinite(declaredSize) && declaredSize > this.#maxBodySize) {
+                throw this.#payloadTooLarge();
+            }
+        }
+        const stream = this.request.body;
+        if (stream === null) {
+            const buffer = await this.request.arrayBuffer();
+            if (buffer.byteLength > this.#maxBodySize) {
+                throw this.#payloadTooLarge();
+            }
+            return buffer;
+        }
+        const reader = stream.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                size += value.byteLength;
+                if (size > this.#maxBodySize) {
+                    await reader.cancel();
+                    throw this.#payloadTooLarge();
+                }
+                chunks.push(value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const body = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            body.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return body.buffer;
+    }
+    #payloadTooLarge() {
+        return new PayloadTooLargeError(`Request body exceeds the maximum size of ${this.#maxBodySize} bytes`);
+    }
     async #readRawText() {
         if (this.#rawBodyText !== undefined) {
             return this.#rawBodyText;
@@ -191,6 +252,9 @@ export class PikkuFetchHTTPRequest {
             }
         }
         catch (e) {
+            if (e instanceof PayloadTooLargeError) {
+                throw e;
+            }
             throw new UnprocessableContentError(`Error parsing body: ${e}`);
         }
         return body;

package/dist/wirings/mcp/mcp-runner.d.ts

@@ -6,6 +6,11 @@ export declare class MCPError extends Error {
 }
 export type RunMCPEndpointParams<Tools extends string = any> = {
     mcp?: PikkuMCP<Tools>;
+    /**
+     * Surface the error message + stack on unexpected internal errors.
+     * Defaults to enabled outside of production.
+     */
+    exposeErrors?: boolean;
 };
 export type JsonRpcError = {
     code: number;

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

@@ -1,4 +1,5 @@
 import { getErrorResponse } from '../../errors/error-handler.js';
+import { isProduction } from '../../env.js';
 import { closeWireServices } from '../../utils.js';
 import { pikkuState, getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
@@ -88,7 +89,7 @@ export async function runMCPPrompt(request, params, name) {
 /**
  * JSON-RPC 2.0 compatible MCP endpoint runner
  */
-async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcpWire }) {
+async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcpWire, exposeErrors = !isProduction() }) {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
     let wireServices;
@@ -165,7 +166,9 @@ async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcp
                 id: request.id,
                 code: -32603,
                 message: 'Internal error',
-                data: { message: e.message, stack: e.stack },
+                data: exposeErrors && !isProduction() && e instanceof Error
+                    ? { message: e.message, stack: e.stack }
+                    : undefined,
             });
         }
     }

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

@@ -399,8 +399,9 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
         }
         return;
     }
-    const run = await workflowService.getRun(runId);
-    const triggerInput = run?.input;
+    // The same run read a few lines up: nothing between here and there writes it,
+    // and `input` is fixed at creation anyway.
+    const triggerInput = currentRun?.input;
     for (const fire of plan.toFire) {
         const node = nodes[fire.logical];
         if (!node?.rpcName)

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

@@ -1,3 +1 @@
-export declare function computeEntryNodeIds(nodes: Record<string, any>): string[];
-export declare function validateWorkflowWiring(nodes: Record<string, any>, toolNames: string[]): string[];
 export declare function generateMermaidDiagram(workflowName: string, nodes: Record<string, any>, entryNodeIds: string[]): string;

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

@@ -1,5 +1,3 @@
-import { pikkuState } from '../../../pikku-state.js';
-import { resolveNamespace } from '../../rpc/rpc-runner.js';
 function normalizeTargets(value) {
     if (!value)
         return [];
@@ -16,146 +14,6 @@ function normalizeTargets(value) {
     }
     return [];
 }
-function collectRefs(value, refs) {
-    if (typeof value === 'object' &&
-        value !== null &&
-        '$ref' in value &&
-        typeof value.$ref === 'string') {
-        refs.add(value.$ref);
-        return;
-    }
-    if (Array.isArray(value)) {
-        for (const item of value)
-            collectRefs(item, refs);
-        return;
-    }
-    if (typeof value === 'object' && value !== null) {
-        for (const v of Object.values(value))
-            collectRefs(v, refs);
-    }
-}
-function resolveToolMeta(toolName) {
-    const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null;
-    if (resolved) {
-        const fnMeta = pikkuState(resolved.package, 'function', 'meta')[resolved.function];
-        const schemas = pikkuState(resolved.package, 'misc', 'schemas');
-        return fnMeta ? { fnMeta, schemas } : null;
-    }
-    const rpcMeta = pikkuState(null, 'rpc', 'meta');
-    const pikkuFuncId = rpcMeta[toolName];
-    if (!pikkuFuncId)
-        return null;
-    const fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId];
-    const schemas = pikkuState(null, 'misc', 'schemas');
-    return fnMeta ? { fnMeta, schemas } : null;
-}
-export function computeEntryNodeIds(nodes) {
-    const referenced = new Set();
-    for (const node of Object.values(nodes)) {
-        if (node.next) {
-            for (const target of normalizeTargets(node.next)) {
-                referenced.add(target);
-            }
-        }
-        if (node.onError) {
-            for (const target of normalizeTargets(node.onError)) {
-                referenced.add(target);
-            }
-        }
-    }
-    return Object.keys(nodes).filter((id) => !referenced.has(id));
-}
-export function validateWorkflowWiring(nodes, toolNames) {
-    const errors = [];
-    const nodeIds = new Set(Object.keys(nodes));
-    const toolSet = new Set(toolNames);
-    for (const [nodeId, node] of Object.entries(nodes)) {
-        if (!node.rpcName) {
-            errors.push(`Node '${nodeId}' is missing 'rpcName'`);
-            continue;
-        }
-        if (!toolSet.has(node.rpcName)) {
-            errors.push(`Node '${nodeId}' references unknown tool '${node.rpcName}'. Available tools: ${toolNames.join(', ')}`);
-            continue;
-        }
-        const nextTargets = normalizeTargets(node.next);
-        for (const target of nextTargets) {
-            if (!nodeIds.has(target)) {
-                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'next'`);
-            }
-        }
-        const errorTargets = normalizeTargets(node.onError);
-        for (const target of errorTargets) {
-            if (!nodeIds.has(target)) {
-                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'onError'`);
-            }
-        }
-        if (!node.input)
-            continue;
-        const refs = new Set();
-        collectRefs(node.input, refs);
-        for (const ref of refs) {
-            if (ref === 'trigger' || ref === '$item') {
-                const targetMeta = resolveToolMeta(node.rpcName);
-                if (targetMeta?.fnMeta?.inputSchemaName) {
-                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
-                    if (targetSchema?.properties) {
-                        for (const [field, fieldValue] of Object.entries(node.input)) {
-                            if (typeof fieldValue === 'object' &&
-                                fieldValue !== null &&
-                                fieldValue.$ref === ref &&
-                                !fieldValue.path) {
-                                const targetType = targetSchema.properties[field]?.type;
-                                if (targetType && targetType !== 'object') {
-                                    errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but references the whole ${ref} object without a path. Use { $ref: "${ref}", path: "${field}" } to extract the field.`);
-                                }
-                            }
-                        }
-                    }
-                }
-                continue;
-            }
-            if (!nodeIds.has(ref)) {
-                errors.push(`Node '${nodeId}' references unknown node '${ref}' in input`);
-                continue;
-            }
-            const sourceNode = nodes[ref];
-            if (!sourceNode?.rpcName)
-                continue;
-            const sourceMeta = resolveToolMeta(sourceNode.rpcName);
-            if (!sourceMeta?.fnMeta?.outputSchemaName)
-                continue;
-            const sourceSchema = sourceMeta.schemas.get(sourceMeta.fnMeta.outputSchemaName);
-            if (!sourceSchema?.properties)
-                continue;
-            for (const [field, fieldValue] of Object.entries(node.input)) {
-                if (typeof fieldValue === 'object' &&
-                    fieldValue !== null &&
-                    fieldValue.$ref === ref &&
-                    fieldValue.path) {
-                    const pathRoot = fieldValue.path.split('.')[0];
-                    if (sourceSchema.properties &&
-                        !(pathRoot in sourceSchema.properties)) {
-                        errors.push(`Node '${nodeId}' input field '${field}' references path '${fieldValue.path}' but node '${ref}' (${sourceNode.rpcName}) output has no property '${pathRoot}'`);
-                        continue;
-                    }
-                    const targetMeta = resolveToolMeta(node.rpcName);
-                    if (!targetMeta?.fnMeta?.inputSchemaName)
-                        continue;
-                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
-                    if (!targetSchema?.properties?.[field])
-                        continue;
-                    const sourceType = sourceSchema.properties[pathRoot]?.type;
-                    const targetType = targetSchema.properties[field].type;
-                    if (sourceType && targetType && sourceType !== targetType) {
-                        errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but node '${ref}' output field '${pathRoot}' is type '${sourceType}'`);
-                    }
-                }
-            }
-        }
-    }
-    return errors;
-}
 export function generateMermaidDiagram(workflowName, nodes, entryNodeIds) {
     const lines = ['graph TD'];
     for (const [nodeId, node] of Object.entries(nodes)) {

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

@@ -2,4 +2,4 @@ export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runW
 export { template } from './template.js';
 export type { TemplateString } from './template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './wire-workflow-graph.js';
-export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';
+export { generateMermaidDiagram } from './graph-validation.js';

package/dist/wirings/workflow/graph/index.js

@@ -1,4 +1,4 @@
 export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runWorkflowGraph, } from './graph-runner.js';
 export { template } from './template.js';
 export { pikkuWorkflowGraph, } from './wire-workflow-graph.js';
-export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';
+export { generateMermaidDiagram } from './graph-validation.js';

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

@@ -10,7 +10,6 @@ export { addWorkflow } from './dsl/workflow-runner.js';
 export { addFeature, resolveFeatureScenarios } from './feature.js';
 export { template, type TemplateString } from './graph/template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';
-export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
 export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, CoreFeature, CoreFeatureScenario, FeatureMeta, FeatureMetaEntry, FeaturesMeta, FeaturePlanEntry, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';

package/dist/wirings/workflow/index.js

@@ -11,8 +11,6 @@ export { addFeature, resolveFeatureScenarios } from './feature.js';
 // Graph helpers (template, pikkuWorkflowGraph)
 export { template } from './graph/template.js';
 export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
-// Graph validation and dynamic workflow utilities
-export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 // Queue worker functions (registered by codegen, executed at runtime)
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 // Narrows the optional halves of the step wire, with a message that says what to do

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -154,14 +154,12 @@ export interface WorkflowRunExtension {
      */
     onAfterRunFunc(context: RunLifecycleContext, outcome: 'completed' | 'failed' | 'interrupted', failure: unknown): Promise<void>;
 }
-/**
- * Abstract workflow state service
- * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
- * Combines orchestration and step execution
- */
 export declare abstract class PikkuWorkflowService implements WorkflowService {
-    private inlineRuns;
     private runExtension?;
+    private runContexts;
+    private contextFor;
+    /** Drop a run's context once nothing is holding it open. */
+    private releaseContext;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
     protected readonly queueStrategy: 'per-workflow' | 'shared-groups';
@@ -171,7 +169,18 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         wireQueues?: boolean;
         mirror?: WorkflowRunMirror;
     } & WorkflowQueueOptions);
-    private safeMirror;
+    /**
+     * Perform a state write, then shadow it to the mirror.
+     *
+     * The mirror is an observability sink, never a second source of truth, and
+     * both halves of that follow from this one shape: it is only ever told about
+     * a write that already landed, and a mirror that is down or throwing cannot
+     * fail — or even be seen by — the workflow it is watching.
+     *
+     * @param write - the authoritative write; its result is what the caller gets
+     * @param mirror - shadows the write, given the live mirror and what was written
+     */
+    private mirrored;
     /**
      * Wire the queue-based orchestrator/step/sleeper workers.
      * Subclasses that orchestrate without queues (e.g. Durable Objects) should
@@ -392,11 +401,6 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         graph: any;
         source: string;
     } | null>;
-    abstract getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
-        workflowName: string;
-        graphHash: string;
-        graph: any;
-    }>>;
     /**
      * Resume a paused workflow by triggering the orchestrator
      * @param runId - Run ID
@@ -480,9 +484,59 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         pollIntervalMs?: number;
         wire?: WorkflowRunWire;
     }): Promise<any>;
-    private stepOrdinals;
-    private stepLineage;
-    private resetStepOrdinals;
+    /**
+     * Read a run until it reaches an end state, backing off as it drags on.
+     *
+     * A fixed interval is wrong at both ends: it makes a workflow that finished
+     * in milliseconds wait out the whole interval anyway, and it keeps reading a
+     * long-running one at full rate for as long as it lasts. Starting short and
+     * growing to `maxIntervalMs` returns quick runs promptly while a slow run's
+     * read cost grows logarithmically rather than linearly with its duration.
+     */
+    protected awaitRunEnd(runId: string, maxIntervalMs: number): Promise<WorkflowRun>;
+    /**
+     * Wait between two reads of a run.
+     *
+     * Its own method so the backoff schedule can be asserted on directly. Timing
+     * a poll loop by the clock measures the host's scheduler as much as the
+     * policy — `setTimeout(40)` routinely returns late on a loaded runner — which
+     * makes the obvious test both slow and flaky.
+     */
+    protected waitBeforeNextRead(ms: number): Promise<void>;
+    /**
+     * Every step of a run in one read, or `null` if this backend has no bulk read.
+     *
+     * A replay walks the DSL body from the top, and each step it passes asks for
+     * its own row — so a run of N steps costs N reads per replay and O(N^2) over
+     * its lifetime. Backends that can answer this in a single query collapse that
+     * to one read per replay.
+     */
+    protected listStepStates(_runId: string): Promise<Array<StepState & {
+        stepName: string;
+    }> | null>;
+    /**
+     * Begin a replay pass: fresh ordinal counters, and one read of the steps the
+     * run has already taken so the walk back to where it left off is served from
+     * memory. Safe because a pass reaches each step key at most once, and the
+     * steps it replays past are `succeeded` and therefore immutable.
+     */
+    private beginReplay;
+    private endReplay;
+    /**
+     * The step row for `stepName`, creating it if the run has not reached it
+     * before. Served from the replay snapshot when one is loaded.
+     */
+    private loadOrCreateStep;
+    /**
+     * The run's immutable half — which workflow it is, the wire it was started
+     * on, its input. `getRun` is otherwise called several times per step for
+     * answers that were all fixed at creation, so a replay reads it once and
+     * hands the same object to everyone who only needs that half.
+     *
+     * Anyone who needs `status`, `output`, `error` or `state` must call `getRun`:
+     * those move while the run executes, and a cached copy would be a lie.
+     */
+    private getRunIdentity;
     /** The step the DSL walk last reached (the predecessor for the next step). */
     private lastStepName;
     /**