@hanfani/core 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aziz Mashkour
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @hanfani/core
+
+Headless engine and types for the Hanfani agent framework.
+
+Pure logic — no I/O, no server, no React. This is the layer that defines what a
+workflow and an agent *are* and enforces the framework's one safety invariant:
+
+> An agent proposes, a human approves, the server acts.
+
+`defineAgent` refuses any `effect` that isn't also an `approval`, so a side
+effect can never be wired to fire without a human gate. `providerConformanceChecks`
+proves any provider honours that at runtime.
+
+## Exports
+
+- **Definitions:** `defineAgent`, `defineWorkflow`, `definePrompt`,
+  `defineProviders`, `AgentDefinitionSchema`.
+- **Messages:** `isAssistant`, `isToolMessage`, `toolCallsOf`,
+  `hasPendingApproval`, `pairToolResults`, `lastApprovalArgs`,
+  `resolvedApprovalCount`, `approvalResolved`.
+- **Handoffs:** `encodeHandoff`, `decodeHandoff`, `handoffNote`,
+  `HandoffPayloadSchema`, `TicketHandoffPayloadSchema`.
+- **Gates & events:** `gateOpened`, `readGateOpened`, `GATE_OPENED`,
+  `GateOpenedValueSchema`, `lifecycleNote`, `LIFECYCLE_NOTE_TEXT`,
+  `foldEventsToMessages`.
+- **Lifecycle & delivery:** `lifecycle`, `hasLiveDescendant`, `resolveDelivery`,
+  `instanceId`, `composeInstructions`.
+- **Providers & integration:** `providerConformanceChecks`, `aggregateHealth`,
+  `isOk`, `isOAuth2`.
+- Plus the full type surface (`WorkflowDescriptor`, `Outcome`, `Phase`,
+  `Provider`, `EffectFn`, `AuthSpec`, `ResolvedCredential`, …).
+
+## Build & test
+
+Built with the native TypeScript 7 compiler (`tsc` / tsgo) — no bundler, no
+compiler-API tooling, so nothing here breaks on the TS 7 upgrade.
+
+```bash
+pnpm build       # tsc -p tsconfig.build.json → dist/*.js + dist/*.d.ts
+pnpm typecheck   # tsc -p tsconfig.json --noEmit
+pnpm test        # vitest smoke suite
+```
+
+## Peer runtime
+
+Depends on `@ag-ui/client` (event/message types) and `zod` (schemas). Both are
+declared as regular dependencies.

package/dist/conformance.d.ts

@@ -0,0 +1,25 @@
+import type { RunAgentInput } from '@ag-ui/client';
+import type { GateResolution, Provider, ResumeHandle } from './types.js';
+export interface ConformanceScenario {
+    approvalNames: readonly string[];
+    surfaceTools: readonly string[];
+    turn1Input: RunAgentInput;
+    approved: {
+        handle: ResumeHandle;
+        resolution: GateResolution;
+    };
+    rejected: {
+        handle: ResumeHandle;
+        resolution: GateResolution;
+    };
+}
+export interface ConformanceCheck {
+    name: string;
+    run(makeProvider: () => Provider, scenario: ConformanceScenario): Promise<void>;
+}
+/**
+ * A provider-agnostic conformance suite: any Provider implementation can be run
+ * against these checks to prove it honours the framework's gate/effect contract.
+ */
+export declare const providerConformanceChecks: ConformanceCheck[];
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAExE,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,UAAU,EAAE,aAAa,CAAA;IACzB,QAAQ,EAAE;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,UAAU,EAAE,cAAc,CAAA;KAAE,CAAA;IAC9D,QAAQ,EAAE;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,UAAU,EAAE,cAAc,CAAA;KAAE,CAAA;CAC/D;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,YAAY,EAAE,MAAM,QAAQ,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChF;AAuBD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,gBAAgB,EA0EvD,CAAA"}

package/dist/conformance.js

