@agenticprimitives/orchestration 0.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust Labs
+
+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,61 @@
+# @agenticprimitives/orchestration
+
+The Ring-0 **agentic orchestration core**: the intent → plan → execute → observe loop, the `Planner` and
+`ToolInvoker` ports, and a deterministic rule-based planner. A first-party app expresses a **goal**; this
+package plans which tools compose to satisfy it and runs them through an injected invoker — the web never
+names a tool (ADR-0044). Pure leaf: no transport, no LLM SDK, no chain. The concrete LLM binding lives behind
+the `Planner` port in [`@agenticprimitives/orchestration-anthropic`](../orchestration-anthropic).
+
+## Install
+
+```bash
+pnpm add @agenticprimitives/orchestration
+```
+
+## Quick start
+
+```ts
+import { runIntent, createRuleBasedPlanner, type ToolSpec } from '@agenticprimitives/orchestration';
+
+const tools: ToolSpec[] = [
+  { id: 'get_vault_record', description: 'Read one of the principal’s vault records by recordType.' },
+  { id: 'get_pii', description: 'Read the principal’s PII (high sensitivity).' },
+];
+
+// Deterministic default planner — goal → tool. No model, no creds.
+const planner = createRuleBasedPlanner([
+  { match: /profile/, toolId: 'get_vault_record', args: { recordType: 'impact-profile' } },
+  { match: /pii|personal/, toolId: 'get_pii' },
+]);
+
+const result = await runIntent(
+  { goal: 'read my profile' },
+  {
+    planner,
+    tools,
+    // The invoker is where authority lives — the a2a skill binds this to the task's delegation.
+    invoke: async (toolId, args) => myMcpCall(toolId, args),
+  },
+);
+
+if (result.outcome === 'completed') console.log(result.result);
+```
+
+## Concepts
+
+- **`Intent`** — a declarative goal (`{ goal, constraints?, context? }`), never a tool name or call sequence.
+- **`Planner`** — the injected port that turns a goal + the exposed `ToolSpec[]` into a `Plan`. Swap the
+  deterministic `createRuleBasedPlanner` for the LLM adapter without touching the loop.
+- **`ToolInvoker`** — the injected port that executes one step. The orchestration core never holds a token,
+  key, or chain client; the invoker carries the on-chain authority (delegation).
+- **`runIntent`** — the loop: plan → execute (with `{ $ref }` result threading) → observe → bounded re-plan on
+  failure. Fail-closed: every error path returns a `failed` `RunResult`.
+
+## Boundaries
+
+Pure leaf. Forbidden imports: `a2a`, `mcp-runtime`, `mcp-protocol`, `delegation`, `service-agent`, and any LLM
+SDK. See `spec.md` + `capability.manifest.json`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { PACKAGE_NAME, PACKAGE_STATUS, SPEC_REF, OrchestrationError } from './types.js';
+export type { Intent, ToolSpec, PlanStep, Plan, StepObservation, RunOutcome, RunResult, OrchestrationErrorCode, } from './types.js';
+export { createRuleBasedPlanner } from './planner.js';
+export type { Planner, PlanInput, PlanRule } from './planner.js';
+export type { ToolInvoker, InvokeContext } from './tool-invoker.js';
+export { runIntent } from './loop.js';
+export type { RunIntentOpts } from './loop.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACxF,YAAY,EACV,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,eAAe,EACf,UAAU,EACV,SAAS,EACT,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEjE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEpE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// @agenticprimitives/orchestration — public API. The Ring-0 agentic loop: the intent→plan→execute→observe
+// model, the Planner + ToolInvoker PORTS, and `runIntent`. Pure leaf — no transport, no LLM SDK, no chain.
+// The LLM binding lives in `@agenticprimitives/orchestration-anthropic` (behind the Planner port). ADR-0044.
+export { PACKAGE_NAME, PACKAGE_STATUS, SPEC_REF, OrchestrationError } from './types.js';
+export { createRuleBasedPlanner } from './planner.js';
+export { runIntent } from './loop.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,2GAA2G;AAC3G,6GAA6G;AAE7G,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAYxF,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAKtD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/loop.d.ts

