@backendkit-labs/agent-core 0.41.0 → 0.43.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.
- package/README.md +27 -0
- package/dist/engine/AgentEngine.d.ts +22 -2
- package/dist/engine/AgentEngine.d.ts.map +1 -1
- package/dist/engine/AgentEngine.js +92 -48
- package/dist/engine/AgentEngine.js.map +1 -1
- package/dist/engine/createBaseEngine.d.ts +2 -0
- package/dist/engine/createBaseEngine.d.ts.map +1 -1
- package/dist/engine/createBaseEngine.js +21 -4
- package/dist/engine/createBaseEngine.js.map +1 -1
- package/dist/engine/error-code.d.ts +7 -0
- package/dist/engine/error-code.d.ts.map +1 -0
- package/dist/engine/error-code.js +23 -0
- package/dist/engine/error-code.js.map +1 -0
- package/dist/engine/run-recorder.d.ts +13 -0
- package/dist/engine/run-recorder.d.ts.map +1 -0
- package/dist/engine/run-recorder.js +49 -0
- package/dist/engine/run-recorder.js.map +1 -0
- package/dist/flow/adapter.d.ts +20 -0
- package/dist/flow/adapter.d.ts.map +1 -0
- package/dist/flow/adapter.js +81 -0
- package/dist/flow/adapter.js.map +1 -0
- package/dist/flow/approval-handler.d.ts +59 -0
- package/dist/flow/approval-handler.d.ts.map +1 -0
- package/dist/flow/approval-handler.js +79 -0
- package/dist/flow/approval-handler.js.map +1 -0
- package/dist/flow/approval.d.ts +39 -0
- package/dist/flow/approval.d.ts.map +1 -0
- package/dist/flow/approval.js +58 -0
- package/dist/flow/approval.js.map +1 -0
- package/dist/flow/convert.d.ts +44 -0
- package/dist/flow/convert.d.ts.map +1 -0
- package/dist/flow/convert.js +34 -0
- package/dist/flow/convert.js.map +1 -0
- package/dist/flow/file-journal.d.ts +34 -0
- package/dist/flow/file-journal.d.ts.map +1 -0
- package/dist/flow/file-journal.js +176 -0
- package/dist/flow/file-journal.js.map +1 -0
- package/dist/flow/handler.d.ts +35 -0
- package/dist/flow/handler.d.ts.map +1 -0
- package/dist/flow/handler.js +51 -0
- package/dist/flow/handler.js.map +1 -0
- package/dist/flow/host.d.ts +79 -0
- package/dist/flow/host.d.ts.map +1 -0
- package/dist/flow/host.js +148 -0
- package/dist/flow/host.js.map +1 -0
- package/dist/flow/index.d.ts +27 -0
- package/dist/flow/index.d.ts.map +1 -0
- package/dist/flow/index.js +55 -0
- package/dist/flow/index.js.map +1 -0
- package/dist/flow/interpolate.d.ts +6 -0
- package/dist/flow/interpolate.d.ts.map +1 -0
- package/dist/flow/interpolate.js +18 -0
- package/dist/flow/interpolate.js.map +1 -0
- package/dist/flow/journal.d.ts +105 -0
- package/dist/flow/journal.d.ts.map +1 -0
- package/dist/flow/journal.js +89 -0
- package/dist/flow/journal.js.map +1 -0
- package/dist/flow/limiter.d.ts +21 -0
- package/dist/flow/limiter.d.ts.map +1 -0
- package/dist/flow/limiter.js +45 -0
- package/dist/flow/limiter.js.map +1 -0
- package/dist/flow/loader.d.ts +24 -0
- package/dist/flow/loader.d.ts.map +1 -0
- package/dist/flow/loader.js +172 -0
- package/dist/flow/loader.js.map +1 -0
- package/dist/flow/planner.d.ts +50 -0
- package/dist/flow/planner.d.ts.map +1 -0
- package/dist/flow/planner.js +131 -0
- package/dist/flow/planner.js.map +1 -0
- package/dist/flow/run.d.ts +106 -0
- package/dist/flow/run.d.ts.map +1 -0
- package/dist/flow/run.js +354 -0
- package/dist/flow/run.js.map +1 -0
- package/dist/flow/tools.d.ts +27 -0
- package/dist/flow/tools.d.ts.map +1 -0
- package/dist/flow/tools.js +71 -0
- package/dist/flow/tools.js.map +1 -0
- package/dist/flow/types.d.ts +112 -0
- package/dist/flow/types.d.ts.map +1 -0
- package/dist/flow/types.js +63 -0
- package/dist/flow/types.js.map +1 -0
- package/dist/governance/types.d.ts +6 -0
- package/dist/governance/types.d.ts.map +1 -1
- package/dist/index.d.ts +21 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +53 -3
- package/dist/index.js.map +1 -1
- package/dist/learning/index.d.ts +2 -1
- package/dist/learning/index.d.ts.map +1 -1
- package/dist/learning/index.js +339 -63
- package/dist/learning/index.js.map +1 -1
- package/dist/learning/signal.d.ts +69 -0
- package/dist/learning/signal.d.ts.map +1 -0
- package/dist/learning/signal.js +201 -0
- package/dist/learning/signal.js.map +1 -0
- package/dist/learning/types.d.ts +203 -1
- package/dist/learning/types.d.ts.map +1 -1
- package/dist/learning/units.d.ts +46 -0
- package/dist/learning/units.d.ts.map +1 -0
- package/dist/learning/units.js +137 -0
- package/dist/learning/units.js.map +1 -0
- package/dist/tools/defineTool.d.ts +4 -1
- package/dist/tools/defineTool.d.ts.map +1 -1
- package/dist/tools/defineTool.js +5 -2
- package/dist/tools/defineTool.js.map +1 -1
- package/dist/tools/services.d.ts +13 -0
- package/dist/tools/services.d.ts.map +1 -1
- package/dist/tools/services.js +12 -0
- package/dist/tools/services.js.map +1 -1
- package/dist/tools/tool-error.d.ts +19 -0
- package/dist/tools/tool-error.d.ts.map +1 -0
- package/dist/tools/tool-error.js +33 -0
- package/dist/tools/tool-error.js.map +1 -0
- package/dist/types/index.d.ts +39 -0
- package/dist/types/index.d.ts.map +1 -1
- package/package.json +94 -89
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Replaces `{{payload}}` and `{{payload.a.b}}` with values from the payload.
|
|
3
|
+
* Objects are JSON-stringified; missing paths render as `null`.
|
|
4
|
+
*/
|
|
5
|
+
export declare function interpolate(template: string, payload: unknown): string;
|
|
6
|
+
//# sourceMappingURL=interpolate.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["../../src/flow/interpolate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAWtE"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.interpolate = interpolate;
|
|
4
|
+
/**
|
|
5
|
+
* Replaces `{{payload}}` and `{{payload.a.b}}` with values from the payload.
|
|
6
|
+
* Objects are JSON-stringified; missing paths render as `null`.
|
|
7
|
+
*/
|
|
8
|
+
function interpolate(template, payload) {
|
|
9
|
+
return template.replace(/\{\{\s*payload((?:\.[\w-]+)*)\s*\}\}/g, (_match, pathStr) => {
|
|
10
|
+
const value = pathStr
|
|
11
|
+
? pathStr.slice(1).split('.').reduce((acc, key) => acc?.[key], payload)
|
|
12
|
+
: payload;
|
|
13
|
+
if (value === undefined || value === null)
|
|
14
|
+
return 'null';
|
|
15
|
+
return typeof value === 'string' ? value : JSON.stringify(value);
|
|
16
|
+
});
|
|
17
|
+
}
|
|
18
|
+
//# sourceMappingURL=interpolate.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"interpolate.js","sourceRoot":"","sources":["../../src/flow/interpolate.ts"],"names":[],"mappings":";;AAIA,kCAWC;AAfD;;;GAGG;AACH,SAAgB,WAAW,CAAC,QAAgB,EAAE,OAAgB;IAC1D,OAAO,QAAQ,CAAC,OAAO,CAAC,uCAAuC,EAAE,CAAC,MAAM,EAAE,OAAe,EAAE,EAAE;QACzF,MAAM,KAAK,GAAG,OAAO;YACjB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAChC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAE,GAA2C,EAAE,CAAC,GAAG,CAAC,EACjE,OAAO,CACV;YACD,CAAC,CAAC,OAAO,CAAC;QACd,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,MAAM,CAAC;QACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;AACP,CAAC"}
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import type { FlowTransition } from './types';
|
|
2
|
+
/**
|
|
3
|
+
* The durable record of a flow run (SPEC-0023 F3): which step the run is on, what each one produced, who owns the run.
|
|
4
|
+
* It is what lets a restarted process resume without repeating a step that is done.
|
|
5
|
+
*
|
|
6
|
+
* It holds step outputs (the next step needs them to resume), so it is as sensitive as the conversation history. Only the
|
|
7
|
+
* input preview and error texts go through the optional `redact`; the payload itself is NOT stored: whoever resumes a run
|
|
8
|
+
* supplies it again.
|
|
9
|
+
*/
|
|
10
|
+
export type JournalStepStatus = 'pending' | 'running' | 'done' | 'failed' | 'skipped' | 'awaiting_approval' | 'interrupted';
|
|
11
|
+
export type JournalRunStatus = 'running' | 'paused' | 'awaiting_approval' | 'done' | 'failed' | 'cancelled' | 'lost';
|
|
12
|
+
export interface JournalStep {
|
|
13
|
+
status: JournalStepStatus;
|
|
14
|
+
output?: string;
|
|
15
|
+
error?: string;
|
|
16
|
+
/** How many times the step has been started (the idempotency key carries it). */
|
|
17
|
+
attempt: number;
|
|
18
|
+
at: string;
|
|
19
|
+
costUsd?: number;
|
|
20
|
+
}
|
|
21
|
+
export interface JournalRun {
|
|
22
|
+
runId: string;
|
|
23
|
+
flow: string;
|
|
24
|
+
tenantId?: string;
|
|
25
|
+
startedAt: string;
|
|
26
|
+
updatedAt: string;
|
|
27
|
+
finishedAt?: string;
|
|
28
|
+
status: JournalRunStatus;
|
|
29
|
+
/** Cut and masked: never the raw payload. */
|
|
30
|
+
inputPreview: string;
|
|
31
|
+
steps: Record<string, JournalStep>;
|
|
32
|
+
waiting?: {
|
|
33
|
+
stepId: string;
|
|
34
|
+
approvalId: string;
|
|
35
|
+
criteria?: string[];
|
|
36
|
+
};
|
|
37
|
+
transitions: FlowTransition[];
|
|
38
|
+
error?: string;
|
|
39
|
+
costUsd?: number;
|
|
40
|
+
}
|
|
41
|
+
export type NewJournalRun = Pick<JournalRun, 'runId' | 'flow' | 'inputPreview'> & {
|
|
42
|
+
tenantId?: string;
|
|
43
|
+
};
|
|
44
|
+
export interface StepPatch extends Partial<Omit<JournalStep, 'at'>> {
|
|
45
|
+
transitions?: FlowTransition[];
|
|
46
|
+
}
|
|
47
|
+
export interface RunPatch {
|
|
48
|
+
status?: JournalRunStatus;
|
|
49
|
+
error?: string;
|
|
50
|
+
costUsd?: number;
|
|
51
|
+
waiting?: JournalRun['waiting'] | null;
|
|
52
|
+
transitions?: FlowTransition[];
|
|
53
|
+
}
|
|
54
|
+
export interface RunJournal {
|
|
55
|
+
/** Creates the run. Fails if the id already exists. */
|
|
56
|
+
begin(run: NewJournalRun): Promise<void>;
|
|
57
|
+
/** Writes the change BEFORE the step runs (`running`) and AFTER (`done`/`failed`). A journal that cannot write throws: the caller must not run the step. */
|
|
58
|
+
step(runId: string, stepId: string, patch: StepPatch): Promise<void>;
|
|
59
|
+
update(runId: string, patch: RunPatch): Promise<void>;
|
|
60
|
+
/** One owner per run, with expiry. Returns the release function, or null if another owner holds it. */
|
|
61
|
+
claim(runId: string, owner: string, ttlMs: number): Promise<(() => Promise<void>) | null>;
|
|
62
|
+
get(runId: string): Promise<JournalRun | undefined>;
|
|
63
|
+
list(filter?: {
|
|
64
|
+
status?: JournalRunStatus[];
|
|
65
|
+
flow?: string;
|
|
66
|
+
tenantId?: string;
|
|
67
|
+
}): Promise<JournalRun[]>;
|
|
68
|
+
}
|
|
69
|
+
export type JournalEvent = {
|
|
70
|
+
kind: 'begin';
|
|
71
|
+
at: string;
|
|
72
|
+
run: NewJournalRun;
|
|
73
|
+
} | {
|
|
74
|
+
kind: 'step';
|
|
75
|
+
at: string;
|
|
76
|
+
stepId: string;
|
|
77
|
+
patch: StepPatch;
|
|
78
|
+
} | {
|
|
79
|
+
kind: 'update';
|
|
80
|
+
at: string;
|
|
81
|
+
patch: RunPatch;
|
|
82
|
+
};
|
|
83
|
+
export declare function foldEvents(events: JournalEvent[]): JournalRun | undefined;
|
|
84
|
+
export declare function matches(run: JournalRun, filter?: {
|
|
85
|
+
status?: JournalRunStatus[];
|
|
86
|
+
flow?: string;
|
|
87
|
+
tenantId?: string;
|
|
88
|
+
}): boolean;
|
|
89
|
+
/** In memory: for tests and for processes whose runs need not outlive them. */
|
|
90
|
+
export declare class MemoryRunJournal implements RunJournal {
|
|
91
|
+
private readonly logs;
|
|
92
|
+
private readonly claims;
|
|
93
|
+
begin(run: NewJournalRun): Promise<void>;
|
|
94
|
+
private log;
|
|
95
|
+
step(runId: string, stepId: string, patch: StepPatch): Promise<void>;
|
|
96
|
+
update(runId: string, patch: RunPatch): Promise<void>;
|
|
97
|
+
claim(runId: string, owner: string, ttlMs: number): Promise<(() => Promise<void>) | null>;
|
|
98
|
+
get(runId: string): Promise<JournalRun | undefined>;
|
|
99
|
+
list(filter?: {
|
|
100
|
+
status?: JournalRunStatus[];
|
|
101
|
+
flow?: string;
|
|
102
|
+
tenantId?: string;
|
|
103
|
+
}): Promise<JournalRun[]>;
|
|
104
|
+
}
|
|
105
|
+
//# sourceMappingURL=journal.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/flow/journal.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.MemoryRunJournal = void 0;
|
|
4
|
+
exports.foldEvents = foldEvents;
|
|
5
|
+
exports.matches = matches;
|
|
6
|
+
const TERMINAL = ['done', 'failed', 'cancelled'];
|
|
7
|
+
function foldEvents(events) {
|
|
8
|
+
let run;
|
|
9
|
+
for (const ev of events) {
|
|
10
|
+
if (ev.kind === 'begin') {
|
|
11
|
+
run = { ...ev.run, startedAt: ev.at, updatedAt: ev.at, status: 'running', steps: {}, transitions: [] };
|
|
12
|
+
continue;
|
|
13
|
+
}
|
|
14
|
+
if (!run)
|
|
15
|
+
continue;
|
|
16
|
+
run.updatedAt = ev.at;
|
|
17
|
+
if (ev.kind === 'step') {
|
|
18
|
+
const { transitions, ...rest } = ev.patch;
|
|
19
|
+
const prev = run.steps[ev.stepId] ?? { status: 'pending', attempt: 0, at: ev.at };
|
|
20
|
+
run.steps[ev.stepId] = { ...prev, ...rest, at: ev.at };
|
|
21
|
+
if (transitions)
|
|
22
|
+
run.transitions.push(...transitions);
|
|
23
|
+
}
|
|
24
|
+
else {
|
|
25
|
+
const { transitions, waiting, ...rest } = ev.patch;
|
|
26
|
+
Object.assign(run, rest);
|
|
27
|
+
if (waiting === null)
|
|
28
|
+
delete run.waiting;
|
|
29
|
+
else if (waiting)
|
|
30
|
+
run.waiting = waiting;
|
|
31
|
+
if (transitions)
|
|
32
|
+
run.transitions.push(...transitions);
|
|
33
|
+
if (rest.status && TERMINAL.includes(rest.status))
|
|
34
|
+
run.finishedAt = ev.at;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
return run;
|
|
38
|
+
}
|
|
39
|
+
function matches(run, filter = {}) {
|
|
40
|
+
return (!filter.status || filter.status.includes(run.status))
|
|
41
|
+
&& (!filter.flow || run.flow === filter.flow)
|
|
42
|
+
&& (!filter.tenantId || run.tenantId === filter.tenantId);
|
|
43
|
+
}
|
|
44
|
+
/** In memory: for tests and for processes whose runs need not outlive them. */
|
|
45
|
+
class MemoryRunJournal {
|
|
46
|
+
logs = new Map();
|
|
47
|
+
claims = new Map();
|
|
48
|
+
async begin(run) {
|
|
49
|
+
if (this.logs.has(run.runId))
|
|
50
|
+
throw new Error(`run "${run.runId}" already exists`);
|
|
51
|
+
this.logs.set(run.runId, [{ kind: 'begin', at: new Date().toISOString(), run }]);
|
|
52
|
+
}
|
|
53
|
+
log(runId) {
|
|
54
|
+
const l = this.logs.get(runId);
|
|
55
|
+
if (!l)
|
|
56
|
+
throw new Error(`run "${runId}" does not exist`);
|
|
57
|
+
return l;
|
|
58
|
+
}
|
|
59
|
+
async step(runId, stepId, patch) {
|
|
60
|
+
this.log(runId).push({ kind: 'step', at: new Date().toISOString(), stepId, patch });
|
|
61
|
+
}
|
|
62
|
+
async update(runId, patch) {
|
|
63
|
+
this.log(runId).push({ kind: 'update', at: new Date().toISOString(), patch });
|
|
64
|
+
}
|
|
65
|
+
async claim(runId, owner, ttlMs) {
|
|
66
|
+
const cur = this.claims.get(runId);
|
|
67
|
+
if (cur && cur.expiresAt > Date.now() && cur.owner !== owner)
|
|
68
|
+
return null;
|
|
69
|
+
const mine = { owner, expiresAt: Date.now() + ttlMs };
|
|
70
|
+
this.claims.set(runId, mine);
|
|
71
|
+
return async () => { if (this.claims.get(runId) === mine)
|
|
72
|
+
this.claims.delete(runId); };
|
|
73
|
+
}
|
|
74
|
+
async get(runId) {
|
|
75
|
+
const l = this.logs.get(runId);
|
|
76
|
+
return l ? foldEvents(l) : undefined;
|
|
77
|
+
}
|
|
78
|
+
async list(filter) {
|
|
79
|
+
const out = [];
|
|
80
|
+
for (const l of this.logs.values()) {
|
|
81
|
+
const r = foldEvents(l);
|
|
82
|
+
if (r && matches(r, filter))
|
|
83
|
+
out.push(r);
|
|
84
|
+
}
|
|
85
|
+
return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
exports.MemoryRunJournal = MemoryRunJournal;
|
|
89
|
+
//# sourceMappingURL=journal.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../src/flow/journal.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A cap on how many things run at once per key (an agent id, a tenant id). In process: a limit shared across processes is
|
|
3
|
+
* the integrator's implementation of the same interface (SPEC-0023 D4).
|
|
4
|
+
*/
|
|
5
|
+
export interface ConcurrencyLimiter {
|
|
6
|
+
/** Resolves with a release function once a slot for `key` is free. Rejects if `signal` aborts while waiting. */
|
|
7
|
+
acquire(key: string, signal?: AbortSignal): Promise<() => void>;
|
|
8
|
+
}
|
|
9
|
+
export interface KeyedLimiterOptions {
|
|
10
|
+
/** Slots per key. A function lets each key have its own. Default: unlimited. */
|
|
11
|
+
max?: number | ((key: string) => number | undefined);
|
|
12
|
+
}
|
|
13
|
+
export declare class KeyedConcurrencyLimiter implements ConcurrencyLimiter {
|
|
14
|
+
private readonly opts;
|
|
15
|
+
private readonly active;
|
|
16
|
+
private readonly waiting;
|
|
17
|
+
constructor(opts?: KeyedLimiterOptions);
|
|
18
|
+
private limitFor;
|
|
19
|
+
acquire(key: string, signal?: AbortSignal): Promise<() => void>;
|
|
20
|
+
}
|
|
21
|
+
//# sourceMappingURL=limiter.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"limiter.d.ts","sourceRoot":"","sources":["../../src/flow/limiter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,gHAAgH;IAChH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,mBAAmB;IAChC,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,qBAAa,uBAAwB,YAAW,kBAAkB;IAIlD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;gBAEnC,IAAI,GAAE,mBAAwB;IAE3D,OAAO,CAAC,QAAQ;IAKV,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;CAyBxE"}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.KeyedConcurrencyLimiter = void 0;
|
|
4
|
+
class KeyedConcurrencyLimiter {
|
|
5
|
+
opts;
|
|
6
|
+
active = new Map();
|
|
7
|
+
waiting = new Map();
|
|
8
|
+
constructor(opts = {}) {
|
|
9
|
+
this.opts = opts;
|
|
10
|
+
}
|
|
11
|
+
limitFor(key) {
|
|
12
|
+
const m = typeof this.opts.max === 'function' ? this.opts.max(key) : this.opts.max;
|
|
13
|
+
return m === undefined ? Infinity : Math.max(1, m);
|
|
14
|
+
}
|
|
15
|
+
async acquire(key, signal) {
|
|
16
|
+
if (signal?.aborted)
|
|
17
|
+
throw new Error('aborted');
|
|
18
|
+
while ((this.active.get(key) ?? 0) >= this.limitFor(key)) {
|
|
19
|
+
await new Promise((resolve, reject) => {
|
|
20
|
+
const q = this.waiting.get(key) ?? [];
|
|
21
|
+
const wake = () => { signal?.removeEventListener('abort', onAbort); resolve(); };
|
|
22
|
+
const onAbort = () => {
|
|
23
|
+
const i = q.indexOf(wake);
|
|
24
|
+
if (i >= 0)
|
|
25
|
+
q.splice(i, 1);
|
|
26
|
+
reject(new Error('aborted'));
|
|
27
|
+
};
|
|
28
|
+
q.push(wake);
|
|
29
|
+
this.waiting.set(key, q);
|
|
30
|
+
signal?.addEventListener('abort', onAbort, { once: true });
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
this.active.set(key, (this.active.get(key) ?? 0) + 1);
|
|
34
|
+
let released = false;
|
|
35
|
+
return () => {
|
|
36
|
+
if (released)
|
|
37
|
+
return;
|
|
38
|
+
released = true;
|
|
39
|
+
this.active.set(key, (this.active.get(key) ?? 1) - 1);
|
|
40
|
+
this.waiting.get(key)?.shift()?.();
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
exports.KeyedConcurrencyLimiter = KeyedConcurrencyLimiter;
|
|
45
|
+
//# sourceMappingURL=limiter.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"limiter.js","sourceRoot":"","sources":["../../src/flow/limiter.ts"],"names":[],"mappings":";;;AAcA,MAAa,uBAAuB;IAIH;IAHZ,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACnC,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEhE,YAA6B,OAA4B,EAAE;QAA9B,SAAI,GAAJ,IAAI,CAA0B;IAAG,CAAC;IAEvD,QAAQ,CAAC,GAAW;QACxB,MAAM,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACnF,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAW,EAAE,MAAoB;QAC3C,IAAI,MAAM,EAAE,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;QAChD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACxC,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;gBACtC,MAAM,IAAI,GAAG,GAAS,EAAE,GAAG,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;gBACvF,MAAM,OAAO,GAAG,GAAS,EAAE;oBACvB,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;oBAC1B,IAAI,CAAC,IAAI,CAAC;wBAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;oBAC3B,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;gBACjC,CAAC,CAAC;gBACF,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACb,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBACzB,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,CAAC,CAAC,CAAC;QACP,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACtD,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,OAAO,GAAG,EAAE;YACR,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACtD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QACvC,CAAC,CAAC;IACN,CAAC;CACJ;AApCD,0DAoCC"}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Flow loader: parses and validates declarative flow YAML (SPEC-0023).
|
|
3
|
+
*
|
|
4
|
+
* Validation happens in two layers:
|
|
5
|
+
* 1. Structural (Zod): shapes, required fields, enums.
|
|
6
|
+
* 2. Semantic: duplicate step ids, unknown `after` references, dependency
|
|
7
|
+
* cycles, trigger coherence, compensation selectors, and the static
|
|
8
|
+
* half of the compliance rule — a gate evaluator can never be the
|
|
9
|
+
* step's own executor (evaluador ≠ ejecutor, ADR-3).
|
|
10
|
+
*/
|
|
11
|
+
import { type FlowDefinition } from './types';
|
|
12
|
+
export declare class FlowLoadError extends Error {
|
|
13
|
+
readonly issues: string[];
|
|
14
|
+
constructor(flowName: string, issues: string[]);
|
|
15
|
+
}
|
|
16
|
+
/** Parses a YAML string into a validated FlowDefinition. */
|
|
17
|
+
export declare function parseFlow(yamlContent: string): FlowDefinition;
|
|
18
|
+
/** Loads and validates a single flow file. */
|
|
19
|
+
export declare function loadFlow(filePath: string): Promise<FlowDefinition>;
|
|
20
|
+
/** Loads every `*.yaml` / `*.yml` in a directory. Throws on the first invalid flow. */
|
|
21
|
+
export declare function loadFlowsFromDir(dir: string): Promise<FlowDefinition[]>;
|
|
22
|
+
/** The semantic half of the validation: duplicate ids, unknown or self references, cycles, the trigger and the compensation selectors. */
|
|
23
|
+
export declare function validateFlow(def: FlowDefinition): string[];
|
|
24
|
+
//# sourceMappingURL=loader.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/flow/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAEpE,qBAAa,aAAc,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEd,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE;CAKjD;AAED,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAsB7D;AAED,8CAA8C;AAC9C,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAGxE;AAED,uFAAuF;AACvF,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAU7E;AAID,0IAA0I;AAC1I,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,EAAE,CAoC1D"}
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Flow loader: parses and validates declarative flow YAML (SPEC-0023).
|
|
4
|
+
*
|
|
5
|
+
* Validation happens in two layers:
|
|
6
|
+
* 1. Structural (Zod): shapes, required fields, enums.
|
|
7
|
+
* 2. Semantic: duplicate step ids, unknown `after` references, dependency
|
|
8
|
+
* cycles, trigger coherence, compensation selectors, and the static
|
|
9
|
+
* half of the compliance rule — a gate evaluator can never be the
|
|
10
|
+
* step's own executor (evaluador ≠ ejecutor, ADR-3).
|
|
11
|
+
*/
|
|
12
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
13
|
+
if (k2 === undefined) k2 = k;
|
|
14
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
15
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
16
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
17
|
+
}
|
|
18
|
+
Object.defineProperty(o, k2, desc);
|
|
19
|
+
}) : (function(o, m, k, k2) {
|
|
20
|
+
if (k2 === undefined) k2 = k;
|
|
21
|
+
o[k2] = m[k];
|
|
22
|
+
}));
|
|
23
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
24
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
25
|
+
}) : function(o, v) {
|
|
26
|
+
o["default"] = v;
|
|
27
|
+
});
|
|
28
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
29
|
+
var ownKeys = function(o) {
|
|
30
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
31
|
+
var ar = [];
|
|
32
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
33
|
+
return ar;
|
|
34
|
+
};
|
|
35
|
+
return ownKeys(o);
|
|
36
|
+
};
|
|
37
|
+
return function (mod) {
|
|
38
|
+
if (mod && mod.__esModule) return mod;
|
|
39
|
+
var result = {};
|
|
40
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
41
|
+
__setModuleDefault(result, mod);
|
|
42
|
+
return result;
|
|
43
|
+
};
|
|
44
|
+
})();
|
|
45
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
46
|
+
exports.FlowLoadError = void 0;
|
|
47
|
+
exports.parseFlow = parseFlow;
|
|
48
|
+
exports.loadFlow = loadFlow;
|
|
49
|
+
exports.loadFlowsFromDir = loadFlowsFromDir;
|
|
50
|
+
exports.validateFlow = validateFlow;
|
|
51
|
+
const fs = __importStar(require("fs/promises"));
|
|
52
|
+
const path = __importStar(require("path"));
|
|
53
|
+
const yaml = __importStar(require("yaml"));
|
|
54
|
+
const types_1 = require("./types");
|
|
55
|
+
class FlowLoadError extends Error {
|
|
56
|
+
issues;
|
|
57
|
+
constructor(flowName, issues) {
|
|
58
|
+
super(`Invalid flow "${flowName}":\n${issues.map(i => ` - ${i}`).join('\n')}`);
|
|
59
|
+
this.name = 'FlowLoadError';
|
|
60
|
+
this.issues = issues;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
exports.FlowLoadError = FlowLoadError;
|
|
64
|
+
/** Parses a YAML string into a validated FlowDefinition. */
|
|
65
|
+
function parseFlow(yamlContent) {
|
|
66
|
+
let raw;
|
|
67
|
+
try {
|
|
68
|
+
raw = yaml.parse(yamlContent);
|
|
69
|
+
}
|
|
70
|
+
catch (err) {
|
|
71
|
+
throw new FlowLoadError('<unparsed>', [`YAML syntax error: ${err.message}`]);
|
|
72
|
+
}
|
|
73
|
+
const parsed = types_1.FlowDefinitionSchema.safeParse(raw);
|
|
74
|
+
if (!parsed.success) {
|
|
75
|
+
const name = raw?.flow;
|
|
76
|
+
throw new FlowLoadError(typeof name === 'string' ? name : '<unknown>', parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`));
|
|
77
|
+
}
|
|
78
|
+
const def = parsed.data;
|
|
79
|
+
const issues = validateFlow(def);
|
|
80
|
+
if (issues.length > 0)
|
|
81
|
+
throw new FlowLoadError(def.flow, issues);
|
|
82
|
+
return def;
|
|
83
|
+
}
|
|
84
|
+
/** Loads and validates a single flow file. */
|
|
85
|
+
async function loadFlow(filePath) {
|
|
86
|
+
const content = await fs.readFile(filePath, 'utf-8');
|
|
87
|
+
return parseFlow(content);
|
|
88
|
+
}
|
|
89
|
+
/** Loads every `*.yaml` / `*.yml` in a directory. Throws on the first invalid flow. */
|
|
90
|
+
async function loadFlowsFromDir(dir) {
|
|
91
|
+
const entries = await fs.readdir(dir);
|
|
92
|
+
const files = entries
|
|
93
|
+
.filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
|
|
94
|
+
.sort();
|
|
95
|
+
const flows = [];
|
|
96
|
+
for (const file of files) {
|
|
97
|
+
flows.push(await loadFlow(path.join(dir, file)));
|
|
98
|
+
}
|
|
99
|
+
return flows;
|
|
100
|
+
}
|
|
101
|
+
// ── Semantic validation ───────────────────────────────────────────────────────
|
|
102
|
+
/** The semantic half of the validation: duplicate ids, unknown or self references, cycles, the trigger and the compensation selectors. */
|
|
103
|
+
function validateFlow(def) {
|
|
104
|
+
const issues = [];
|
|
105
|
+
const ids = new Set();
|
|
106
|
+
for (const step of def.steps) {
|
|
107
|
+
if (ids.has(step.id))
|
|
108
|
+
issues.push(`duplicate step id "${step.id}"`);
|
|
109
|
+
ids.add(step.id);
|
|
110
|
+
}
|
|
111
|
+
for (const step of def.steps) {
|
|
112
|
+
for (const dep of step.after) {
|
|
113
|
+
if (!ids.has(dep)) {
|
|
114
|
+
issues.push(`step "${step.id}" references unknown step "${dep}" in after`);
|
|
115
|
+
}
|
|
116
|
+
if (dep === step.id) {
|
|
117
|
+
issues.push(`step "${step.id}" cannot depend on itself`);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
if (step.gate?.evaluator && step.gate.evaluator === step.agent) {
|
|
121
|
+
issues.push(`step "${step.id}": gate evaluator "${step.gate.evaluator}" must differ from the executing agent (evaluador ≠ ejecutor)`);
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
issues.push(...detectCycles(def));
|
|
125
|
+
issues.push(...validateTrigger(def));
|
|
126
|
+
for (const comp of def.compensation) {
|
|
127
|
+
const stepId = comp.on.replace(/\.failed$/, '');
|
|
128
|
+
if (!ids.has(stepId)) {
|
|
129
|
+
issues.push(`compensation "on: ${comp.on}" references unknown step "${stepId}"`);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
return issues;
|
|
133
|
+
}
|
|
134
|
+
function detectCycles(def) {
|
|
135
|
+
const depMap = new Map(def.steps.map(s => [s.id, s.after]));
|
|
136
|
+
const visited = new Set();
|
|
137
|
+
const inStack = new Set();
|
|
138
|
+
const issues = [];
|
|
139
|
+
const dfs = (id) => {
|
|
140
|
+
if (inStack.has(id)) {
|
|
141
|
+
issues.push(`dependency cycle detected at step "${id}"`);
|
|
142
|
+
return;
|
|
143
|
+
}
|
|
144
|
+
if (visited.has(id))
|
|
145
|
+
return;
|
|
146
|
+
inStack.add(id);
|
|
147
|
+
for (const dep of depMap.get(id) ?? [])
|
|
148
|
+
dfs(dep);
|
|
149
|
+
inStack.delete(id);
|
|
150
|
+
visited.add(id);
|
|
151
|
+
};
|
|
152
|
+
for (const step of def.steps) {
|
|
153
|
+
if (issues.length > 0)
|
|
154
|
+
break;
|
|
155
|
+
dfs(step.id);
|
|
156
|
+
}
|
|
157
|
+
return issues;
|
|
158
|
+
}
|
|
159
|
+
function validateTrigger(def) {
|
|
160
|
+
const t = def.trigger;
|
|
161
|
+
switch (t.type) {
|
|
162
|
+
case 'queue':
|
|
163
|
+
return t.queue ? [] : ['trigger type "queue" requires a queue name'];
|
|
164
|
+
case 'webhook':
|
|
165
|
+
return t.path ? [] : ['trigger type "webhook" requires a path'];
|
|
166
|
+
case 'cron':
|
|
167
|
+
return t.schedule ? [] : ['trigger type "cron" requires a schedule'];
|
|
168
|
+
case 'manual':
|
|
169
|
+
return [];
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
//# sourceMappingURL=loader.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/flow/loader.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import type { StructuredChat, GenerateObjectOptions } from '../structured/generateObject';
|
|
2
|
+
import type { LLMProvider } from '../types';
|
|
3
|
+
import type { FlowDefinition } from './types';
|
|
4
|
+
export type { StructuredChat };
|
|
5
|
+
/**
|
|
6
|
+
* The planner (SPEC-0023 F6b): from a task and the agents available, a model produces a plan that becomes a `FlowDefinition`,
|
|
7
|
+
* ready for `runFlow`. A plan a model writes and a flow written in YAML are then the same object.
|
|
8
|
+
*
|
|
9
|
+
* The plan is validated before anything runs: duplicate ids, a dependency on an unknown step, an agent that does not exist
|
|
10
|
+
* and cycles are rejected, and the model is told what was wrong and asked again (`retries`). An agent id invented by the
|
|
11
|
+
* model would otherwise run as a no-op and look like success.
|
|
12
|
+
*/
|
|
13
|
+
export interface PlannerAgent {
|
|
14
|
+
id: string;
|
|
15
|
+
name?: string;
|
|
16
|
+
description?: string;
|
|
17
|
+
capabilities?: string[];
|
|
18
|
+
domain?: string;
|
|
19
|
+
/** Every step of this agent needs a person to review its output (`gate.approval: human`), whatever the model says. */
|
|
20
|
+
gate?: boolean;
|
|
21
|
+
/** Criteria the reviewer checks; added to those the model proposes. Only count when the step is gated. */
|
|
22
|
+
gateCriteria?: string[];
|
|
23
|
+
}
|
|
24
|
+
/** The marker for a needed capability no agent covers. The step stays in the flow and is reported in `unresolved`. */
|
|
25
|
+
export declare const UNRESOLVED_AGENT = "unresolved";
|
|
26
|
+
export interface PlanFlowOptions {
|
|
27
|
+
agents: PlannerAgent[];
|
|
28
|
+
/** The model: a provider, or any chat function (`StructuredChat`). One of the two. */
|
|
29
|
+
provider?: LLMProvider;
|
|
30
|
+
chat?: StructuredChat;
|
|
31
|
+
/** Knowledge the plan should take into account (retrieved by the caller). */
|
|
32
|
+
context?: string;
|
|
33
|
+
/** Policy text for the planner, e.g. a MANDATORY GATES section: which domains need a gate and with what criteria. */
|
|
34
|
+
policyContext?: string;
|
|
35
|
+
/** Name of the flow. Default: the summary the model wrote. */
|
|
36
|
+
flow?: string;
|
|
37
|
+
/** Extra attempts after an invalid plan, each told what was wrong. Default 1. */
|
|
38
|
+
retries?: number;
|
|
39
|
+
signal?: AbortSignal;
|
|
40
|
+
onMetrics?: GenerateObjectOptions['onMetrics'];
|
|
41
|
+
}
|
|
42
|
+
export interface PlannedFlow {
|
|
43
|
+
flow: FlowDefinition;
|
|
44
|
+
summary: string;
|
|
45
|
+
/** Steps the model could not assign to any agent (`agent_id: "unresolved"`). Empty when the plan is complete. */
|
|
46
|
+
unresolved: string[];
|
|
47
|
+
}
|
|
48
|
+
export declare const PLANNER_SYSTEM = "You are a task decomposition expert.\nGiven a task and a list of available specialist agents, produce a JSON execution plan.\n\nRules:\n- Use only agent IDs from the provided list.\n- depends_on: [] means the sub-task can start immediately; [\"t1\"] waits for t1 to finish.\n- If no agent matches a needed capability, use agent_id=\"unresolved\" and note the gap in the task.\n- Keep each task description focused and self-contained.\n- gate: set to true when a MANDATORY GATES section is present and the step's agent domain matches a governed domain. Always false otherwise.\n- gate_criteria: when gate is true, copy the suggested criteria from the MANDATORY GATES section verbatim and add any task-specific criteria that the human approver should verify.";
|
|
49
|
+
export declare function planFlow(task: string, opts: PlanFlowOptions): Promise<PlannedFlow>;
|
|
50
|
+
//# sourceMappingURL=planner.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/flow/planner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sHAAsH;IACtH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0GAA0G;IAC1G,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,sHAAsH;AACtH,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qHAAqH;IACrH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,iHAAiH;IACjH,UAAU,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,eAAO,MAAM,cAAc,yvBASyJ,CAAC;AAyDrL,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAiDxF"}
|