@@ -0,0 +1,90 @@
+import { EventType } from '@ag-ui/client';
+import { readGateOpened } from './gate.js';
+async function collect(events) {
+    const out = [];
+    for await (const e of events)
+        out.push(e);
+    return out;
+}
+function gatesIn(events) {
+    const out = [];
+    for (const e of events) {
+        const gate = readGateOpened(e);
+        if (gate)
+            out.push(gate);
+    }
+    return out;
+}
+function assert(cond, message) {
+    if (!cond)
+        throw new Error(`conformance: ${message}`);
+}
+/**
+ * A provider-agnostic conformance suite: any Provider implementation can be run
+ * against these checks to prove it honours the framework's gate/effect contract.
+ */
+export const providerConformanceChecks = [
+    {
+        name: 'turn 1 opens exactly one approval gate matching an approval tool',
+        async run(makeProvider, scenario) {
+            const events = await collect(makeProvider().run(scenario.turn1Input));
+            const gates = gatesIn(events);
+            assert(gates.length === 1, `expected 1 GATE_OPENED, got ${gates.length}`);
+            const gate = gates[0];
+            assert(scenario.approvalNames.includes(gate.toolName), `gate toolName "${gate.toolName}" is not an approval`);
+            const startIds = events
+                .filter((e) => e.type === EventType.TOOL_CALL_START)
+                .map((e) => e.toolCallId);
+            assert(startIds.includes(gate.toolCallId), 'gate toolCallId has no matching TOOL_CALL_START');
+        },
+    },
+    {
+        name: 'resume(approved) completes and re-opens no gate',
+        async run(makeProvider, scenario) {
+            const provider = makeProvider();
+            assert(typeof provider.resume === 'function', 'provider does not implement resume()');
+            const events = await collect(provider.resume(scenario.approved.handle, scenario.approved.resolution));
+            assert(gatesIn(events).length === 0, 'resume(approved) re-opened a gate');
+            assert(events.length > 0, 'resume(approved) produced no events');
+        },
+    },
+    {
+        name: 'resume(rejected) terminates and re-opens no gate',
+        async run(makeProvider, scenario) {
+            const provider = makeProvider();
+            assert(typeof provider.resume === 'function', 'provider does not implement resume()');
+            const events = await collect(provider.resume(scenario.rejected.handle, scenario.rejected.resolution));
+            assert(gatesIn(events).length === 0, 'resume(rejected) re-opened a gate');
+            assert(events.length > 0, 'resume(rejected) produced no events');
+            assert(events.filter((e) => e.type === EventType.TOOL_CALL_START).length === 0, 'resume(rejected) emitted a tool call (possible effect)');
+        },
+    },
+    {
+        name: 'only surfaced tools appear as tool calls on turn 1',
+        async run(makeProvider, scenario) {
+            const events = await collect(makeProvider().run(scenario.turn1Input));
+            const toolNames = events
+                .filter((e) => e.type === EventType.TOOL_CALL_START)
+                .map((e) => e.toolCallName);
+            for (const name of toolNames) {
+                assert(name !== undefined && scenario.surfaceTools.includes(name), `surfaced an undeclared tool: "${name}"`);
+            }
+        },
+    },
+    {
+        name: 'every TOOL_CALL_START on turn 1 has a matching TOOL_CALL_END with the same toolCallId',
+        async run(makeProvider, scenario) {
+            const events = await collect(makeProvider().run(scenario.turn1Input));
+            const startIds = events
+                .filter((e) => e.type === EventType.TOOL_CALL_START)
+                .map((e) => e.toolCallId);
+            const endIds = new Set(events
+                .filter((e) => e.type === EventType.TOOL_CALL_END)
+                .map((e) => e.toolCallId));
+            for (const id of startIds) {
+                assert(endIds.has(id), `TOOL_CALL_START id "${id}" has no matching TOOL_CALL_END`);
+            }
+        },
+    },
+];
+//# sourceMappingURL=conformance.js.map

package/dist/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"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"}

