@parcha/agentrun-pi 0.1.0-beta.1

package/dist/demo-data.js

@@ -0,0 +1,386 @@
+// Generated by scripts/build-pi-demo.mjs from the public research example.
+export const demoData = {
+    "workflow": {
+        "v": 2,
+        "name": "deep-research",
+        "schemas": {
+            "Question": {
+                "$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "properties": {
+                    "question": {
+                        "type": "string",
+                        "minLength": 1
+                    }
+                },
+                "required": [
+                    "question"
+                ],
+                "additionalProperties": false
+            },
+            "Plan": {
+                "$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "properties": {
+                    "questions": {
+                        "minItems": 1,
+                        "maxItems": 5,
+                        "type": "array",
+                        "items": {
+                            "type": "string",
+                            "minLength": 1
+                        }
+                    }
+                },
+                "required": [
+                    "questions"
+                ],
+                "additionalProperties": false
+            },
+            "Finding": {
+                "$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "properties": {
+                    "question": {
+                        "type": "string"
+                    },
+                    "answer": {
+                        "type": "string"
+                    },
+                    "sources": {
+                        "minItems": 1,
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "id": {
+                                    "type": "string"
+                                },
+                                "text": {
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "id",
+                                "text"
+                            ],
+                            "additionalProperties": false
+                        }
+                    }
+                },
+                "required": [
+                    "question",
+                    "answer",
+                    "sources"
+                ],
+                "additionalProperties": false
+            },
+            "Report": {
+                "$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "properties": {
+                    "answer": {
+                        "type": "string"
+                    },
+                    "findings": {
+                        "minItems": 1,
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "question": {
+                                    "type": "string"
+                                },
+                                "answer": {
+                                    "type": "string"
+                                },
+                                "sources": {
+                                    "minItems": 1,
+                                    "type": "array",
+                                    "items": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {
+                                                "type": "string"
+                                            },
+                                            "text": {
+                                                "type": "string"
+                                            }
+                                        },
+                                        "required": [
+                                            "id",
+                                            "text"
+                                        ],
+                                        "additionalProperties": false
+                                    }
+                                }
+                            },
+                            "required": [
+                                "question",
+                                "answer",
+                                "sources"
+                            ],
+                            "additionalProperties": false
+                        }
+                    }
+                },
+                "required": [
+                    "answer",
+                    "findings"
+                ],
+                "additionalProperties": false
+            }
+        },
+        "input": {
+            "schemaId": "Question"
+        },
+        "output": {
+            "schemaId": "Report",
+            "path": "report"
+        },
+        "root": {
+            "node": "chain",
+            "steps": [
+                {
+                    "node": "decide",
+                    "label": "plan",
+                    "instructions": "Break the research question into up to five distinct, answerable subquestions. Each runs independently: include its subject and relevant context so it makes sense without the original question.",
+                    "state": {
+                        "question": "{question}"
+                    },
+                    "out": "Plan",
+                    "as": "plan"
+                },
+                {
+                    "node": "map",
+                    "label": "research",
+                    "itemsPath": "plan.questions",
+                    "as": "findings",
+                    "maxConcurrency": 3,
+                    "resultPath": "finding",
+                    "body": {
+                        "node": "workflow",
+                        "label": "research-question",
+                        "workflow": {
+                            "v": 2,
+                            "name": "research-one-question",
+                            "schemas": {
+                                "Question": {
+                                    "$schema": "http://json-schema.org/draft-07/schema#",
+                                    "type": "object",
+                                    "properties": {
+                                        "question": {
+                                            "type": "string",
+                                            "minLength": 1
+                                        }
+                                    },
+                                    "required": [
+                                        "question"
+                                    ],
+                                    "additionalProperties": false
+                                },
+                                "Sources": {
+                                    "$schema": "http://json-schema.org/draft-07/schema#",
+                                    "type": "object",
+                                    "properties": {
+                                        "sources": {
+                                            "type": "array",
+                                            "items": {
+                                                "type": "object",
+                                                "properties": {
+                                                    "id": {
+                                                        "type": "string"
+                                                    },
+                                                    "text": {
+                                                        "type": "string"
+                                                    }
+                                                },
+                                                "required": [
+                                                    "id",
+                                                    "text"
+                                                ],
+                                                "additionalProperties": false
+                                            }
+                                        }
+                                    },
+                                    "required": [
+                                        "sources"
+                                    ],
+                                    "additionalProperties": false
+                                },
+                                "Finding": {
+                                    "$schema": "http://json-schema.org/draft-07/schema#",
+                                    "type": "object",
+                                    "properties": {
+                                        "question": {
+                                            "type": "string"
+                                        },
+                                        "answer": {
+                                            "type": "string"
+                                        },
+                                        "sources": {
+                                            "minItems": 1,
+                                            "type": "array",
+                                            "items": {
+                                                "type": "object",
+                                                "properties": {
+                                                    "id": {
+                                                        "type": "string"
+                                                    },
+                                                    "text": {
+                                                        "type": "string"
+                                                    }
+                                                },
+                                                "required": [
+                                                    "id",
+                                                    "text"
+                                                ],
+                                                "additionalProperties": false
+                                            }
+                                        }
+                                    },
+                                    "required": [
+                                        "question",
+                                        "answer",
+                                        "sources"
+                                    ],
+                                    "additionalProperties": false
+                                },
+                                "EvidenceDecision": {
+                                    "type": "object",
+                                    "additionalProperties": false,
+                                    "required": [
+                                        "answersQuestion"
+                                    ],
+                                    "properties": {
+                                        "answersQuestion": {
+                                            "type": "boolean",
+                                            "description": "Does this candidate passage provide concrete information for answering `subquestion`? Evaluate the passage's claims, not keyword overlap. A partial answer, a condition, a limitation, or evidence contradicting the proposed answer counts; the passage need not settle the whole question.",
+                                            "criteria": {
+                                                "true": "Reports a specific fact, observation, rule or limitation bearing on the subquestion. Keep supporting and contrary evidence, including qualified answers; do not require proof that the answer holds in every situation.",
+                                                "false": "Only mentions the topic, promises an unspecified benefit, omits the information needed to bear on the subquestion, or describes a different subject without establishing relevance."
+                                            }
+                                        }
+                                    }
+                                }
+                            },
+                            "input": {
+                                "schemaId": "Question"
+                            },
+                            "output": {
+                                "schemaId": "Finding",
+                                "path": "finding"
+                            },
+                            "root": {
+                                "node": "chain",
+                                "steps": [
+                                    {
+                                        "node": "call",
+                                        "label": "search",
+                                        "via": "tool",
+                                        "tool": "search",
+                                        "args": {
+                                            "question": "{question}"
+                                        },
+                                        "out": "Sources",
+                                        "as": "search",
+                                        "deadline_s": 15
+                                    },
+                                    {
+                                        "node": "sift",
+                                        "label": "screen-evidence",
+                                        "itemsPath": "search.sources",
+                                        "state": {
+                                            "subquestion": "{question}"
+                                        },
+                                        "out": "EvidenceDecision",
+                                        "as": "evidence",
+                                        "keep": {
+                                            "path": "answersQuestion",
+                                            "gte": 0.8
+                                        }
+                                    },
+                                    {
+                                        "node": "escalate",
+                                        "label": "missing-evidence",
+                                        "when": {
+                                            "predicate": "empty",
+                                            "path": "evidence.items"
+                                        },
+                                        "kind": "needs_research",
+                                        "stage": "evidence",
+                                        "summary": "No selected evidence addresses: {question}"
+                                    },
+                                    {
+                                        "node": "agent",
+                                        "label": "write-finding",
+                                        "instructions": "Answer this subquestion using only the selected sources. Preserve contrary evidence, conditions and uncertainty. Say what cannot be determined when evidence is partial; do not turn a conditional claim into an unconditional conclusion. Return the question, answer and cited source records.",
+                                        "state": {
+                                            "question": "{question}",
+                                            "sources": "{evidence.items}"
+                                        },
+                                        "out": "Finding",
+                                        "as": "finding"
+                                    }
+                                ]
+                            }
+                        },
+                        "input": {
+                            "question": "{item}"
+                        },
+                        "out": "Finding",
+                        "as": "finding"
+                    }
+                },
+                {
+                    "node": "agent",
+                    "label": "write-report",
+                    "instructions": "Answer the original question from these findings. Preserve disagreements, conditions, uncertainty and remaining limitations. Keep unresolved questions explicit; do not present partial findings as conclusive.",
+                    "state": {
+                        "question": "{question}",
+                        "findings": "{findings}"
+                    },
+                    "out": "Report",
+                    "as": "report"
+                }
+            ]
+        }
+    },
+    "question": "Should our small team move its documentation from a wiki into the code repository?",
+    "sources": [
+        {
+            "id": "review-guide",
+            "text": "In this fictional team, documentation changes in the repository require a pull request and an assigned reviewer."
+        },
+        {
+            "id": "advert",
+            "text": "Repository documentation will transform your whole business."
+        },
+        {
+            "id": "editor-trial",
+            "text": "In the fictional trial, browser editing worked, but two non-developers needed help resolving merge conflicts."
+        },
+        {
+            "id": "design-news",
+            "text": "The wiki product has changed its logo."
+        },
+        {
+            "id": "search-trial",
+            "text": "The fictional repository search found filenames and exact words, but missed the synonyms people used in the wiki."
+        },
+        {
+            "id": "search-advert",
+            "text": "Find anything instantly with our new search experience."
+        }
+    ],
+    "subquestions": [
+        "What review process would our team use for documentation changes in the code repository?",
+        "Can our team’s non-developers edit documentation in the code repository?",
+        "How does documentation search in the code repository compare with our wiki?"
+    ],
+    "evidenceIds": [
+        "review-guide",
+        "editor-trial",
+        "search-trial"
+    ]
+};

