@backendkit-labs/agent-core 0.42.0 → 0.44.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +60 -1
  2. package/dist/flow/adapter.d.ts +20 -0
  3. package/dist/flow/adapter.d.ts.map +1 -0
  4. package/dist/flow/adapter.js +81 -0
  5. package/dist/flow/adapter.js.map +1 -0
  6. package/dist/flow/approval-handler.d.ts +59 -0
  7. package/dist/flow/approval-handler.d.ts.map +1 -0
  8. package/dist/flow/approval-handler.js +79 -0
  9. package/dist/flow/approval-handler.js.map +1 -0
  10. package/dist/flow/approval.d.ts +39 -0
  11. package/dist/flow/approval.d.ts.map +1 -0
  12. package/dist/flow/approval.js +58 -0
  13. package/dist/flow/approval.js.map +1 -0
  14. package/dist/flow/condition.d.ts +6 -0
  15. package/dist/flow/condition.d.ts.map +1 -0
  16. package/dist/flow/condition.js +30 -0
  17. package/dist/flow/condition.js.map +1 -0
  18. package/dist/flow/convert.d.ts +44 -0
  19. package/dist/flow/convert.d.ts.map +1 -0
  20. package/dist/flow/convert.js +34 -0
  21. package/dist/flow/convert.js.map +1 -0
  22. package/dist/flow/file-journal.d.ts +34 -0
  23. package/dist/flow/file-journal.d.ts.map +1 -0
  24. package/dist/flow/file-journal.js +176 -0
  25. package/dist/flow/file-journal.js.map +1 -0
  26. package/dist/flow/handler.d.ts +35 -0
  27. package/dist/flow/handler.d.ts.map +1 -0
  28. package/dist/flow/handler.js +51 -0
  29. package/dist/flow/handler.js.map +1 -0
  30. package/dist/flow/host.d.ts +79 -0
  31. package/dist/flow/host.d.ts.map +1 -0
  32. package/dist/flow/host.js +148 -0
  33. package/dist/flow/host.js.map +1 -0
  34. package/dist/flow/index.d.ts +27 -0
  35. package/dist/flow/index.d.ts.map +1 -0
  36. package/dist/flow/index.js +55 -0
  37. package/dist/flow/index.js.map +1 -0
  38. package/dist/flow/interpolate.d.ts +6 -0
  39. package/dist/flow/interpolate.d.ts.map +1 -0
  40. package/dist/flow/interpolate.js +18 -0
  41. package/dist/flow/interpolate.js.map +1 -0
  42. package/dist/flow/journal.d.ts +105 -0
  43. package/dist/flow/journal.d.ts.map +1 -0
  44. package/dist/flow/journal.js +89 -0
  45. package/dist/flow/journal.js.map +1 -0
  46. package/dist/flow/limiter.d.ts +21 -0
  47. package/dist/flow/limiter.d.ts.map +1 -0
  48. package/dist/flow/limiter.js +45 -0
  49. package/dist/flow/limiter.js.map +1 -0
  50. package/dist/flow/loader.d.ts +24 -0
  51. package/dist/flow/loader.d.ts.map +1 -0
  52. package/dist/flow/loader.js +185 -0
  53. package/dist/flow/loader.js.map +1 -0
  54. package/dist/flow/planner.d.ts +50 -0
  55. package/dist/flow/planner.d.ts.map +1 -0
  56. package/dist/flow/planner.js +131 -0
  57. package/dist/flow/planner.js.map +1 -0
  58. package/dist/flow/run.d.ts +115 -0
  59. package/dist/flow/run.d.ts.map +1 -0
  60. package/dist/flow/run.js +417 -0
  61. package/dist/flow/run.js.map +1 -0
  62. package/dist/flow/tools.d.ts +27 -0
  63. package/dist/flow/tools.d.ts.map +1 -0
  64. package/dist/flow/tools.js +71 -0
  65. package/dist/flow/tools.js.map +1 -0
  66. package/dist/flow/types.d.ts +139 -0
  67. package/dist/flow/types.d.ts.map +1 -0
  68. package/dist/flow/types.js +80 -0
  69. package/dist/flow/types.js.map +1 -0
  70. package/dist/index.d.ts +17 -1
  71. package/dist/index.d.ts.map +1 -1
  72. package/dist/index.js +46 -2
  73. package/dist/index.js.map +1 -1
  74. package/dist/learning/index.d.ts +1 -1
  75. package/dist/learning/index.d.ts.map +1 -1
  76. package/dist/learning/index.js +104 -42
  77. package/dist/learning/index.js.map +1 -1
  78. package/dist/learning/signal.d.ts +32 -14
  79. package/dist/learning/signal.d.ts.map +1 -1
  80. package/dist/learning/signal.js +95 -30
  81. package/dist/learning/signal.js.map +1 -1
  82. package/dist/learning/types.d.ts +60 -0
  83. package/dist/learning/types.d.ts.map +1 -1
  84. package/package.json +6 -1