package/dist/defineAgent.d.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+/**
+ * The agent contract. `superRefine` enforces the framework's structural rules:
+ * approvals/renders/dispatches must be declared tools, and every effect must be
+ * an approval (so a side effect can never fire without a human gate).
+ */
+export declare const AgentDefinitionSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    provider: z.ZodString;
+    instructions: z.ZodString;
+    tools: z.ZodArray<z.ZodString, "many">;
+    approvals: z.ZodArray<z.ZodString, "many">;
+    renders: z.ZodRecord<z.ZodString, z.ZodString>;
+    handoffs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    maxInstances: z.ZodDefault<z.ZodNumber>;
+    effects: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    readonly: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    dispatches: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    provider: string;
+    instructions: string;
+    tools: string[];
+    approvals: string[];
+    renders: Record<string, string>;
+    handoffs?: string[] | undefined;
+    maxInstances: number;
+    effects: string[];
+    readonly: string[];
+    dispatches: string[];
+}, {
+    id: string;
+    name: string;
+    provider: string;
+    instructions: string;
+    tools: string[];
+    approvals: string[];
+    renders: Record<string, string>;
+    handoffs?: string[] | undefined;
+    maxInstances?: number | undefined;
+    effects?: string[] | undefined;
+    readonly?: string[] | undefined;
+    dispatches?: string[] | undefined;
+}>, {
+    id: string;
+    name: string;
+    provider: string;
+    instructions: string;
+    tools: string[];
+    approvals: string[];
+    renders: Record<string, string>;
+    handoffs?: string[] | undefined;
+    maxInstances: number;
+    effects: string[];
+    readonly: string[];
+    dispatches: string[];
+}, {
+    id: string;
+    name: string;
+    provider: string;
+    instructions: string;
+    tools: string[];
+    approvals: string[];
+    renders: Record<string, string>;
+    handoffs?: string[] | undefined;
+    maxInstances?: number | undefined;
+    effects?: string[] | undefined;
+    readonly?: string[] | undefined;
+    dispatches?: string[] | undefined;
+}>;
+export type AgentDefinition = z.infer<typeof AgentDefinitionSchema>;
+export type AgentDefinitionInput = z.input<typeof AgentDefinitionSchema>;
+export declare function defineAgent(def: AgentDefinitionInput): AgentDefinition;
+//# sourceMappingURL=defineAgent.d.ts.map

package/dist/defineAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineAgent.d.ts","sourceRoot":"","sources":["../src/defineAgent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgD9B,CAAA;AAEJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AACnE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAExE,wBAAgB,WAAW,CAAC,GAAG,EAAE,oBAAoB,GAAG,eAAe,CAEtE"}

package/dist/defineAgent.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+/**
+ * The agent contract. `superRefine` enforces the framework's structural rules:
+ * approvals/renders/dispatches must be declared tools, and every effect must be
+ * an approval (so a side effect can never fire without a human gate).
+ */
+export const AgentDefinitionSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    provider: z.string(),
+    instructions: z.string(),
+    tools: z.array(z.string()),
+    approvals: z.array(z.string()),
+    renders: z.record(z.string()),
+    handoffs: z.array(z.string()).optional(),
+    maxInstances: z.number().int().positive().default(1),
+    effects: z.array(z.string()).default([]),
+    readonly: z.array(z.string()).default([]),
+    dispatches: z.array(z.string()).default([]),
+})
+    .superRefine((def, ctx) => {
+    for (const approval of def.approvals) {
+        if (!def.tools.includes(approval)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `approval "${approval}" is not declared in tools`,
+            });
+        }
+    }
+    for (const renderKey of Object.keys(def.renders)) {
+        if (!def.tools.includes(renderKey)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `render key "${renderKey}" is not declared in tools`,
+            });
+        }
+    }
+    for (const effect of def.effects) {
+        if (!def.approvals.includes(effect)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `effect "${effect}" is not an approval`,
+            });
+        }
+    }
+    for (const dispatch of def.dispatches) {
+        if (!def.tools.includes(dispatch)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `dispatch "${dispatch}" is not declared in tools`,
+            });
+        }
+    }
+});
+export function defineAgent(def) {
+    return AgentDefinitionSchema.parse(def);
+}
+//# sourceMappingURL=defineAgent.js.map

package/dist/defineAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineAgent.js","sourceRoot":"","sources":["../src/defineAgent.ts"],"names":[],"mappings":"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"}

package/dist/definePrompt.d.ts

@@ -0,0 +1,15 @@
+import type { z } from 'zod';
+import type { PromptStrategy, ResumeOutcome } from './types.js';
+export interface PromptSpec<T> {
+    input?: z.ZodType<T>;
+    onInput?: (payload: T) => string;
+    onStart: () => string;
+    onResume?: (result: Record<string, unknown>) => ResumeOutcome;
+}
+/**
+ * Build a prompt strategy: on the first turn, decode any handoff payload and
+ * route it through `onInput`, else `onStart`; on resume, hand the executed
+ * result to `onResume`.
+ */
+export declare function definePrompt<T>(spec: PromptSpec<T>): PromptStrategy;
+//# sourceMappingURL=definePrompt.d.ts.map

package/dist/definePrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definePrompt.d.ts","sourceRoot":"","sources":["../src/definePrompt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/D,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,CAAA;IAChC,OAAO,EAAE,MAAM,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,aAAa,CAAA;CAC9D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAenE"}

package/dist/definePrompt.js