@@ -0,0 +1,25 @@
+import type { Intent, RunResult, StepObservation, ToolSpec } from './types.js';
+import type { Planner } from './planner.js';
+import type { ToolInvoker } from './tool-invoker.js';
+export interface RunIntentOpts {
+    /** The injected planning port (deterministic default or the LLM adapter). */
+    planner: Planner;
+    /** The tools the agent exposes — the plan may only reference these (fail-closed). */
+    tools: ToolSpec[];
+    /** The injected tool executor (the a2a skill binds it to the task delegation). */
+    invoke: ToolInvoker;
+    /** Hard cap on total step executions across all (re-)plans. Default 8. */
+    maxSteps?: number;
+    /** How many times the loop re-plans after a step failure. Default 1 (one observe→re-plan cycle). */
+    maxReplans?: number;
+    /** Optional observer for each executed step (telemetry; never authority). */
+    onObserve?: (obs: StepObservation) => void;
+}
+/**
+ * Run an intent to a terminal result. Plans, executes the steps in order (threading `ref` results into later
+ * args), observes, and re-plans (bounded) when a step throws. Returns `completed` with the last successful
+ * step's result, or `failed` with the error. Fail-closed throughout: an unknown tool, an empty plan, no plan,
+ * or an exhausted step budget all produce a `failed` RunResult (never a misleading empty success).
+ */
+export declare function runIntent(intent: Intent, opts: RunIntentOpts): Promise<RunResult>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAkB,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE/F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,kFAAkF;IAClF,MAAM,EAAE,WAAW,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAC;CAC5C;AAiDD;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CA6DvF"}

package/dist/loop.js