package/README.md CHANGED
@@ -19,6 +19,7 @@ The foundation engine for the BackendKit Labs agent framework. Provides everythi
19
19
  - [MCP client](#mcp-client)
20
20
  - [MCP tool server (tools without a model)](#mcp-tool-server-tools-without-a-model)
21
21
  - [Workflow engine](#workflow-engine)
22
+ - [Flows — declarative and durable](#flows--declarative-and-durable)
22
23
  - [Advanced memory system](#advanced-memory-system)
23
24
  - [Observability](#observability)
24
25
  - [Skills and slash commands](#skills-and-slash-commands)
@@ -775,6 +776,63 @@ const result = await runner.run(myWorkflow, {
775
776
 
776
777
  ---
777
778
 
779
+ ## Flows — declarative and durable
780
+
781
+ A business flow is data: a YAML file with steps, dependencies, approvals and compensations. `runFlow` executes it; **how** a step runs is the `StepExecutor` you pass (one agent, a remote worker, a queue). Adding a flow for a company means writing YAML, not platform code. A runnable example lives in [`examples/flows`](../../examples/flows).
782
+
783
+ ```yaml
784
+ flow: close-month
785
+ trigger: { type: manual }
786
+ steps:
787
+ - id: collect-sales # no `after`: runs in parallel with collect-costs
788
+ agent: sales
789
+ prompt: "Collect the sales of {{payload.month}}"
790
+ - id: collect-costs
791
+ agent: finance
792
+ prompt: "Collect the costs of {{payload.month}}"
793
+ timeoutMs: 60000
794
+ - id: report
795
+ agent: analyst
796
+ prompt: "Write the month report"
797
+ after: [collect-sales, collect-costs]
798
+ gate: { approval: human } # stops until a person decides
799
+ - id: publish
800
+ agent: comms
801
+ prompt: "Send the report to the board"
802
+ after: [report]
803
+ when: { step: report, contains: "APPROVED" } # runs only if the report says so; otherwise skipped
804
+ compensation:
805
+ - on: report.failed
806
+ agent: comms
807
+ prompt: "Tell the board the report is delayed"
808
+ ```
809
+
810
+ ```typescript
811
+ import { loadFlow, runFlow, FileRunJournal, MemoryApprovalStore } from '@backendkit-labs/agent-core';
812
+
813
+ const flow = await loadFlow('flows/close-month.yaml'); // parseFlow(yaml), loadFlowsFromDir(dir), validateFlow(def)
814
+ const result = await runFlow(flow, {
815
+ executor: { run: async (step, input) => ({ content: await myAgent(step.agent).run(input.prompt) }) },
816
+ payload: { month: '2026-10' }, // {{payload.x}} in prompts
817
+ journal: new FileRunJournal('.flows'), // durable: survives the process
818
+ approvals: { store: new MemoryApprovalStore() }, // gate.approval: human (or a policy `ask`)
819
+ runId: 'close-2026-10',
820
+ maxConcurrency: 8, // per wave; `limiter` caps per agent/tenant across flows
821
+ });
822
+ result.status; // 'completed' | 'failed' | 'rejected' | 'cancelled' | 'awaiting_approval'
823
+ result.costUsd; // sum of the costUsd the steps reported (absent if none did)
824
+ ```
825
+
826
+ - **Conditional steps (0.44.0):** `when: { step, contains | equals | matches, not? }` runs a step only if the output of a step it waits for says so (`step` must be in `after`; `equals` ignores surrounding whitespace). A step whose condition does not hold, or cannot be evaluated because that step produced no output, is `skipped` before anything else: it does not run, **no approval is asked**, what waits for it is skipped too, and the flow does **not** fail. The skip is in `transitions` with the reason (`condition not met: report contains "APPROVED"`).
827
+ - **Waves and failure:** steps whose `after` are done run together. A failed step skips what depends on it (`onStepFailure: 'continue'` runs them without its output), then the `compensation` entries run. `timeoutMs` per step, `stepTimeoutMs` as a default.
828
+ - **Durable and resumable:** with a `journal` each step is written before and after it runs, one process holds the run (`claim`), and calling `runFlow` again with the same `runId` **resumes**: `done` steps are not run again. The claim is **renewed while the run lives** (every `claimRenewMs`, a third of `claimTtlMs` by default), so a run longer than the TTL is not taken over by another process; it expires only when this process stops. If a renewal finds the claim taken, the run stops and `runFlow` throws `FlowClaimError` without writing over the new owner (`claimRenewMs: 0` turns renewal off). A step the journal shows as `running` (the process died) runs again by default — at least once; `input.idempotencyKey` (`runId:stepId:attempt`) lets a step with an external effect be safe. `MemoryRunJournal`, `FileRunJournal` (atomic across processes) and `RedisRunJournal` (in [`agent-flow-queue`](../flow-queue)) share one contract. The payload is not stored: pass it again when resuming.
829
+ - **Approval:** `gate.approval: human` or a `policy` that answers `ask` for `flow.step:<id>` stops the run as `awaiting_approval`; decide it and run again with the same `runId`. `when: 'after'` runs the step first and shows its output to the approver.
830
+ - **Plan with a model:** `planFlow(task, { agents, provider })` turns a task into a validated `FlowDefinition` (unknown agents, cycles and duplicate ids are rejected and the model is asked again); steps no agent covers come back in `unresolved`. A plan a model writes and a YAML file are the same object. `flowFromTaskPlan` and `flowFromStaticFlow` convert older shapes.
831
+ - **Serve and steer it:** `flowFromDefinition(def, opts)` + `createFlowHandler({ name: flow })` give the `flowHandler` an `AgentServer` takes (start, status, pause, resume, cancel). `createApprovalHandler(store)` gives the `approvalHandler` (list, get, decide). `createFlowTools({ flows, approvals, approver })` exposes both as tools for a model or an MCP server; `flow_cancel` and `approval_decide` are `destructive`, so the tool server needs an `authorize` or a `policy`, and a model-driven server should use `approver: { kind: 'service', id }` (it cannot satisfy an approval that needs a human).
832
+ - **Across processes:** [`@backendkit-labs/agent-flow-queue`](../flow-queue) provides a BullMQ `StepExecutor` (each step runs on a worker) and a Redis journal.
833
+
834
+ ---
835
+
778
836
  ## Advanced memory system
779
837
 
780
838
  Beyond session history, agents can use a three-layer persistent memory. Each layer is independently configurable and backed by a pluggable store.
@@ -1132,7 +1190,8 @@ await learning.retire(id); // withdraw an appro
1132
1190
  ```
1133
1191
 
1134
1192
  - **What the `learning` option wires.** Every failed, timed-out, denied or blocked tool call becomes an experience. The lessons of each agent, sanitized and capped, join its system prompt. The rules a person approved (`{ tool, effect: 'ask' | 'deny' }`) are enforced only when the engine is on the policy path (`policy`, `approver` or `approvals` is set): `learning` alone never changes how the engine asks for approval. `learning.sink`, `learning.hooks` and `learning.policy` remain available to wire by hand.
1135
- - **What makes a pattern.** The same failure (tool, kind and, when the tool's error has one, its code: `ECONNRESET` and `ERP_PERIOD_CLOSED` are different patterns) seen `threshold` times **inside the window** (`window: { days: 30 }`). Correct calls are counted, not stored, so a tool with many calls also needs the failures to be a share of them (`rate`, default 5% from 20 calls): 3 failures in 1000 calls are noise, 3 in 5 are not. The share is that of the **subject**: to judge a context on its own, put it in the subject (`breakout/trend_flat` and `breakout/trend_up` are judged separately; `breakout` judges both together). The share decides when a pattern **enters**; once in, it stays while its failures stay in the window, so a lesson that works (and fills its subject with correct calls) does not remove itself. `rate: false` counts failures only. `learning.flush()` writes the counters now; they are also written after each turn.
1193
+ - **What makes a pattern.** The same failure (tool, kind and, when the tool's error has one, its code: `ECONNRESET` and `ERP_PERIOD_CLOSED` are different patterns) seen `threshold` times **inside the window** (`window: { days: 30 }`). Correct calls are counted, not stored, so a tool with many calls also needs the failures to be a share of them (`rate`, default 5% from 20 calls): 3 failures in 1000 calls are noise, 3 in 5 are not. The share is that of the **subject**: to judge a context on its own, put it in the subject (`breakout/trend_flat` and `breakout/trend_up` are judged separately; `breakout` judges both together). The share decides when a pattern **enters**; once in, it stays, so a lesson that works (and fills its subject with correct calls) does not remove itself. `rate: false` counts failures only. `learning.flush()` writes the counters now; they are also written after each turn.
1194
+ - **How long a lesson lives.** Each pattern has a record (`learning.records()`): its state, its line and its dates. A learned lesson **stays while its subject is still being called**: when the agent obeys it, the failures leave the window, and a lesson that left with them would let the mistake come back. It leaves when the subject has had no calls and no failures for `quietAfterDays` (default: the window), or when a person resolves it: `learning.resolve(patternKey, by, { tenantId?, reason? })`, only for who `approverKinds` allows. A resolved pattern that fails again afterwards is active again and its record says it came back (`reappeared`). A pattern without a subject (a signal of a vertical, with no calls to count) leaves with its window. The line of a lesson is written once, in its record: a later failure, a hint registered afterwards or a restart do not rewrite it, so the system prompt stays the same; a hint its author improves later reaches the patterns that appear after that. The trade-off: a tool that failed three times because of an outage keeps its lesson while it is called, until someone resolves it. The proposal of a rule shows its evidence: `3 x tool_error on place_order (3 of 10 calls, 30%), first to last`.
1136
1195
  - **Lessons come in units.** The lessons of an agent are grouped by tool (`### post_invoice`), with `general` first; inside a unit, what a person taught goes before what was learned, and `lessons.maxPerUnit` caps the learned ones. `lessons.maxPerUnit` and `lessons.maxLessons` keep the learned lessons that happen most. The text is cut by dropping whole entries from the end, learned ones first and what a person taught only when nothing learned is left, so the same lessons always give the same system prompt.
1137
1196
  - **The advice comes from whoever knows the domain.** A tool declares what to do about each error code: `defineTool({ ..., errorHints: { ERP_PERIOD_CLOSED: 'The period is closed: post it in the next open one.', '*': 'Check the invoice first.' } })`. When that error repeats, the lesson says it. It is only about the errors the tool raises: for the failures the engine sees by itself (a denial, a timeout, a result that was too large) it says one fixed sentence (`ENGINE_HINTS`). Nothing generic is invented for the rest: the lesson states the fact.
1138
1197
  - **A unit a person can write and review in git.** `await learning.exportUnit('post_invoice')` gives markdown with a front matter, the `## Taught` lessons (the part an import reads) and the `## Learned` ones (generated: ignored on import). `await learning.importUnit(md, by)` teaches the taught ones; the file is imported whole or not at all, importing it twice changes nothing (a lesson that did not change keeps its place and its first author), and `{ replace: true }` forgets the ones that left the file. **The front matter decides which tenant gets the lessons**: a product with tenants passes `{ tenantId }` to say it itself. `learning.units()` lists the units.
@@ -0,0 +1,20 @@
1
+ import type { FlowDefinition } from './types';
2
+ import type { InProcessFlow, FlowRunView } from './host';
3
+ import type { JournalRun } from './journal';
4
+ import type { RunFlowOptions } from './run';
5
+ /**
6
+ * Hosts a `FlowDefinition` in a `FlowHost` (SPEC-0023 F4): a supervisor (Hermes) then starts, watches, pauses, resumes and
7
+ * cancels it through the protocol without knowing it is a core flow. The input of `start` is the flow payload. Pausing
8
+ * holds the steps not yet started; cancelling aborts the ones running and starts no more.
9
+ */
10
+ export declare function flowFromDefinition(def: FlowDefinition, opts: Omit<RunFlowOptions, 'payload' | 'signal' | 'checkpoint' | 'onTransition'>): InProcessFlow;
11
+ /**
12
+ * Projects a journal record to the `FlowRunState` vocabulary of the protocol (SPEC-0023 §4.1). For a supervisor that speaks 1.1
13
+ * (`protocolMinor` below 2, the default) `awaiting_approval` shows as `paused` and `lost` as `failed`, with the reason in
14
+ * `detail`/`error`; from 1.2 on they are sent as they are, and so are the step states `awaiting_approval` and `interrupted`.
15
+ * `stepOrder` (the flow's step ids) gives the steps their declared order.
16
+ */
17
+ export declare function flowRunView(run: JournalRun, stepOrder?: string[], options?: {
18
+ protocolMinor?: number;
19
+ }): FlowRunView;
20
+ //# sourceMappingURL=adapter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/flow/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAA4B,MAAM,QAAQ,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,cAAc,CAAC,GAAG,aAAa,CA2BvJ;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,WAAW,CAyBxH"}
@@ -0,0 +1,81 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.flowFromDefinition = flowFromDefinition;
4
+ exports.flowRunView = flowRunView;
5
+ const run_1 = require("./run");
6
+ /**
7
+ * Hosts a `FlowDefinition` in a `FlowHost` (SPEC-0023 F4): a supervisor (Hermes) then starts, watches, pauses, resumes and
8
+ * cancels it through the protocol without knowing it is a core flow. The input of `start` is the flow payload. Pausing
9
+ * holds the steps not yet started; cancelling aborts the ones running and starts no more.
10
+ */
11
+ function flowFromDefinition(def, opts) {
12
+ return {
13
+ steps: def.steps.map(s => s.id),
14
+ run: async (input, control) => {
15
+ const result = await (0, run_1.runFlow)(def, {
16
+ ...opts,
17
+ payload: input,
18
+ signal: control.signal,
19
+ checkpoint: control.checkpoint,
20
+ onTransition: t => {
21
+ if (t.stepId.includes(':compensation'))
22
+ return;
23
+ if (t.event === 'started')
24
+ control.mark(t.stepId, 'running');
25
+ else if (t.event === 'completed')
26
+ control.mark(t.stepId, 'done');
27
+ else if (t.event === 'failed')
28
+ control.mark(t.stepId, 'failed', t.detail);
29
+ else if (t.event === 'skipped')
30
+ control.mark(t.stepId, 'skipped');
31
+ else if (t.event === 'rejected')
32
+ control.mark(t.stepId, 'failed', 'rejected');
33
+ },
34
+ });
35
+ if (result.status === 'cancelled')
36
+ return undefined; // the host already reports it as cancelled
37
+ if (result.status !== 'completed') {
38
+ const bad = Object.values(result.steps).find(s => s.status === 'failed' || s.status === 'rejected');
39
+ throw new Error(bad ? `step "${bad.stepId}" ${bad.status}${bad.error ? `: ${bad.error}` : ''}` : `flow ${result.status}`);
40
+ }
41
+ const last = def.steps[def.steps.length - 1];
42
+ return result.steps[last.id]?.content ?? '';
43
+ },
44
+ };
45
+ }
46
+ /**
47
+ * Projects a journal record to the `FlowRunState` vocabulary of the protocol (SPEC-0023 §4.1). For a supervisor that speaks 1.1
48
+ * (`protocolMinor` below 2, the default) `awaiting_approval` shows as `paused` and `lost` as `failed`, with the reason in
49
+ * `detail`/`error`; from 1.2 on they are sent as they are, and so are the step states `awaiting_approval` and `interrupted`.
50
+ * `stepOrder` (the flow's step ids) gives the steps their declared order.
51
+ */
52
+ function flowRunView(run, stepOrder, options = {}) {
53
+ const native = (options.protocolMinor ?? 1) >= 2;
54
+ const status = native ? run.status
55
+ : run.status === 'awaiting_approval' ? 'paused' : run.status === 'lost' ? 'failed' : run.status;
56
+ const ids = [...new Set([...(stepOrder ?? []), ...Object.keys(run.steps)])];
57
+ const steps = ids.map((name) => {
58
+ const j = run.steps[name];
59
+ if (!j)
60
+ return { name, status: 'pending' };
61
+ if (!native && j.status === 'awaiting_approval')
62
+ return { name, status: 'running', detail: 'awaiting approval' };
63
+ if (!native && j.status === 'interrupted')
64
+ return { name, status: 'failed', detail: j.error ?? 'interrupted' };
65
+ return { name, status: j.status, ...(j.error ? { detail: j.error } : {}) };
66
+ });
67
+ const current = run.waiting?.stepId ?? steps.find(s => s.status === 'running')?.name;
68
+ const last = stepOrder?.length ? run.steps[stepOrder[stepOrder.length - 1]] : undefined;
69
+ return {
70
+ flowRunId: run.runId,
71
+ flow: run.flow,
72
+ status,
73
+ ...(current ? { currentStep: current } : {}),
74
+ steps,
75
+ startedAt: run.startedAt,
76
+ ...(run.finishedAt ? { finishedAt: run.finishedAt } : {}),
77
+ ...(status === 'done' && last?.output !== undefined ? { output: last.output } : {}),
78
+ ...(run.status === 'lost' && !native ? { error: 'lost' } : run.error ? { error: run.error } : {}),
79
+ };
80
+ }
81
+ //# sourceMappingURL=adapter.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/flow/adapter.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,59 @@
1
+ import type { ApprovalStatus, ApprovalStore, ApproverKind, ApproverRef, StoredApproval } from '../governance/types';
2
+ /**
3
+ * The approvals of an agent as the `approvalHandler` an `AgentServer` takes (`ApprovalHandler` of `@backendkit-labs/agent-protocol`,
4
+ * protocol 1.2), declared here with the same shape so that core depends on no transport (SPEC-0023 F6c). A supervisor, a console or an
5
+ * MCP client then sees what waits for a person and decides it.
6
+ */
7
+ export interface ApprovalSummaryView {
8
+ id: string;
9
+ status: ApprovalStatus;
10
+ subject: {
11
+ kind: string;
12
+ [key: string]: unknown;
13
+ };
14
+ reason: string;
15
+ approver?: string;
16
+ accepts?: ApproverKind[];
17
+ requestedBy: {
18
+ agentId: string;
19
+ sessionId?: string;
20
+ tenantId?: string;
21
+ };
22
+ createdAt: string;
23
+ outcome?: {
24
+ decision: 'approve' | 'reject';
25
+ by: ApproverRef;
26
+ reason?: string;
27
+ at: string;
28
+ };
29
+ }
30
+ export interface ApprovalDecisionInput {
31
+ decision: 'approve' | 'reject';
32
+ reason?: string;
33
+ by: ApproverRef;
34
+ }
35
+ export interface ApprovalHandlerPort {
36
+ list(filter: {
37
+ status?: ApprovalStatus;
38
+ }): Promise<ApprovalSummaryView[]>;
39
+ get(id: string): Promise<ApprovalSummaryView>;
40
+ decide(id: string, decision: ApprovalDecisionInput, context?: unknown): Promise<ApprovalSummaryView>;
41
+ }
42
+ /** A refusal with a protocol code. `AgentServer` recognises it by `name` and `code`. */
43
+ export declare class ApprovalControlError extends Error {
44
+ readonly code: 'TASK_NOT_FOUND' | 'CONFLICT' | 'FORBIDDEN';
45
+ constructor(code: 'TASK_NOT_FOUND' | 'CONFLICT' | 'FORBIDDEN', message: string);
46
+ }
47
+ export interface ApprovalHandlerOptions {
48
+ /** Can this agent approver do the action itself? Default: no (SPEC-0014 §6.2 rule 3), so only humans and services decide. */
49
+ canAgentAct?: (by: ApproverRef, request: StoredApproval) => Promise<boolean>;
50
+ /**
51
+ * Called after a decision is recorded, for the host to continue what waited for it: for a flow step, run the flow again with the
52
+ * same `runId`. A throw here does not undo the decision.
53
+ */
54
+ onDecided?: (approval: StoredApproval) => void | Promise<void>;
55
+ }
56
+ /** What a reviewer sees. A tool call shows the tool and its arguments, not the whole definition. */
57
+ export declare function summarizeApproval(a: StoredApproval): ApprovalSummaryView;
58
+ export declare function createApprovalHandler(store: ApprovalStore, options?: ApprovalHandlerOptions): ApprovalHandlerPort;
59
+ //# sourceMappingURL=approval-handler.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"approval-handler.d.ts","sourceRoot":"","sources":["../../src/flow/approval-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrI;;;;GAIG;AAEH,MAAM,WAAW,mBAAmB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,WAAW,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,SAAS,GAAG,QAAQ,CAAC;QAAC,EAAE,EAAE,WAAW,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9F;AAED,MAAM,WAAW,qBAAqB;IAClC,QAAQ,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAChC,IAAI,CAAC,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC1E,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACxG;AAED,wFAAwF;AACxF,qBAAa,oBAAqB,SAAQ,KAAK;IAC/B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,UAAU,GAAG,WAAW;gBAAjD,IAAI,EAAE,gBAAgB,GAAG,UAAU,GAAG,WAAW,EAAE,OAAO,EAAE,MAAM;CAI1F;AAED,MAAM,WAAW,sBAAsB;IACnC,6HAA6H;IAC7H,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7E;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAED,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,cAAc,GAAG,mBAAmB,CAkBxE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,GAAE,sBAA2B,GAAG,mBAAmB,CA+BrH"}
@@ -0,0 +1,79 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ApprovalControlError = void 0;
4
+ exports.summarizeApproval = summarizeApproval;
5
+ exports.createApprovalHandler = createApprovalHandler;
6
+ const approval_1 = require("../governance/approval");
7
+ /** A refusal with a protocol code. `AgentServer` recognises it by `name` and `code`. */
8
+ class ApprovalControlError extends Error {
9
+ code;
10
+ constructor(code, message) {
11
+ super(message);
12
+ this.code = code;
13
+ this.name = 'ControlError';
14
+ }
15
+ }
16
+ exports.ApprovalControlError = ApprovalControlError;
17
+ /** What a reviewer sees. A tool call shows the tool and its arguments, not the whole definition. */
18
+ function summarizeApproval(a) {
19
+ const s = a.subject;
20
+ const subject = s.kind === 'tool_call' && 'call' in s
21
+ ? { kind: 'tool_call', tool: s.call.tool.name, args: s.call.args }
22
+ : { ...s };
23
+ return {
24
+ id: a.id,
25
+ status: a.status,
26
+ subject,
27
+ reason: a.reason,
28
+ ...(a.approver ? { approver: a.approver } : {}),
29
+ ...(a.accepts ? { accepts: a.accepts } : {}),
30
+ requestedBy: {
31
+ agentId: a.principal.agentId, sessionId: a.principal.sessionId, ...(a.principal.tenantId ? { tenantId: a.principal.tenantId } : {}),
32
+ },
33
+ createdAt: a.createdAt,
34
+ ...(a.outcome ? { outcome: { decision: a.outcome.decision, by: a.outcome.by, ...(a.outcome.reason ? { reason: a.outcome.reason } : {}), at: a.outcome.at } } : {}),
35
+ };
36
+ }
37
+ function createApprovalHandler(store, options = {}) {
38
+ const find = async (id) => {
39
+ let found;
40
+ try {
41
+ found = await store.get(id);
42
+ }
43
+ catch { /* an id the store refuses is an id it does not have */ }
44
+ if (!found)
45
+ throw new ApprovalControlError('TASK_NOT_FOUND', `approval ${id} not found`);
46
+ return found;
47
+ };
48
+ return {
49
+ list: async (filter) => (await store.list(filter.status ? { status: filter.status } : {})).map(summarizeApproval),
50
+ get: async (id) => summarizeApproval(await find(id)),
51
+ decide: async (id, d) => {
52
+ const request = await find(id);
53
+ if (request.status !== 'pending')
54
+ throw new ApprovalControlError('CONFLICT', `approval ${id} was already decided (${request.status})`);
55
+ const outcome = {
56
+ decision: d.decision, by: d.by, ...(d.reason ? { reason: d.reason } : {}), at: new Date().toISOString(),
57
+ };
58
+ // An answer that breaks the rules (wrong kind of approver, one's own request) is refused, not recorded as a rejection:
59
+ // the approver is told, and the request stays open for someone who may decide it.
60
+ const problem = await (0, approval_1.approvalProblem)(outcome, request, async (by) => options.canAgentAct?.(by, request) ?? false);
61
+ if (problem)
62
+ throw new ApprovalControlError('FORBIDDEN', problem);
63
+ let stored;
64
+ try {
65
+ stored = await store.resolve(id, outcome);
66
+ }
67
+ catch (err) {
68
+ // Another decision won the race: the store accepts one per id.
69
+ throw new ApprovalControlError('CONFLICT', err.message);
70
+ }
71
+ try {
72
+ await options.onDecided?.(stored);
73
+ }
74
+ catch { /* the decision stands */ }
75
+ return summarizeApproval(stored);
76
+ },
77
+ };
78
+ }
79
+ //# sourceMappingURL=approval-handler.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"approval-handler.js","sourceRoot":"","sources":["../../src/flow/approval-handler.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,39 @@
1
+ import type { ApprovalStore, Approver, ApproverRef, Identity, ToolPolicy } from '../governance/types';
2
+ import type { FlowStep } from './types';
3
+ /**
4
+ * Approval of a flow step through the `ApprovalStore` of SPEC-0014 (SPEC-0023 F5). A step needs approval when its gate says
5
+ * `approval: human`, or when the `policy` decides `ask` for the pseudo tool `flow.step:<stepId>` (which is how a learned rule
6
+ * can put a step behind a person). The request is stored with a deterministic id, so resuming the run finds the answer.
7
+ */
8
+ export interface FlowApprovals {
9
+ store: ApprovalStore;
10
+ /** Who the flow acts for. The agent is the step's agent and the session is the run. */
11
+ identity?: Identity;
12
+ chain?: string[];
13
+ /** Decides per step; `ask` stops it for approval, `deny` fails it. No policy: only `gate.approval: human` asks. */
14
+ policy?: ToolPolicy;
15
+ /** Answers in process (a CLI, a connected UI). Without one the run stops with `awaiting_approval` until someone resolves the store. */
16
+ approver?: Approver;
17
+ /**
18
+ * `before` (default): the person approves the ACTION and the step runs after. `after`: the step runs, its output is shown to
19
+ * the approver (it is in the request) and the steps that follow wait for the decision; a rejection fails the step.
20
+ */
21
+ when?: 'before' | 'after';
22
+ /** Can this agent approver do the step itself? Default: no (SPEC-0014 §6.2 rule 3). */
23
+ canAgentAct?: (by: ApproverRef, step: FlowStep) => Promise<boolean>;
24
+ }
25
+ export type StepApproval = {
26
+ kind: 'proceed';
27
+ } | {
28
+ kind: 'rejected';
29
+ reason: string;
30
+ } | {
31
+ kind: 'denied';
32
+ reason: string;
33
+ } | {
34
+ kind: 'pending';
35
+ approvalId: string;
36
+ };
37
+ export declare function stepApprovalId(runId: string, stepId: string): string;
38
+ export declare function decideStepApproval(a: FlowApprovals, flow: string, runId: string, step: FlowStep, previous: Record<string, string>, output?: string): Promise<StepApproval>;
39
+ //# sourceMappingURL=approval.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../src/flow/approval.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAC0B,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAa,UAAU,EAC1G,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,aAAa,CAAC;IACrB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,mHAAmH;IACnH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uIAAuI;IACvI,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC1B,uFAAuF;IACvF,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvE;AAED,MAAM,MAAM,YAAY,GAClB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAsB,kBAAkB,CACpC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GACjH,OAAO,CAAC,YAAY,CAAC,CA4CvB"}
@@ -0,0 +1,58 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.stepApprovalId = stepApprovalId;
4
+ exports.decideStepApproval = decideStepApproval;
5
+ const approval_1 = require("../governance/approval");
6
+ function stepApprovalId(runId, stepId) {
7
+ return `${runId}-${stepId}`.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 128);
8
+ }
9
+ async function decideStepApproval(a, flow, runId, step, previous, output) {
10
+ const principal = { agentId: step.agent, sessionId: runId, chain: a.chain ?? [], ...(a.identity ?? {}) };
11
+ const human = step.gate?.approval === 'human';
12
+ let reason = human ? `step "${step.id}" of flow "${flow}" requires human approval` : '';
13
+ let approver;
14
+ let accepts = human ? ['human'] : undefined;
15
+ if (a.policy) {
16
+ const d = await a.policy.decide(principal, {
17
+ tool: { name: `flow.step:${step.id}`, description: `step "${step.id}" of flow "${flow}"`, parameters: { type: 'object', properties: {} }, execute: async () => '' },
18
+ args: { input: previous, ...(output !== undefined ? { output } : {}) },
19
+ });
20
+ if (d.effect === 'deny')
21
+ return { kind: 'denied', reason: d.reason };
22
+ if (d.effect === 'ask') {
23
+ reason = d.reason;
24
+ approver = d.approver;
25
+ if (d.accepts)
26
+ accepts = human && !d.accepts.includes('human') ? ['human'] : d.accepts;
27
+ }
28
+ else if (!human) {
29
+ return { kind: 'proceed' };
30
+ }
31
+ }
32
+ else if (!human) {
33
+ return { kind: 'proceed' };
34
+ }
35
+ const id = stepApprovalId(runId, step.id);
36
+ let stored = await a.store.get(id);
37
+ if (!stored) {
38
+ const req = {
39
+ id, principal, subject: { kind: 'workflow_step', workflow: flow, step: step.id, input: output !== undefined ? { previous, output } : previous },
40
+ reason, ...(approver ? { approver } : {}), ...(accepts ? { accepts } : {}), createdAt: new Date().toISOString(),
41
+ };
42
+ await a.store.put(req);
43
+ stored = await a.store.get(id);
44
+ }
45
+ if (stored && stored.status === 'pending' && a.approver) {
46
+ const outcome = await a.approver.request(stored);
47
+ const problem = await (0, approval_1.approvalProblem)(outcome, stored, async (by) => a.canAgentAct?.(by, step) ?? false);
48
+ stored = await a.store.resolve(id, problem
49
+ ? { decision: 'reject', by: outcome.by ?? { kind: 'service', id: 'engine' }, reason: problem, at: new Date().toISOString() }
50
+ : outcome);
51
+ }
52
+ if (!stored || stored.status === 'pending')
53
+ return { kind: 'pending', approvalId: id };
54
+ if (stored.status === 'rejected')
55
+ return { kind: 'rejected', reason: stored.outcome?.reason ?? 'rejected' };
56
+ return { kind: 'proceed' }; // approved, or executed on a previous attempt
57
+ }
58
+ //# sourceMappingURL=approval.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"approval.js","sourceRoot":"","sources":["../../src/flow/approval.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,6 @@
1
+ import type { FlowCondition } from './types';
2
+ /** Text of a condition for the log: `decision contains "ENTER"`. */
3
+ export declare function describeCondition(c: FlowCondition): string;
4
+ /** Whether `output` (of the step the condition looks at) satisfies it. An invalid regular expression is never satisfied: `validateFlow` reports it. */
5
+ export declare function evaluateCondition(c: FlowCondition, output: string): boolean;
6
+ //# sourceMappingURL=condition.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"condition.d.ts","sourceRoot":"","sources":["../../src/flow/condition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAI1D;AAED,uJAAuJ;AACvJ,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQ3E"}
@@ -0,0 +1,30 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.describeCondition = describeCondition;
4
+ exports.evaluateCondition = evaluateCondition;
5
+ /** Text of a condition for the log: `decision contains "ENTER"`. */
6
+ function describeCondition(c) {
7
+ if (c.contains !== undefined)
8
+ return `${c.step} ${c.not ? 'does not contain' : 'contains'} "${c.contains}"`;
9
+ if (c.equals !== undefined)
10
+ return `${c.step} ${c.not ? 'does not equal' : 'equals'} "${c.equals}"`;
11
+ return `${c.step} ${c.not ? 'does not match' : 'matches'} /${c.matches}/`;
12
+ }
13
+ /** Whether `output` (of the step the condition looks at) satisfies it. An invalid regular expression is never satisfied: `validateFlow` reports it. */
14
+ function evaluateCondition(c, output) {
15
+ let ok;
16
+ if (c.contains !== undefined)
17
+ ok = output.includes(c.contains);
18
+ else if (c.equals !== undefined)
19
+ ok = output.trim() === c.equals.trim();
20
+ else {
21
+ try {
22
+ ok = new RegExp(c.matches ?? '').test(output);
23
+ }
24
+ catch {
25
+ return false;
26
+ }
27
+ }
28
+ return c.not ? !ok : ok;
29
+ }
30
+ //# sourceMappingURL=condition.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"condition.js","sourceRoot":"","sources":["../../src/flow/condition.ts"],"names":[],"mappings":";;AAGA,8CAIC;AAGD,8CAQC;AAhBD,oEAAoE;AACpE,SAAgB,iBAAiB,CAAC,CAAgB;IAC9C,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,QAAQ,GAAG,CAAC;IAC5G,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC;IACpG,OAAO,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,OAAO,GAAG,CAAC;AAC9E,CAAC;AAED,uJAAuJ;AACvJ,SAAgB,iBAAiB,CAAC,CAAgB,EAAE,MAAc;IAC9D,IAAI,EAAW,CAAC;IAChB,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;QAAE,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;SAC1D,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;QAAE,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;SACnE,CAAC;QACF,IAAI,CAAC;YAAC,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,KAAK,CAAC;QAAC,CAAC;IAClF,CAAC;IACD,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5B,CAAC"}
@@ -0,0 +1,44 @@
1
+ import type { FlowDefinition } from './types';
2
+ /**
3
+ * Plans and static flows as `FlowDefinition` (SPEC-0023 F6a). A plan a planner generates and a flow written in YAML are the same
4
+ * object once converted: both run on `runFlow`. The inputs are structural types, so core needs no planner or orchestrator package.
5
+ *
6
+ * `gate: true` is a person reviewing the step's OUTPUT (`gate.approval: 'human'`); run it with `approvals.when: 'after'`.
7
+ * `gate_criteria` only count when the step is gated, as before.
8
+ */
9
+ export interface PlanStepLike {
10
+ id: string;
11
+ agent_id: string;
12
+ task: string;
13
+ depends_on?: string[];
14
+ gate?: boolean;
15
+ gate_criteria?: string[];
16
+ timeout_ms?: number;
17
+ }
18
+ export interface TaskPlanLike {
19
+ summary: string;
20
+ subtasks: PlanStepLike[];
21
+ }
22
+ export interface StaticFlowLike {
23
+ id: string;
24
+ name?: string;
25
+ version?: number;
26
+ steps: Array<{
27
+ id: string;
28
+ agent: string;
29
+ task: string;
30
+ depends_on?: string[];
31
+ gate?: boolean;
32
+ gate_criteria?: string[];
33
+ }>;
34
+ }
35
+ /** A plan generated for one task: an ephemeral flow with a manual trigger. */
36
+ export declare function flowFromTaskPlan(plan: TaskPlanLike, opts?: {
37
+ flow?: string;
38
+ version?: number;
39
+ }): FlowDefinition;
40
+ /** A flow file of the orchestrator (`flows/*.yaml`, already parsed). `{{payload.key}}` placeholders pass through unchanged. */
41
+ export declare function flowFromStaticFlow(f: StaticFlowLike, opts?: {
42
+ trigger?: FlowDefinition['trigger'];
43
+ }): FlowDefinition;
44
+ //# sourceMappingURL=convert.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../src/flow/convert.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;GAMG;AAEH,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;QACT,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC,CAAC;CACN;AAMD,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,cAAc,CAWnH;AAED,+HAA+H;AAC/H,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAA;CAAO,GAAG,cAAc,CAUxH"}
@@ -0,0 +1,34 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.flowFromTaskPlan = flowFromTaskPlan;
4
+ exports.flowFromStaticFlow = flowFromStaticFlow;
5
+ const types_1 = require("./types");
6
+ function gateOf(gate, criteria) {
7
+ return gate ? { gate: { criteria: criteria ?? [], evidence: 'optional', approval: 'human' } } : {};
8
+ }
9
+ /** A plan generated for one task: an ephemeral flow with a manual trigger. */
10
+ function flowFromTaskPlan(plan, opts = {}) {
11
+ return types_1.FlowDefinitionSchema.parse({
12
+ flow: opts.flow ?? (plan.summary.trim() || 'plan'),
13
+ version: opts.version ?? 1,
14
+ trigger: { type: 'manual' },
15
+ steps: plan.subtasks.map(s => ({
16
+ id: s.id, agent: s.agent_id, prompt: s.task, after: s.depends_on ?? [],
17
+ ...gateOf(s.gate, s.gate_criteria),
18
+ ...(s.timeout_ms !== undefined ? { timeoutMs: s.timeout_ms } : {}),
19
+ })),
20
+ });
21
+ }
22
+ /** A flow file of the orchestrator (`flows/*.yaml`, already parsed). `{{payload.key}}` placeholders pass through unchanged. */
23
+ function flowFromStaticFlow(f, opts = {}) {
24
+ return types_1.FlowDefinitionSchema.parse({
25
+ flow: f.id,
26
+ version: f.version ?? 1,
27
+ trigger: opts.trigger ?? { type: 'manual' },
28
+ steps: f.steps.map(s => ({
29
+ id: s.id, agent: s.agent, prompt: s.task, after: s.depends_on ?? [],
30
+ ...gateOf(s.gate, s.gate_criteria),
31
+ })),
32
+ });
33
+ }
34
+ //# sourceMappingURL=convert.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"convert.js","sourceRoot":"","sources":["../../src/flow/convert.ts"],"names":[],"mappings":";;AA6CA,4CAWC;AAGD,gDAUC;AArED,mCAA+C;AAwC/C,SAAS,MAAM,CAAC,IAAyB,EAAE,QAA8B;IACrE,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,QAAQ,IAAI,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACvG,CAAC;AAED,8EAA8E;AAC9E,SAAgB,gBAAgB,CAAC,IAAkB,EAAE,OAA4C,EAAE;IAC/F,OAAO,4BAAoB,CAAC,KAAK,CAAC;QAC9B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,MAAM,CAAC;QAClD,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,CAAC;QAC1B,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC3B,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC3B,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,UAAU,IAAI,EAAE;YACtE,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC;YAClC,GAAG,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrE,CAAC,CAAC;KACN,CAAC,CAAC;AACP,CAAC;AAED,+HAA+H;AAC/H,SAAgB,kBAAkB,CAAC,CAAiB,EAAE,OAAgD,EAAE;IACpG,OAAO,4BAAoB,CAAC,KAAK,CAAC;QAC9B,IAAI,EAAE,CAAC,CAAC,EAAE;QACV,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,CAAC;QACvB,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC3C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACrB,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,UAAU,IAAI,EAAE;YACnE,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC;SACrC,CAAC,CAAC;KACN,CAAC,CAAC;AACP,CAAC"}