@@ -0,0 +1,23 @@
+import { decodeHandoff } from './handoff.js';
+/**
+ * Build a prompt strategy: on the first turn, decode any handoff payload and
+ * route it through `onInput`, else `onStart`; on resume, hand the executed
+ * result to `onResume`.
+ */
+export function definePrompt(spec) {
+    const { onResume } = spec;
+    return {
+        buildFirst(input) {
+            if (spec.input && spec.onInput) {
+                const payload = decodeHandoff(input, spec.input);
+                if (payload)
+                    return spec.onInput(payload);
+            }
+            return spec.onStart();
+        },
+        buildResume: onResume
+            ? (_args, executedResult) => onResume(executedResult ?? {})
+            : undefined,
+    };
+}
+//# sourceMappingURL=definePrompt.js.map

package/dist/definePrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definePrompt.js","sourceRoot":"","sources":["../src/definePrompt.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAU5C;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAI,IAAmB;IACjD,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;IACzB,OAAO;QACL,UAAU,CAAC,KAAoB;YAC7B,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAC/B,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;gBAChD,IAAI,OAAO;oBAAE,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;YAC3C,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,EAAE,CAAA;QACvB,CAAC;QACD,WAAW,EAAE,QAAQ;YACnB,CAAC,CAAC,CAAC,KAA8B,EAAE,cAAwC,EAAE,EAAE,CAC3E,QAAQ,CAAC,cAAc,IAAI,EAAE,CAAC;YAClC,CAAC,CAAC,SAAS;KACd,CAAA;AACH,CAAC"}

package/dist/defineWorkflow.d.ts

@@ -0,0 +1,10 @@
+import type { WorkflowDescriptor } from './types.js';
+/** Stable instance id for an agent within a workflow. */
+export declare function instanceId(workflowId: string, agentId: string): string;
+/**
+ * Validate a workflow descriptor's internal consistency: unique agent ids, a
+ * role:input entry agent, handoffs that point inside the workflow, unique input
+ * names, and inputs bound to input-role agents. Returns the descriptor as-is.
+ */
+export declare function defineWorkflow(def: WorkflowDescriptor): WorkflowDescriptor;
+//# sourceMappingURL=defineWorkflow.d.ts.map

package/dist/defineWorkflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineWorkflow.d.ts","sourceRoot":"","sources":["../src/defineWorkflow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,kBAAkB,GAAG,kBAAkB,CAuC1E"}

package/dist/defineWorkflow.js

@@ -0,0 +1,38 @@
+/** Stable instance id for an agent within a workflow. */
+export function instanceId(workflowId, agentId) {
+    return `${workflowId}__${agentId}`;
+}
+/**
+ * Validate a workflow descriptor's internal consistency: unique agent ids, a
+ * role:input entry agent, handoffs that point inside the workflow, unique input
+ * names, and inputs bound to input-role agents. Returns the descriptor as-is.
+ */
+export function defineWorkflow(def) {
+    const agentIds = def.agents.map((a) => a.agent.id);
+    const dupAgent = agentIds.find((id, i) => agentIds.indexOf(id) !== i);
+    if (dupAgent)
+        throw new Error(`workflow "${def.id}": duplicate agent id "${dupAgent}"`);
+    const inputAgentIds = new Set(def.agents.filter((a) => a.role === 'input').map((a) => a.agent.id));
+    const allAgentIds = new Set(agentIds);
+    if (!inputAgentIds.has(def.entryAgentId)) {
+        throw new Error(`workflow "${def.id}": entry agent "${def.entryAgentId}" is not a role:input agent`);
+    }
+    for (const a of def.agents) {
+        for (const target of a.agent.handoffs ?? []) {
+            if (!allAgentIds.has(target)) {
+                throw new Error(`workflow "${def.id}": agent "${a.agent.id}" hands off to "${target}" which is not in this workflow`);
+            }
+        }
+    }
+    const inputNames = def.inputs.map((i) => i.name);
+    const dupInput = inputNames.find((n, i) => inputNames.indexOf(n) !== i);
+    if (dupInput)
+        throw new Error(`workflow "${def.id}": duplicate published input name "${dupInput}"`);
+    for (const input of def.inputs) {
+        if (!inputAgentIds.has(input.agentId)) {
+            throw new Error(`workflow "${def.id}": input "${input.name}" is bound to "${input.agentId}" which is not a role:input agent`);
+        }
+    }
+    return def;
+}
+//# sourceMappingURL=defineWorkflow.js.map