@@ -0,0 +1,113 @@
+import { OrchestrationError } from './types.js';
+/** Read a dot/index path (e.g. `list.record_types.0.record_type`) out of the ref store. A bare name with no
+ *  dots is a plain top-level lookup. A missing segment short-circuits to `undefined` (the tool then validates
+ *  its own args — fail-closed, no path traversal / eval). */
+function getPath(root, path) {
+    return path.split('.').reduce((acc, seg) => (acc == null ? undefined : acc[seg]), root);
+}
+/** Recursively resolve `{ $ref: 'name.path' }` placeholders (anywhere — nested objects/arrays included)
+ *  against prior step results. Non-placeholder values pass through unchanged. */
+function resolveValue(v, refs) {
+    if (Array.isArray(v))
+        return v.map((x) => resolveValue(x, refs));
+    if (v && typeof v === 'object') {
+        if ('$ref' in v) {
+            const ref = v.$ref;
+            return typeof ref === 'string' ? getPath(refs, ref) : undefined;
+        }
+        const out = {};
+        for (const [k, val] of Object.entries(v))
+            out[k] = resolveValue(val, refs);
+        return out;
+    }
+    return v;
+}
+/** Resolve `{ $ref }` arg placeholders against prior step results (supports `name.path.0.field`). */
+function resolveArgs(args, refs) {
+    return resolveValue(args, refs);
+}
+/** Assert every step targets an exposed tool — fail-closed before any invocation (ADR-0013). */
+function assertKnownTools(plan, toolIds) {
+    for (const step of plan.steps) {
+        if (!toolIds.has(step.toolId)) {
+            throw new OrchestrationError('unknown_tool', `plan selected a tool not exposed by this agent: ${step.toolId}`);
+        }
+    }
+    if (plan.steps.length === 0)
+        throw new OrchestrationError('empty_plan', 'the planner returned a plan with no steps');
+}
+async function callPlanner(planner, input) {
+    try {
+        return await planner.plan(input);
+    }
+    catch (e) {
+        if (e instanceof OrchestrationError)
+            throw e; // no_plan / empty_plan surface as-is
+        throw new OrchestrationError('planner_failed', e instanceof Error ? e.message : String(e));
+    }
+}
+/**
+ * Run an intent to a terminal result. Plans, executes the steps in order (threading `ref` results into later
+ * args), observes, and re-plans (bounded) when a step throws. Returns `completed` with the last successful
+ * step's result, or `failed` with the error. Fail-closed throughout: an unknown tool, an empty plan, no plan,
+ * or an exhausted step budget all produce a `failed` RunResult (never a misleading empty success).
+ */
+export async function runIntent(intent, opts) {
+    const maxSteps = opts.maxSteps ?? 8;
+    const maxReplans = opts.maxReplans ?? 1;
+    const toolIds = new Set(opts.tools.map((t) => t.id));
+    const allObservations = [];
+    const refs = {};
+    let executed = 0;
+    let replans = 0;
+    let lastResult;
+    try {
+        let plan = await callPlanner(opts.planner, { intent, tools: opts.tools });
+        assertKnownTools(plan, toolIds);
+        // The plan loop: walk the current plan; on a step failure, re-plan (bounded) and restart with a fresh plan.
+        for (;;) {
+            let failedMidPlan = false;
+            for (let i = 0; i < plan.steps.length; i++) {
+                if (executed >= maxSteps)
+                    throw new OrchestrationError('max_steps', `step budget of ${maxSteps} exhausted`);
+                const step = plan.steps[i];
+                const ctx = { intent, step, index: i };
+                const args = resolveArgs(step.args, refs);
+                executed++;
+                let obs;
+                try {
+                    const result = await opts.invoke(step.toolId, args, ctx);
+                    obs = { step, ok: true, result };
+                    if (step.ref)
+                        refs[step.ref] = result;
+                    lastResult = result;
+                }
+                catch (e) {
+                    obs = { step, ok: false, error: e instanceof Error ? e.message : String(e) };
+                }
+                allObservations.push(obs);
+                opts.onObserve?.(obs);
+                if (!obs.ok) {
+                    failedMidPlan = true;
+                    break; // stop this plan; decide whether to re-plan below
+                }
+            }
+            if (!failedMidPlan) {
+                return { outcome: 'completed', plan, steps: allObservations, result: lastResult };
+            }
+            if (replans >= maxReplans) {
+                const last = allObservations[allObservations.length - 1];
+                return { outcome: 'failed', plan, steps: allObservations, error: last?.error ?? 'step failed' };
+            }
+            replans++;
+            plan = await callPlanner(opts.planner, { intent, tools: opts.tools, observations: allObservations });
+            assertKnownTools(plan, toolIds);
+        }
+    }
+    catch (e) {
+        const error = e instanceof OrchestrationError ? `${e.code}: ${e.message}` : e instanceof Error ? e.message : String(e);
+        // No plan was ever produced if allObservations is empty + we threw before the loop.
+        return { outcome: 'failed', plan: { steps: [] }, steps: allObservations, error };
+    }
+}
+//# sourceMappingURL=loop.js.map

package/dist/loop.js.map

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

package/dist/planner.d.ts