package/dist/demo.d.ts

@@ -0,0 +1,13 @@
+import type { Workflow, WorkflowDeps } from '@parcha/agentrun-dsl';
+import type { PiToolDefinition } from './types.js';
+export declare const demoWorkflow: Workflow;
+export declare const demoInput: {
+    question: string;
+};
+export declare const demoSources: {
+    id: string;
+    text: string;
+}[];
+export declare const demoQuestions: string[];
+export declare function demoSearchTool(): PiToolDefinition;
+export declare function scriptedDemoDeps(noEvidence?: boolean): WorkflowDeps;

package/dist/demo.js

@@ -0,0 +1,44 @@
+import { demoData } from './demo-data.js';
+export const demoWorkflow = demoData.workflow;
+export const demoInput = { question: demoData.question };
+export const demoSources = demoData.sources;
+export const demoQuestions = demoData.subquestions;
+export function demoSearchTool() {
+    return {
+        name: 'search', label: 'Search example sources',
+        description: 'Read the bundled fictional wiki-migration sources. This does not search the internet.',
+        parameters: { type: 'object', properties: { question: { type: 'string' } }, required: ['question'], additionalProperties: false },
+        async execute(_id, _args, signal) {
+            signal?.throwIfAborted();
+            return { content: [{ type: 'text', text: JSON.stringify({ sources: demoSources }) }], details: { sources: structuredClone(demoSources) } };
+        },
+    };
+}
+export function scriptedDemoDeps(noEvidence = false) {
+    return {
+        runEffect: async ({ node, signal }) => {
+            signal?.throwIfAborted();
+            if (node.tool !== 'search')
+                throw new Error('Unknown demo tool');
+            return { sources: structuredClone(demoSources) };
+        },
+        runJudge: async ({ questions, state, signal }) => {
+            signal?.throwIfAborted();
+            const data = state;
+            const selected = demoData.evidenceIds[demoQuestions.indexOf(data.subquestion)];
+            return { answers: Object.fromEntries(Object.keys(questions).map(id => [id, {
+                        type: 'noul', noul: !noEvidence && data.items[Number(id.split('.')[0])]?.item.id === selected ? 0.95 : 0.05,
+                    }])) };
+        },
+        runNode: async ({ label, user, signal }) => {
+            signal?.throwIfAborted();
+            const input = JSON.parse(user);
+            switch (label.split('/').at(-1)) {
+                case 'plan': return { questions: demoQuestions };
+                case 'write-finding': return { question: input.question, answer: input.sources.map((s) => s.text).join(' '), sources: input.sources };
+                case 'write-report': return { answer: 'Pilot the repository workflow first. Reviews gain an explicit approval step, but editing and search still have gaps.', findings: input.findings };
+                default: throw new Error('Unknown scripted demo step');
+            }
+        },
+    };
+}