package/dist/defineWorkflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineWorkflow.js","sourceRoot":"","sources":["../src/defineWorkflow.ts"],"names":[],"mappings":"AAEA,yDAAyD;AACzD,MAAM,UAAU,UAAU,CAAC,UAAkB,EAAE,OAAe;IAC5D,OAAO,GAAG,UAAU,KAAK,OAAO,EAAE,CAAA;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAuB;IACpD,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAClD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IACrE,IAAI,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,EAAE,0BAA0B,QAAQ,GAAG,CAAC,CAAA;IAEvF,MAAM,aAAa,GAAG,IAAI,GAAG,CAC3B,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CACpE,CAAA;IACD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAA;IAErC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,aAAa,GAAG,CAAC,EAAE,mBAAmB,GAAG,CAAC,YAAY,6BAA6B,CACpF,CAAA;IACH,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC3B,KAAK,MAAM,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;YAC5C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CACb,aAAa,GAAG,CAAC,EAAE,aAAa,CAAC,CAAC,KAAK,CAAC,EAAE,mBAAmB,MAAM,iCAAiC,CACrG,CAAA;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;IACvE,IAAI,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,EAAE,sCAAsC,QAAQ,GAAG,CAAC,CAAA;IAEnG,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,aAAa,GAAG,CAAC,EAAE,aAAa,KAAK,CAAC,IAAI,kBAAkB,KAAK,CAAC,OAAO,mCAAmC,CAC7G,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/delivery.d.ts

@@ -0,0 +1,8 @@
+import type { DeliveryResult, Destination, WorkflowDescriptor } from './types.js';
+/**
+ * Resolve where a payload should be delivered. Agent destinations resolve
+ * directly; contract destinations validate the payload against the target
+ * workflow's published input schema before resolving.
+ */
+export declare function resolveDelivery(workflows: WorkflowDescriptor[], origin: string, dest: Destination, payload: unknown): DeliveryResult;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEjF;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,kBAAkB,EAAE,EAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,OAAO,GACf,cAAc,CAchB"}

package/dist/delivery.js

@@ -0,0 +1,21 @@
+import { instanceId } from './defineWorkflow.js';
+/**
+ * Resolve where a payload should be delivered. Agent destinations resolve
+ * directly; contract destinations validate the payload against the target
+ * workflow's published input schema before resolving.
+ */
+export function resolveDelivery(workflows, origin, dest, payload) {
+    if (dest.kind === 'agent') {
+        return { ok: true, instanceId: instanceId(origin, dest.agentId) };
+    }
+    const workflow = workflows.find((w) => w.id === dest.workflow);
+    if (!workflow)
+        return { ok: false, error: `unknown workflow "${dest.workflow}"` };
+    const input = workflow.inputs.find((i) => i.name === dest.input);
+    if (!input)
+        return { ok: false, error: `workflow "${dest.workflow}" has no input "${dest.input}"` };
+    return input.schema.safeParse(payload).success
+        ? { ok: true, instanceId: instanceId(workflow.id, input.agentId), targetWorkflow: workflow.id }
+        : { ok: false, error: `payload does not match contract "${dest.workflow}.${dest.input}"` };
+}
+//# sourceMappingURL=delivery.js.map

package/dist/delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.js","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAGhD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,SAA+B,EAC/B,MAAc,EACd,IAAiB,EACjB,OAAgB;IAEhB,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAA;IACnE,CAAC;IAED,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC9D,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,qBAAqB,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAA;IAEjF,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,CAAA;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,IAAI,CAAC,QAAQ,mBAAmB,IAAI,CAAC,KAAK,GAAG,EAAE,CAAA;IAEnG,OAAO,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO;QAC5C,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,EAAE;QAC/F,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,oCAAoC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,GAAG,EAAE,CAAA;AAC9F,CAAC"}

package/dist/fold.d.ts

@@ -0,0 +1,8 @@
+import type { BaseEvent, Message } from '@ag-ui/client';
+/**
+ * Fold an ag-ui event stream into a flat list of messages: text chunks merge by
+ * messageId, tool calls attach to their parent assistant message, tool results
+ * become tool messages, and lifecycle/handoff custom events become notes.
+ */
+export declare function foldEventsToMessages(events: readonly BaseEvent[]): Message[];
+//# sourceMappingURL=fold.d.ts.map

package/dist/fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../src/fold.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAsCvD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,EAAE,CAoF5E"}

package/dist/fold.js