@@ -0,0 +1,35 @@
+import type { Intent, Plan, PlanStep, ToolSpec, StepObservation } from './types.js';
+/** What a planner is given to produce (or re-produce) a plan. */
+export interface PlanInput {
+    intent: Intent;
+    /** The tools the agent exposes — the planner MUST pick from these (fail-closed elsewhere). */
+    tools: ToolSpec[];
+    /** Prior step observations, present only on a re-plan (empty / undefined on the first plan). */
+    observations?: StepObservation[];
+}
+/** The injected planning port: turn a goal + the available tools into an ordered tool composition. */
+export interface Planner {
+    plan(input: PlanInput): Promise<Plan>;
+}
+/** One deterministic rule. When the goal matches, emit either a single step (`toolId` + `args`) OR a
+ *  multi-step plan (`steps`) — later steps may reference earlier results via `{ $ref: 'name.path' }`. A rule
+ *  is SKIPPED if any tool it names is not in the provided `tools` (fail-closed; the next rule is tried). */
+export interface PlanRule {
+    /** Regex tested against the lowercased goal, or a predicate over the raw goal. */
+    match: RegExp | ((goal: string) => boolean);
+    /** Single-step: the tool to invoke. Provide this OR `steps`. */
+    toolId?: string;
+    /** Static args, or a function of the raw goal. Defaults to `{}`. (Single-step only.) */
+    args?: Record<string, unknown> | ((goal: string) => Record<string, unknown>);
+    /** Optional ref name to bind the (single) step's result under. (Single-step only.) */
+    ref?: string;
+    /** Multi-step: an explicit ordered plan, or a function of the raw goal. Provide this OR `toolId`. */
+    steps?: PlanStep[] | ((goal: string) => PlanStep[]);
+}
+/**
+ * The deterministic default planner: maps a goal to a single-tool plan via the FIRST matching rule whose
+ * `toolId` is actually exposed in `tools`. No model, no creds, fully testable — the live default. Throws
+ * `OrchestrationError('no_plan')` when nothing matches (fail-closed; never an empty silent success).
+ */
+export declare function createRuleBasedPlanner(rules: PlanRule[]): Planner;
+//# sourceMappingURL=planner.d.ts.map

package/dist/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../src/planner.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGpF,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,gGAAgG;IAChG,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;CAClC;AAED,sGAAsG;AACtG,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED;;4GAE4G;AAC5G,MAAM,WAAW,QAAQ;IACvB,kFAAkF;IAClF,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;IAC5C,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7E,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qGAAqG;IACrG,KAAK,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,EAAE,CAAC,CAAC;CACrD;AAKD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAqBjE"}

package/dist/planner.js

@@ -0,0 +1,33 @@
+import { OrchestrationError } from './types.js';
+const matches = (rule, goal) => typeof rule.match === 'function' ? rule.match(goal) : rule.match.test(goal.toLowerCase());
+/**
+ * The deterministic default planner: maps a goal to a single-tool plan via the FIRST matching rule whose
+ * `toolId` is actually exposed in `tools`. No model, no creds, fully testable — the live default. Throws
+ * `OrchestrationError('no_plan')` when nothing matches (fail-closed; never an empty silent success).
+ */
+export function createRuleBasedPlanner(rules) {
+    return {
+        async plan({ intent, tools }) {
+            const available = new Set(tools.map((t) => t.id));
+            for (const rule of rules) {
+                if (!matches(rule, intent.goal))
+                    continue;
+                // Multi-step rule: emit the full template (skip the rule if any tool isn't exposed).
+                if (rule.steps) {
+                    const steps = typeof rule.steps === 'function' ? rule.steps(intent.goal) : rule.steps;
+                    if (!steps.every((s) => available.has(s.toolId)))
+                        continue;
+                    return { steps, rationale: `rule-based: matched "${intent.goal}" → ${steps.map((s) => s.toolId).join(' + ')}` };
+                }
+                // Single-step rule.
+                if (!rule.toolId || !available.has(rule.toolId))
+                    continue; // unset or unexposed tool — skip
+                const args = typeof rule.args === 'function' ? rule.args(intent.goal) : (rule.args ?? {});
+                const step = rule.ref ? { toolId: rule.toolId, args, ref: rule.ref } : { toolId: rule.toolId, args };
+                return { steps: [step], rationale: `rule-based: matched "${intent.goal}" → ${rule.toolId}` };
+            }
+            throw new OrchestrationError('no_plan', `no rule satisfies the goal: "${intent.goal}"`);
+        },
+    };
+}
+//# sourceMappingURL=planner.js.map