package/dist/extension-service.d.ts

@@ -0,0 +1,110 @@
+import { type Workflow, type WorkflowDeps, type WorkflowInspection, type Escalation } from '@parcha/agentrun-dsl';
+type Event = Parameters<NonNullable<WorkflowDeps['onEvent']>>[0];
+type Counts = {
+    agent: number;
+    judge: number;
+    tool: number;
+};
+export interface ExtensionServiceLimits {
+    /** null disables a host admission/deadline limit; omission retains defaults. */
+    deadlineMs: number | null;
+    maxAgentCalls: number | null;
+    maxJudgeCalls: number | null;
+    maxToolCalls: number | null;
+    maxConcurrency: number;
+    /** Retained sanitized event bytes, not an execution limit. Old events may be omitted. */
+    maxTraceBytes: number;
+    /** Independent per-event JSON safety limit; exceeding it fails closed. */
+    maxEventBytes: number;
+}
+export interface ExtensionServiceOptions {
+    allowedTools?: readonly string[];
+    rubricSections?: Record<string, string>;
+    limits?: Partial<ExtensionServiceLimits>;
+}
+export interface PreparedWorkflow {
+    digest: string;
+    inspection: WorkflowInspection;
+    workflow: Workflow;
+    executableAuthorized: boolean;
+}
+export interface ExtensionRunReport {
+    digest: string;
+    status: 'complete' | 'escalated' | 'failed' | 'interrupted';
+    calls: Counts;
+    events: Event[];
+    output?: unknown;
+    escalation?: Pick<Escalation, 'kind' | 'stage' | 'summary' | 'label' | 'executionPath'>;
+    error?: {
+        code: string;
+        message: string;
+        stage?: string;
+        path?: string;
+        reason?: string;
+        status?: number;
+        problems?: string[];
+        stateBytes?: number;
+        maxStateBytes?: number;
+    };
+    uncertainEffects?: {
+        idempotencyKey: string;
+        executionPath?: string;
+        outcome: 'unknown';
+    }[];
+    traceTruncated?: boolean;
+    /** Received counts include validated events only; rejected events have no safe byte size. */
+    trace?: {
+        policy: 'tail';
+        receivedEvents: number;
+        receivedBytes: number;
+        rejectedEvents: number;
+        retainedEvents: number;
+        retainedBytes: number;
+        droppedEvents: number;
+        droppedBytes: number;
+    };
+}
+export interface ExtensionRunOptions {
+    deps: WorkflowDeps;
+    signal?: AbortSignal;
+    /** Best-effort UI observation; suppressed after cancellation/disposal. */
+    onEvent?: (event: Event) => unknown;
+    /** Full sanitized valid stream, including cleanup before closure. Nonfatal;
+     * host owns persistence failures and any asynchronous queue/drain. */
+    onTraceEvent?: (event: Event) => unknown;
+}
+export declare class ExtensionServiceError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare const extensionStructuralLimits: Readonly<{
+    maxNodes: 200;
+    maxMapConcurrency: 8;
+    maxParallelBranches: 8;
+}>;
+export declare class WorkflowExtensionService {
+    private readonly allowedTools;
+    private readonly rubricSections;
+    private readonly limits;
+    private current?;
+    private lastReport?;
+    private disposed;
+    private active?;
+    constructor(options?: ExtensionServiceOptions);
+    private available;
+    private idle;
+    private check;
+    /** Admission and syntax feedback only: never executes code or authorizes a run. */
+    preflight(value: unknown, input?: Record<string, unknown>): WorkflowInspection;
+    prepare(value: unknown, options?: {
+        allowExecutableCandidates?: boolean;
+    }): PreparedWorkflow;
+    inspect(): {
+        current?: PreparedWorkflow;
+        lastReport?: ExtensionRunReport;
+    };
+    stop(): void;
+    dispose(): Promise<void>;
+    run(input: Record<string, unknown>, options: ExtensionRunOptions): Promise<ExtensionRunReport>;
+}
+export {};