@@ -0,0 +1,98 @@
+import { EventType } from '@ag-ui/client';
+import { LIFECYCLE_NOTE_TEXT } from './lifecycleNote.js';
+/**
+ * Fold an ag-ui event stream into a flat list of messages: text chunks merge by
+ * messageId, tool calls attach to their parent assistant message, tool results
+ * become tool messages, and lifecycle/handoff custom events become notes.
+ */
+export function foldEventsToMessages(events) {
+    const messages = new Map();
+    const parentByToolCall = new Map();
+    for (const raw of events) {
+        const e = raw;
+        switch (e.type) {
+            case EventType.TEXT_MESSAGE_CHUNK: {
+                const id = e.messageId;
+                if (!id)
+                    break;
+                const existing = messages.get(id);
+                if (existing && existing.role === 'assistant') {
+                    existing.content = (existing.content ?? '') + (e.delta ?? '');
+                }
+                else {
+                    messages.set(id, { id, role: 'assistant', content: e.delta ?? '' });
+                }
+                break;
+            }
+            case EventType.TOOL_CALL_START: {
+                const id = e.toolCallId;
+                if (!id)
+                    break;
+                const parentId = e.parentMessageId ?? `tc-${id}`;
+                let parent = messages.get(parentId);
+                if (!parent || parent.role !== 'assistant') {
+                    parent = { id: parentId, role: 'assistant', content: '', toolCalls: [] };
+                    messages.set(parentId, parent);
+                }
+                parent.toolCalls ||= [];
+                parent.toolCalls.push({
+                    id,
+                    type: 'function',
+                    function: { name: e.toolCallName ?? '', arguments: '' },
+                });
+                parentByToolCall.set(id, parentId);
+                break;
+            }
+            case EventType.TOOL_CALL_ARGS: {
+                const id = e.toolCallId;
+                if (!id)
+                    break;
+                const parentId = parentByToolCall.get(id);
+                if (!parentId)
+                    break;
+                const call = messages.get(parentId)?.toolCalls?.find((c) => c.id === id);
+                if (call)
+                    call.function.arguments += e.delta ?? '';
+                break;
+            }
+            case EventType.TOOL_CALL_END:
+                break;
+            case EventType.TOOL_CALL_RESULT: {
+                const id = e.toolCallId;
+                const msgId = e.messageId ?? (id ? `result-${id}` : undefined);
+                if (!msgId || !id)
+                    break;
+                messages.set(msgId, { id: msgId, role: 'tool', toolCallId: id, content: e.content ?? '' });
+                break;
+            }
+            case EventType.CUSTOM: {
+                if (e.name === 'lifecycle') {
+                    const v = e.value;
+                    if (v && v.outcome !== undefined) {
+                        const text = LIFECYCLE_NOTE_TEXT[v.outcome] || v.outcome;
+                        const id = `lifecycle-${v.at}`;
+                        messages.set(id, { id, role: 'system', content: text });
+                    }
+                    break;
+                }
+                if (e.name === 'handoff' && e.value) {
+                    const v = e.value;
+                    const id = `handoff-${v.childWorkItemId}`;
+                    messages.set(id, {
+                        id,
+                        role: 'handoff',
+                        targetAgentId: v.targetAgentId,
+                        childWorkItemId: v.childWorkItemId,
+                        deduped: v.deduped,
+                    });
+                    break;
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return [...messages.values()];
+}
+//# sourceMappingURL=fold.js.map

package/dist/fold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.js","sourceRoot":"","sources":["../src/fold.ts"],"names":[],"mappings":"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"}

package/dist/gate.d.ts

@@ -0,0 +1,25 @@
+import type { BaseEvent, CustomEvent as AguiCustomEvent } from '@ag-ui/client';
+import { z } from 'zod';
+export declare const GATE_OPENED: 'GATE_OPENED';
+export declare const GateOpenedValueSchema: z.ZodObject<{
+    gateKind: z.ZodLiteral<"approval">;
+    toolName: z.ZodString;
+    toolCallId: z.ZodString;
+    proposedArtifact: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    gateKind: "approval";
+    toolName: string;
+    toolCallId: string;
+    proposedArtifact: Record<string, unknown>;
+}, {
+    gateKind: "approval";
+    toolName: string;
+    toolCallId: string;
+    proposedArtifact: Record<string, unknown>;
+}>;
+export type GateOpenedValue = z.infer<typeof GateOpenedValueSchema>;
+/** Emit the custom event that opens a human-approval gate. */
+export declare function gateOpened(value: GateOpenedValue): AguiCustomEvent;
+/** Read a GATE_OPENED value off an event, or null if it isn't one. */
+export declare function readGateOpened(event: BaseEvent): GateOpenedValue | null;
+//# sourceMappingURL=gate.d.ts.map