package/dist/planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.js","sourceRoot":"","sources":["../src/planner.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgChD,MAAM,OAAO,GAAG,CAAC,IAAc,EAAE,IAAY,EAAW,EAAE,CACxD,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAE5F;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAiB;IACtD,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAa;YACrC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAClD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC;oBAAE,SAAS;gBAC1C,qFAAqF;gBACrF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;oBACf,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;oBACtF,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;wBAAE,SAAS;oBAC3D,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,wBAAwB,MAAM,CAAC,IAAI,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;gBAClH,CAAC;gBACD,oBAAoB;gBACpB,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;oBAAE,SAAS,CAAC,iCAAiC;gBAC5F,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;gBAC1F,MAAM,IAAI,GAAa,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;gBAC/G,OAAO,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,wBAAwB,MAAM,CAAC,IAAI,OAAO,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/F,CAAC;YACD,MAAM,IAAI,kBAAkB,CAAC,SAAS,EAAE,gCAAgC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;QAC1F,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tool-invoker.d.ts

@@ -0,0 +1,15 @@
+import type { Intent, PlanStep } from './types.js';
+/** Context handed to the invoker for one step (for logging / args resolution; never authority). */
+export interface InvokeContext {
+    intent: Intent;
+    step: PlanStep;
+    /** 0-based index of this step within the current plan. */
+    index: number;
+}
+/**
+ * Execute a single tool. Resolve with the tool's result, or REJECT to signal a step failure (the loop then
+ * re-plans, bounded). A resolved value is treated as success — an invoker that wants to surface a tool-level
+ * error as a failure must throw (fail-closed; the loop does not inspect result shapes for hidden errors).
+ */
+export type ToolInvoker = (toolId: string, args: Record<string, unknown>, ctx: InvokeContext) => Promise<unknown>;
+//# sourceMappingURL=tool-invoker.d.ts.map

package/dist/tool-invoker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-invoker.d.ts","sourceRoot":"","sources":["../src/tool-invoker.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEnD,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,OAAO,CAAC,CAAC"}

package/dist/tool-invoker.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-invoker.js.map

package/dist/tool-invoker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-invoker.js","sourceRoot":"","sources":["../src/tool-invoker.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+export declare const PACKAGE_NAME: "@agenticprimitives/orchestration";
+export declare const PACKAGE_STATUS: "w1-core";
+export declare const SPEC_REF: "packages/orchestration/spec.md";
+/** A declarative goal posted by a first-party surface. NOT a tool name, payload, or call sequence. */
+export interface Intent {
+    /** The natural-language / declarative objective, e.g. "read my profile". */
+    goal: string;
+    /** Optional hard constraints the planner must respect (budget, deadline, scope). Opaque to the loop. */
+    constraints?: Record<string, unknown>;
+    /** Optional context the planner may use (principal handle, locale…). Opaque to the loop. */
+    context?: Record<string, unknown>;
+}
+/** A capability the agent MAY compose. The planner picks from these; the loop refuses any other tool id. */
+export interface ToolSpec {
+    /** Stable tool id (matches the invoker's dispatch key, e.g. an MCP tool name). */
+    id: string;
+    /** Human/LLM-readable description — what the tool does + when to use it. Untrusted-by-client (SEP). */
+    description: string;
+    /** Optional JSON-Schema for the tool's args (the LLM planner uses it as the tool-use input schema). */
+    inputSchema?: Record<string, unknown>;
+}
+/** One step of a plan: invoke `toolId` with `args`; optionally bind the result under `ref` for later steps. */
+export interface PlanStep {
+    toolId: string;
+    args: Record<string, unknown>;
+    /** Name to store this step's result under; later steps reference it via `{ $ref: name }` in their args. */
+    ref?: string;
+}
+/** The ordered tool composition the planner produced for an intent. */
+export interface Plan {
+    steps: PlanStep[];
+    /** Optional one-line reasoning (audit/telemetry only — never trusted as authority). */
+    rationale?: string;
+}
+/** The recorded outcome of one executed step (fed back into a re-plan). */
+export interface StepObservation {
+    step: PlanStep;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+export type RunOutcome = 'completed' | 'failed';
+/** The result of running an intent to completion (or fail-closed). */
+export interface RunResult {
+    outcome: RunOutcome;
+    /** The final plan that was executed (the last re-plan, if any). */
+    plan: Plan;
+    /** Every step observation, in execution order, across all (re-)plans. */
+    steps: StepObservation[];
+    /** The last successful step's result — the composed answer returned to the caller. */
+    result?: unknown;
+    /** Set when `outcome === 'failed'`. */
+    error?: string;
+}
+/** Stable error codes the loop / planners raise (fail-closed; never a silent empty success). */
+export type OrchestrationErrorCode = 'no_plan' | 'unknown_tool' | 'empty_plan' | 'max_steps' | 'planner_failed';
+export declare class OrchestrationError extends Error {
+    readonly code: OrchestrationErrorCode;
+    constructor(code: OrchestrationErrorCode, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,YAAY,EAAG,kCAA2C,CAAC;AACxE,eAAO,MAAM,cAAc,EAAG,SAAkB,CAAC;AACjD,eAAO,MAAM,QAAQ,EAAG,gCAAyC,CAAC;AAElE,sGAAsG;AACtG,MAAM,WAAW,MAAM;IACrB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,4GAA4G;AAC5G,MAAM,WAAW,QAAQ;IACvB,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,uGAAuG;IACvG,WAAW,EAAE,MAAM,CAAC;IACpB,uGAAuG;IACvG,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,+GAA+G;AAC/G,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,2GAA2G;IAC3G,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,uEAAuE;AACvE,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEhD,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,UAAU,CAAC;IACpB,mEAAmE;IACnE,IAAI,EAAE,IAAI,CAAC;IACX,yEAAyE;IACzE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,sFAAsF;IACtF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gGAAgG;AAChG,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,cAAc,GACd,YAAY,GACZ,WAAW,GACX,gBAAgB,CAAC;AAErB,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,IAAI,EAAE,sBAAsB;gBAA5B,IAAI,EAAE,sBAAsB,EAC5C,OAAO,EAAE,MAAM;CAKlB"}

package/dist/types.js

@@ -0,0 +1,19 @@
+// @agenticprimitives/orchestration — the intent→plan→execute→observe model (the Ring-0 agentic loop).
+//
+// This is a PURE leaf: the model, the ports, and the loop only. No transport (a2a), no LLM SDK
+// (orchestration-anthropic), no chain reads. A first-party app expresses an `Intent` (a GOAL, never a tool
+// name); a `Planner` decides which `ToolSpec`s compose to satisfy it; the loop executes the resulting `Plan`
+// through an injected `ToolInvoker`, observes, and re-plans (bounded) on failure. The concrete tools are MCP
+// tools the a2a agent exposes — composed AS PRIMITIVES (ADR-0044). The web never names a tool; the agent does.
+export const PACKAGE_NAME = '@agenticprimitives/orchestration';
+export const PACKAGE_STATUS = 'w1-core';
+export const SPEC_REF = 'packages/orchestration/spec.md';
+export class OrchestrationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OrchestrationError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,EAAE;AACF,+FAA+F;AAC/F,2GAA2G;AAC3G,6GAA6G;AAC7G,6GAA6G;AAC7G,+GAA+G;AAE/G,MAAM,CAAC,MAAM,YAAY,GAAG,kCAA2C,CAAC;AACxE,MAAM,CAAC,MAAM,cAAc,GAAG,SAAkB,CAAC;AACjD,MAAM,CAAC,MAAM,QAAQ,GAAG,gCAAyC,CAAC;AAoElE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEzB;IADlB,YACkB,IAA4B,EAC5C,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAwB;QAI5C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@agenticprimitives/orchestration",
+  "version": "0.0.0-alpha.1",
+  "description": "The Ring-0 agentic orchestration core (ADR-0044): the intent→plan→execute→observe loop, the Planner + ToolInvoker ports, and a deterministic rule-based planner. A first-party app expresses a goal; the loop plans which tools compose to satisfy it and runs them through an injected invoker. Pure leaf — no transport, no LLM SDK, no chain; the concrete LLM binding lives behind the Planner port in orchestration-anthropic.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentictrustlabs/agenticprimitives.git",
+    "directory": "packages/orchestration"
+  },
+  "homepage": "https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/orchestration",
+  "bugs": {
+    "url": "https://github.com/agentictrustlabs/agenticprimitives/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "spec.md",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
+  "keywords": [
+    "agentic",
+    "primitives",
+    "orchestration",
+    "planner",
+    "intent",
+    "agentic-loop"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}

package/spec.md

@@ -0,0 +1,53 @@
+# orchestration — the Ring-0 agentic loop
+
+**Status:** w1-core. **Doctrine:** [ADR-0044](../../docs/architecture/decisions/0044-a2a-is-the-agentic-orchestration-layer.md)
++ [docs/architecture/principles.md](../../docs/architecture/principles.md) §1 + memory `feedback_orchestration_is_ring0`.
+
+## 1. Why
+
+The doctrine: a first-party UI expresses a declarative **intent** (a goal) to an a2a agent, which **plans**
+which capability satisfies it and **composes tools as primitives** — `web → edge → /api/a2a → a2a skills →
+MCP`. The web never names a tool. **Orchestration — the intent→plan→execute→observe loop, the Planner PORT,
+and the tool model — is a Ring-0 primitive** in a pure package; ONLY the concrete LLM binding is an in-repo
+adapter behind the port (the `chain-state` / `chain-state-viem` pattern). This package is that core.
+
+## 2. The model
+
+- `Intent { goal; constraints?; context? }` — a GOAL, never a tool name / payload / call sequence.
+- `ToolSpec { id; description; inputSchema? }` — a capability the agent MAY compose (an MCP tool, typically).
+- `Plan { steps: PlanStep[]; rationale? }`, `PlanStep { toolId; args; ref? }` — the ordered composition.
+- `StepObservation { step; ok; result?; error? }` — fed back into a re-plan.
+- `RunResult { outcome: 'completed'|'failed'; plan; steps; result?; error? }`.
+
+## 3. The ports (injected)
+
+- `Planner { plan({ intent, tools, observations? }): Promise<Plan> }` — turns a goal + the exposed tools into
+  a plan. The deterministic `createRuleBasedPlanner(rules)` is the default; the LLM adapter implements the SAME
+  port. A planner MUST pick only from the provided `tools`.
+- `ToolInvoker (toolId, args, ctx): Promise<unknown>` — executes one step. The a2a `orchestrate` skill binds it
+  to `ctx.mcp.callTool` under the **task's delegation**, so every composed call rides on-chain authority.
+
+## 4. The loop — `runIntent(intent, opts)`
+
+1. Plan with `{ intent, tools }`. Fail-closed: a plan that names an unexposed tool → `unknown_tool`; a
+   zero-step plan → `empty_plan`; the planner producing nothing → `no_plan`.
+2. Execute steps in order. Resolve `{ $ref: 'name' }` args from prior step results. Bind a step's result under
+   `step.ref` for later steps. Cap total executions at `maxSteps` (default 8).
+3. On a step throw: record the failed observation and **re-plan** (passing all observations), bounded by
+   `maxReplans` (default 1). Exhausted → `failed` with the last error.
+4. All steps succeed → `completed` with the last successful result.
+
+Fail-closed everywhere (ADR-0013): no plan / empty plan / unknown tool / exhausted budget all return a `failed`
+`RunResult` — never a misleading empty success.
+
+## 5. Boundaries
+
+Pure leaf (only `@agenticprimitives/types` allowed, currently unused). No transport, no LLM SDK, no chain. The
+LLM binding is `@agenticprimitives/orchestration-anthropic`. `service-agent` is the deterministic compile/run
+target; this core PRODUCES plans and is a separate concern (not folded in).
+
+## 6. Out of scope (this wave)
+
+Multi-tool graph reasoning beyond linear steps + `$ref` threading; parallel step execution; service-agent as
+the executor; planner-side cost/latency optimization. W1 = linear plans + bounded re-plan, deterministic + LLM
+planners behind one port.