@deliverd/sdk 0.25.0 → 0.26.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 +82 -3
- package/dist/adapters/index.d.ts +4 -0
- package/dist/adapters/index.d.ts.map +1 -1
- package/dist/adapters/index.js +2 -0
- package/dist/adapters/mastra.d.ts +81 -0
- package/dist/adapters/mastra.d.ts.map +1 -0
- package/dist/adapters/mastra.js +54 -0
- package/dist/adapters/muse-spark.d.ts +79 -0
- package/dist/adapters/muse-spark.d.ts.map +1 -0
- package/dist/adapters/muse-spark.js +59 -0
- package/dist/adapters/shared.d.ts +2 -1
- package/dist/adapters/shared.d.ts.map +1 -1
- package/dist/data-screen.d.ts +233 -0
- package/dist/data-screen.d.ts.map +1 -0
- package/dist/data-screen.js +389 -0
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +42 -2
- package/dist/governance.d.ts +94 -0
- package/dist/governance.d.ts.map +1 -0
- package/dist/governance.js +166 -0
- package/dist/index.d.ts +27 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +30 -0
- package/dist/messages.d.ts +2 -0
- package/dist/messages.d.ts.map +1 -1
- package/dist/messages.js +8 -1
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +2184 -0
- package/dist/screen.d.ts +85 -0
- package/dist/screen.d.ts.map +1 -0
- package/dist/screen.js +69 -0
- package/dist/tasks.d.ts +38 -1
- package/dist/tasks.d.ts.map +1 -1
- package/dist/tasks.js +67 -0
- package/dist/types.d.ts +589 -3
- package/dist/types.d.ts.map +1 -1
- package/package.json +5 -5
- package/src/adapters/index.ts +11 -0
- package/src/adapters/mastra.ts +118 -0
- package/src/adapters/muse-spark.ts +147 -0
- package/src/adapters/shared.ts +2 -1
- package/src/data-screen.ts +533 -0
- package/src/dev.ts +45 -2
- package/src/governance.ts +204 -0
- package/src/index.ts +43 -0
- package/src/messages.ts +10 -1
- package/src/released.ts +2184 -0
- package/src/screen.ts +144 -0
- package/src/tasks.ts +88 -0
- package/src/types.ts +577 -3
package/README.md
CHANGED
|
@@ -23,6 +23,18 @@ Your approver gets an email and a notification, opens a page that works on a
|
|
|
23
23
|
phone, and approves, rejects with a reason, or asks your agent a question.
|
|
24
24
|
Every step is on the record.
|
|
25
25
|
|
|
26
|
+
## Start free
|
|
27
|
+
|
|
28
|
+
1. [Create a free Deliverd account](https://deliverd.dev/sign-up?utm_source=npm&utm_medium=package&utm_campaign=sdk&utm_content=readme).
|
|
29
|
+
The Free plan needs no card.
|
|
30
|
+
2. Name your organisation. The next page hands you a key: set it as
|
|
31
|
+
`DELIVERD_API_KEY`.
|
|
32
|
+
3. Run the five lines above. Leave `approvers` out and the request goes to
|
|
33
|
+
your organisation's owners and admins; name anyone else in it to ask them.
|
|
34
|
+
|
|
35
|
+
Want to see it work before you sign up? Development mode, next, needs no key
|
|
36
|
+
and no network.
|
|
37
|
+
|
|
26
38
|
## Before you have an account
|
|
27
39
|
|
|
28
40
|
```ts
|
|
@@ -312,6 +324,47 @@ A finding of kind `decision` is a suggestion until a person confirms it.
|
|
|
312
324
|
`task.requestDecisionApproval(findingId)` puts it to somebody. Only a person
|
|
313
325
|
changes what a task is for; an agent proposes that as a finding too.
|
|
314
326
|
|
|
327
|
+
## Compliance Mode
|
|
328
|
+
|
|
329
|
+
On Business and Enterprise, a task can be governed: the AI system doing the
|
|
330
|
+
work, its purpose, owners, risk, data and oversight, the controls that follow
|
|
331
|
+
from them, and a gate that says whether the work may proceed.
|
|
332
|
+
|
|
333
|
+
```ts
|
|
334
|
+
const system = await deliverd.governance.aiSystems.register({
|
|
335
|
+
name: "Claims triage",
|
|
336
|
+
provider: "Anthropic",
|
|
337
|
+
model: "claude-opus",
|
|
338
|
+
promptHash: "sha256:9f2c…", // a digest, never the prompt
|
|
339
|
+
});
|
|
340
|
+
|
|
341
|
+
await task.govern({ aiSystemId: system.id, purpose: "Route claims", risk: "high", personalData: true });
|
|
342
|
+
await task.submitEvidence({ type: "model_evaluation", title: "Eval run", controls: ["model_evaluation"], results });
|
|
343
|
+
await task.requestControlApproval("deployment_approval");
|
|
344
|
+
|
|
345
|
+
const gate = await task.checkGovernanceGate({ action: "deploy" });
|
|
346
|
+
if (!gate.allowed) throw new Error(gate.reason);
|
|
347
|
+
|
|
348
|
+
const pack = await task.evidencePack(); // profile, controls, evidence, decisions, timeline, digest
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
`deliverd.governance` covers the organisation as a whole:
|
|
352
|
+
|
|
353
|
+
- `checkAuthority({ action })` says whether this agent may `send`, `deploy`,
|
|
354
|
+
`delete` and the rest on its own, only with approval, or not at all.
|
|
355
|
+
- `incidents.report()`, `get()`, `list()` and `draftReport()` record AI
|
|
356
|
+
incidents and draft the DORA reports a person signs off.
|
|
357
|
+
- `aiSystems.recordModelChange()` records a new model or prompt, and every
|
|
358
|
+
task that uses the system is reassessed. `task.triggerReassessment(reason)`
|
|
359
|
+
asks for one by hand.
|
|
360
|
+
- `frameworks()`, `frameworkMapping({ taskId })` and `createCustomFramework()`
|
|
361
|
+
show how requirements map onto controls. `ictRegister()` and `summary()`
|
|
362
|
+
are read-only views.
|
|
363
|
+
|
|
364
|
+
An agent can raise a risk or add facts. Only a person can lower them, set
|
|
365
|
+
thresholds, waive a control or resolve an incident. Every answer records
|
|
366
|
+
governance and certifies nothing.
|
|
367
|
+
|
|
315
368
|
## Evidence
|
|
316
369
|
|
|
317
370
|
Show your working. One call assembles the whole record of a piece of work —
|
|
@@ -684,6 +737,30 @@ import { runWithDeliverdApprovals } from "@deliverd/sdk/adapters";
|
|
|
684
737
|
const result = await runWithDeliverdApprovals((input) => run(agent, input), "Refund order 1042", { deliverd });
|
|
685
738
|
```
|
|
686
739
|
|
|
740
|
+
**Mastra** — mark tools `requireApproval: true` (or pass `requireToolApproval`), then:
|
|
741
|
+
|
|
742
|
+
```ts
|
|
743
|
+
import { generateWithDeliverdApprovals } from "@deliverd/sdk/adapters";
|
|
744
|
+
|
|
745
|
+
const output = await generateWithDeliverdApprovals(agent, agent.generate("Refund order 1042", { requireToolApproval: true }), { deliverd });
|
|
746
|
+
```
|
|
747
|
+
|
|
748
|
+
Each suspended call is approved with `agent.approveToolCallGenerate` or declined
|
|
749
|
+
with `agent.declineToolCallGenerate`, and the person's reason reaches the model.
|
|
750
|
+
|
|
751
|
+
**Muse Spark** (Meta Model API) — the loop runs the calls, so hand them over with the function that runs them:
|
|
752
|
+
|
|
753
|
+
```ts
|
|
754
|
+
import { runMuseFunctionCalls } from "@deliverd/sdk/adapters";
|
|
755
|
+
|
|
756
|
+
const results = await runMuseFunctionCalls(resp.output, runTool, { deliverd, when: (tool) => tool === "refund" });
|
|
757
|
+
resp = await muse.responses.create({ model: "muse-spark-1.1", input: results, tools, previous_response_id: resp.id });
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
Only approved calls run; a declined one's result tells the model a person said
|
|
761
|
+
no, and why. `runMuseToolCalls(message, runTool, { deliverd })` does the same
|
|
762
|
+
for Chat Completions' `tool_calls`.
|
|
763
|
+
|
|
687
764
|
**LangGraph** — pause the graph rather than a process, and resume it from the callback:
|
|
688
765
|
|
|
689
766
|
```ts
|
|
@@ -764,11 +841,13 @@ Zero dependencies. Node 20 or later.
|
|
|
764
841
|
|
|
765
842
|
## Also
|
|
766
843
|
|
|
844
|
+
- [Create a free account](https://deliverd.dev/sign-up?utm_source=npm&utm_medium=package&utm_campaign=sdk&utm_content=readme), if
|
|
845
|
+
you have not yet.
|
|
767
846
|
- The same walkthrough as a page, if you would rather read it there:
|
|
768
|
-
|
|
769
|
-
- The API reference:
|
|
847
|
+
[deliverd.dev/quickstart](https://deliverd.dev/quickstart?utm_source=npm&utm_medium=package&utm_campaign=sdk&utm_content=readme)
|
|
848
|
+
- The API reference: [deliverd.dev/docs/api](https://deliverd.dev/docs/api?utm_source=npm&utm_medium=package&utm_campaign=sdk&utm_content=readme)
|
|
770
849
|
- MCP, if your agent speaks it rather than TypeScript:
|
|
771
|
-
|
|
850
|
+
[deliverd.dev/docs/developers/mcp](https://deliverd.dev/docs/developers/mcp?utm_source=npm&utm_medium=package&utm_campaign=sdk&utm_content=readme)
|
|
772
851
|
- The CLI, for a terminal or a CI job: `npm install -g deliverd`
|
|
773
852
|
|
|
774
853
|
MIT.
|
package/dist/adapters/index.d.ts
CHANGED
|
@@ -14,6 +14,10 @@ export { resolveInterruptions, runWithDeliverdApprovals } from "./openai-agents.
|
|
|
14
14
|
export type { OpenAiApprovalItem, OpenAiInterruptedResult } from "./openai-agents.js";
|
|
15
15
|
export { approveInGraph, resumeFromCallback } from "./langgraph.js";
|
|
16
16
|
export type { DeliverdInterruptValue, GraphApprovalRecord, GraphApprover, GraphDecision } from "./langgraph.js";
|
|
17
|
+
export { generateWithDeliverdApprovals, pendingMastraApproval, resolveMastraApproval } from "./mastra.js";
|
|
18
|
+
export type { MastraApprovingAgent, MastraOutput } from "./mastra.js";
|
|
19
|
+
export { runMuseFunctionCalls, runMuseToolCalls } from "./muse-spark.js";
|
|
20
|
+
export type { MuseFunctionCall, MuseFunctionCallOutput, MuseToolApprovalOptions, MuseToolCall, MuseToolMessage, MuseToolRunner, } from "./muse-spark.js";
|
|
17
21
|
export { defaultDescription, DEFAULT_TOOL_EXPIRY } from "./shared.js";
|
|
18
22
|
export type { Approver, CallDescription, CallOutcome, ToolApprovalOptions } from "./shared.js";
|
|
19
23
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChH,OAAO,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1G,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACzE,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,YAAY,EACZ,eAAe,EACf,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
|
package/dist/adapters/index.js
CHANGED
|
@@ -10,4 +10,6 @@ export { deliverdCanUseTool } from "./claude-agent-sdk.js";
|
|
|
10
10
|
export { deliverdToolApproval } from "./ai-sdk.js";
|
|
11
11
|
export { resolveInterruptions, runWithDeliverdApprovals } from "./openai-agents.js";
|
|
12
12
|
export { approveInGraph, resumeFromCallback } from "./langgraph.js";
|
|
13
|
+
export { generateWithDeliverdApprovals, pendingMastraApproval, resolveMastraApproval } from "./mastra.js";
|
|
14
|
+
export { runMuseFunctionCalls, runMuseToolCalls } from "./muse-spark.js";
|
|
13
15
|
export { defaultDescription, DEFAULT_TOOL_EXPIRY } from "./shared.js";
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import { type ToolApprovalOptions } from "./shared.js";
|
|
2
|
+
/**
|
|
3
|
+
* Mastra: a person approves an agent's tool calls, through Deliverd.
|
|
4
|
+
*
|
|
5
|
+
* Mark the tools that need a person as Mastra already has you do —
|
|
6
|
+
* `createTool({ requireApproval: true })`, or `requireToolApproval` on the
|
|
7
|
+
* call — and a run that reaches one stops with `finishReason: "suspended"`.
|
|
8
|
+
* Instead of building your own prompt:
|
|
9
|
+
*
|
|
10
|
+
* ```ts
|
|
11
|
+
* import { Deliverd } from "@deliverd/sdk";
|
|
12
|
+
* import { generateWithDeliverdApprovals } from "@deliverd/sdk/adapters";
|
|
13
|
+
*
|
|
14
|
+
* const output = await generateWithDeliverdApprovals(
|
|
15
|
+
* agent,
|
|
16
|
+
* agent.generate("Refund order 1042", { requireToolApproval: true }),
|
|
17
|
+
* { deliverd: new Deliverd(), approvers: ["finance"] }
|
|
18
|
+
* );
|
|
19
|
+
* console.log(output.text);
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* Each suspended call becomes a request in Deliverd. Approved, it is
|
|
23
|
+
* `agent.approveToolCallGenerate({ runId, toolCallId })` and the tool runs;
|
|
24
|
+
* declined, it is `agent.declineToolCallGenerate({ runId, toolCallId, reason })`
|
|
25
|
+
* and Mastra hands the person's reason to the model in place of its default
|
|
26
|
+
* "not approved". The run resumes until nothing is waiting on a person.
|
|
27
|
+
* `resolveMastraApproval` does one round, for a loop you own.
|
|
28
|
+
*
|
|
29
|
+
* A run suspended by a tool's own `suspend()` — waiting on data, not on a
|
|
30
|
+
* yes or no — is returned as it is, for you to resume.
|
|
31
|
+
*
|
|
32
|
+
* Shapes follow `@mastra/core` 1.78.0's type definitions:
|
|
33
|
+
* `Agent.approveToolCallGenerate` and `Agent.declineToolCallGenerate` in
|
|
34
|
+
* `dist/agent/agent.d.ts`; `FullOutput`'s `finishReason`, `runId` and
|
|
35
|
+
* `suspendPayload` in `dist/stream/base/output.d.ts`; and the payload of a
|
|
36
|
+
* `tool-call-approval` chunk, `ToolCallApprovalPayload` (`toolCallId`,
|
|
37
|
+
* `toolName`, `args`), against `ToolCallSuspendedPayload`, which also carries
|
|
38
|
+
* the tool's own `suspendPayload`, in `dist/stream/types.d.ts`.
|
|
39
|
+
*/
|
|
40
|
+
/** The part of a Mastra generate output this adapter reads. */
|
|
41
|
+
export interface MastraOutput {
|
|
42
|
+
finishReason?: string;
|
|
43
|
+
runId?: string;
|
|
44
|
+
/** For an approval: `{ toolCallId, toolName, args }`. */
|
|
45
|
+
suspendPayload?: unknown;
|
|
46
|
+
}
|
|
47
|
+
/** The part of a Mastra `Agent` this adapter calls. */
|
|
48
|
+
export interface MastraApprovingAgent<Output extends MastraOutput = MastraOutput> {
|
|
49
|
+
approveToolCallGenerate(options: {
|
|
50
|
+
runId: string;
|
|
51
|
+
toolCallId?: string;
|
|
52
|
+
}): Promise<Output>;
|
|
53
|
+
declineToolCallGenerate(options: {
|
|
54
|
+
runId: string;
|
|
55
|
+
toolCallId?: string;
|
|
56
|
+
reason?: string;
|
|
57
|
+
}): Promise<Output>;
|
|
58
|
+
}
|
|
59
|
+
/** The tool call a suspended output is waiting on a person for, or null when it is not. */
|
|
60
|
+
export declare function pendingMastraApproval(output: MastraOutput): {
|
|
61
|
+
runId: string;
|
|
62
|
+
toolCallId: string;
|
|
63
|
+
toolName: string;
|
|
64
|
+
args: unknown;
|
|
65
|
+
} | null;
|
|
66
|
+
/**
|
|
67
|
+
* Decide the call a suspended output is waiting on, and resume the run.
|
|
68
|
+
* Returns the resumed run's output, or null when nothing was waiting on a
|
|
69
|
+
* person.
|
|
70
|
+
*/
|
|
71
|
+
export declare function resolveMastraApproval<Output extends MastraOutput>(agent: MastraApprovingAgent<Output>, output: MastraOutput, options: ToolApprovalOptions): Promise<Output | null>;
|
|
72
|
+
/**
|
|
73
|
+
* Resume a Mastra run until nothing is waiting on a person.
|
|
74
|
+
*
|
|
75
|
+
* `first` is the output of `agent.generate(…)`, or the promise of it. A cap
|
|
76
|
+
* on rounds stops an agent that keeps asking from waiting forever.
|
|
77
|
+
*/
|
|
78
|
+
export declare function generateWithDeliverdApprovals<Output extends MastraOutput>(agent: MastraApprovingAgent<Output>, first: Output | Promise<Output>, options: ToolApprovalOptions & {
|
|
79
|
+
maxRounds?: number;
|
|
80
|
+
}): Promise<Output>;
|
|
81
|
+
//# sourceMappingURL=mastra.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mastra.d.ts","sourceRoot":"","sources":["../../src/adapters/mastra.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IAC9E,uBAAuB,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1F,uBAAuB,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5G;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,GACnB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAa/E;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,SAAS,YAAY,EACrE,KAAK,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACnC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxB;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,MAAM,SAAS,YAAY,EAC7E,KAAK,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACnC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAC/B,OAAO,EAAE,mBAAmB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,OAAO,CAAC,MAAM,CAAC,CAYjB"}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import { askAboutCall } from "./shared.js";
|
|
2
|
+
/** The tool call a suspended output is waiting on a person for, or null when it is not. */
|
|
3
|
+
export function pendingMastraApproval(output) {
|
|
4
|
+
if (output.finishReason !== "suspended" || !output.runId)
|
|
5
|
+
return null;
|
|
6
|
+
const payload = output.suspendPayload;
|
|
7
|
+
if (typeof payload !== "object" || payload === null)
|
|
8
|
+
return null;
|
|
9
|
+
const { toolCallId, toolName, args } = payload;
|
|
10
|
+
// A tool that called suspend() is waiting on data, not on a decision.
|
|
11
|
+
if ("suspendPayload" in payload || typeof toolCallId !== "string")
|
|
12
|
+
return null;
|
|
13
|
+
return {
|
|
14
|
+
runId: output.runId,
|
|
15
|
+
toolCallId,
|
|
16
|
+
toolName: typeof toolName === "string" ? toolName : "a tool",
|
|
17
|
+
args: args ?? {},
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Decide the call a suspended output is waiting on, and resume the run.
|
|
22
|
+
* Returns the resumed run's output, or null when nothing was waiting on a
|
|
23
|
+
* person.
|
|
24
|
+
*/
|
|
25
|
+
export async function resolveMastraApproval(agent, output, options) {
|
|
26
|
+
const pending = pendingMastraApproval(output);
|
|
27
|
+
if (!pending)
|
|
28
|
+
return null;
|
|
29
|
+
const { runId, toolCallId, toolName, args } = pending;
|
|
30
|
+
if (options.when && !(await options.when(toolName, args))) {
|
|
31
|
+
return agent.approveToolCallGenerate({ runId, toolCallId });
|
|
32
|
+
}
|
|
33
|
+
const outcome = await askAboutCall(toolName, args, `mastra:${runId}:${toolCallId}`, options);
|
|
34
|
+
return outcome.allowed
|
|
35
|
+
? agent.approveToolCallGenerate({ runId, toolCallId })
|
|
36
|
+
: agent.declineToolCallGenerate({ runId, toolCallId, reason: outcome.reason });
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Resume a Mastra run until nothing is waiting on a person.
|
|
40
|
+
*
|
|
41
|
+
* `first` is the output of `agent.generate(…)`, or the promise of it. A cap
|
|
42
|
+
* on rounds stops an agent that keeps asking from waiting forever.
|
|
43
|
+
*/
|
|
44
|
+
export async function generateWithDeliverdApprovals(agent, first, options) {
|
|
45
|
+
const maxRounds = options.maxRounds ?? 10;
|
|
46
|
+
let output = await first;
|
|
47
|
+
for (let round = 0; pendingMastraApproval(output); round++) {
|
|
48
|
+
if (round >= maxRounds) {
|
|
49
|
+
throw new Error(`The run was still waiting for approval after ${maxRounds} rounds; stopping rather than asking forever.`);
|
|
50
|
+
}
|
|
51
|
+
output = (await resolveMastraApproval(agent, output, options));
|
|
52
|
+
}
|
|
53
|
+
return output;
|
|
54
|
+
}
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { type ToolApprovalOptions } from "./shared.js";
|
|
2
|
+
/**
|
|
3
|
+
* Meta's Muse Spark, on the Meta Model API: a person approves the function
|
|
4
|
+
* calls a response asks for, and only the approved ones run.
|
|
5
|
+
*
|
|
6
|
+
* Muse Spark has no approval hook of its own. A response lists the calls the
|
|
7
|
+
* model wants made and your loop makes them, so the loop is where a person
|
|
8
|
+
* comes in. Hand the calls to Deliverd with the function that runs them:
|
|
9
|
+
*
|
|
10
|
+
* ```ts
|
|
11
|
+
* import OpenAI from "openai";
|
|
12
|
+
* import { Deliverd } from "@deliverd/sdk";
|
|
13
|
+
* import { runMuseFunctionCalls } from "@deliverd/sdk/adapters";
|
|
14
|
+
*
|
|
15
|
+
* const muse = new OpenAI({ baseURL: "https://api.meta.ai/v1", apiKey: process.env.MODEL_API_KEY });
|
|
16
|
+
* let resp = await muse.responses.create({ model: "muse-spark-1.1", input, tools });
|
|
17
|
+
* const results = await runMuseFunctionCalls(resp.output, runTool, {
|
|
18
|
+
* deliverd: new Deliverd(),
|
|
19
|
+
* when: (tool) => tool === "refund",
|
|
20
|
+
* approvers: ["finance"],
|
|
21
|
+
* });
|
|
22
|
+
* resp = await muse.responses.create({ model: "muse-spark-1.1", input: results, tools, previous_response_id: resp.id });
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* `runMuseFunctionCalls` reads the Responses API's `function_call` items and
|
|
26
|
+
* returns its `function_call_output` items; `runMuseToolCalls` reads a Chat
|
|
27
|
+
* Completions message's `tool_calls` and returns `role: "tool"` messages.
|
|
28
|
+
* A declined call is not run: its result is a sentence telling the model a
|
|
29
|
+
* person said no, and why, so the model changes course instead of the run
|
|
30
|
+
* crashing. Both shapes are the OpenAI-compatible ones Meta's Model API
|
|
31
|
+
* serves, so they work for any endpoint that speaks them.
|
|
32
|
+
*/
|
|
33
|
+
export interface MuseToolApprovalOptions extends ToolApprovalOptions {
|
|
34
|
+
/**
|
|
35
|
+
* Fields of a call's arguments the approver may correct before approving,
|
|
36
|
+
* per tool: `editable: (tool) => tool === "refund" ? ["amount"] : []`. The
|
|
37
|
+
* call then runs with what they approved rather than what the model asked.
|
|
38
|
+
*/
|
|
39
|
+
editable?: (toolName: string, input: Record<string, unknown>) => string[];
|
|
40
|
+
}
|
|
41
|
+
/** Runs one call: the tool's name and its parsed arguments. A string result is passed on as it is; anything else as JSON. */
|
|
42
|
+
export type MuseToolRunner = (toolName: string, input: unknown) => unknown | Promise<unknown>;
|
|
43
|
+
/** A Responses API output item asking for a function call. */
|
|
44
|
+
export interface MuseFunctionCall {
|
|
45
|
+
type: "function_call";
|
|
46
|
+
call_id: string;
|
|
47
|
+
name: string;
|
|
48
|
+
arguments: string;
|
|
49
|
+
}
|
|
50
|
+
/** What goes back as the next request's `input`, one per call. */
|
|
51
|
+
export interface MuseFunctionCallOutput {
|
|
52
|
+
type: "function_call_output";
|
|
53
|
+
call_id: string;
|
|
54
|
+
output: string;
|
|
55
|
+
}
|
|
56
|
+
/** A Chat Completions tool call, from `choices[0].message.tool_calls`. */
|
|
57
|
+
export interface MuseToolCall {
|
|
58
|
+
id: string;
|
|
59
|
+
type?: string;
|
|
60
|
+
function: {
|
|
61
|
+
name: string;
|
|
62
|
+
arguments: string;
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
/** The `role: "tool"` message answering one tool call. */
|
|
66
|
+
export interface MuseToolMessage {
|
|
67
|
+
role: "tool";
|
|
68
|
+
tool_call_id: string;
|
|
69
|
+
content: string;
|
|
70
|
+
}
|
|
71
|
+
/** Ask about, and run, every `function_call` in a Responses API output. Other items are ignored. */
|
|
72
|
+
export declare function runMuseFunctionCalls(output: readonly {
|
|
73
|
+
type?: string;
|
|
74
|
+
}[], run: MuseToolRunner, options: MuseToolApprovalOptions): Promise<MuseFunctionCallOutput[]>;
|
|
75
|
+
/** Ask about, and run, every tool call on a Chat Completions message. */
|
|
76
|
+
export declare function runMuseToolCalls(message: {
|
|
77
|
+
tool_calls?: readonly MuseToolCall[] | null;
|
|
78
|
+
}, run: MuseToolRunner, options: MuseToolApprovalOptions): Promise<MuseToolMessage[]>;
|
|
79
|
+
//# sourceMappingURL=muse-spark.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"muse-spark.d.ts","sourceRoot":"","sources":["../../src/adapters/muse-spark.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;CAC3E;AAED,6HAA6H;AAC7H,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9F,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oGAAoG;AACpG,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,EACpC,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAYnC;AAED,yEAAyE;AACzE,wBAAsB,gBAAgB,CACpC,OAAO,EAAE;IAAE,UAAU,CAAC,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI,CAAA;CAAE,EACxD,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,eAAe,EAAE,CAAC,CAU5B"}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { askAboutCall } from "./shared.js";
|
|
2
|
+
/** Ask about, and run, every `function_call` in a Responses API output. Other items are ignored. */
|
|
3
|
+
export async function runMuseFunctionCalls(output, run, options) {
|
|
4
|
+
const results = [];
|
|
5
|
+
for (const item of output) {
|
|
6
|
+
if (item.type !== "function_call")
|
|
7
|
+
continue;
|
|
8
|
+
const call = item;
|
|
9
|
+
results.push({
|
|
10
|
+
type: "function_call_output",
|
|
11
|
+
call_id: call.call_id,
|
|
12
|
+
output: await approveAndRun(call.name, call.arguments, call.call_id, run, options),
|
|
13
|
+
});
|
|
14
|
+
}
|
|
15
|
+
return results;
|
|
16
|
+
}
|
|
17
|
+
/** Ask about, and run, every tool call on a Chat Completions message. */
|
|
18
|
+
export async function runMuseToolCalls(message, run, options) {
|
|
19
|
+
const results = [];
|
|
20
|
+
for (const call of message.tool_calls ?? []) {
|
|
21
|
+
results.push({
|
|
22
|
+
role: "tool",
|
|
23
|
+
tool_call_id: call.id,
|
|
24
|
+
content: await approveAndRun(call.function.name, call.function.arguments, call.id, run, options),
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
return results;
|
|
28
|
+
}
|
|
29
|
+
async function approveAndRun(toolName, rawArguments, callId, run, options) {
|
|
30
|
+
const input = parseArguments(rawArguments);
|
|
31
|
+
if (!options.when || (await options.when(toolName, input))) {
|
|
32
|
+
const editable = typeof input === "object" && input !== null && !Array.isArray(input)
|
|
33
|
+
? options.editable?.(toolName, input)
|
|
34
|
+
: undefined;
|
|
35
|
+
// The call id makes the ask idempotent: a loop that is retried, or a
|
|
36
|
+
// process restarted mid-wait, finds the request it already made.
|
|
37
|
+
const outcome = await askAboutCall(toolName, input, `muse-spark:${callId}`, options, undefined, editable);
|
|
38
|
+
if (!outcome.allowed)
|
|
39
|
+
return outcome.reason;
|
|
40
|
+
// What was approved runs, which is the proposal unless a person corrected it.
|
|
41
|
+
return render(await run(toolName, outcome.input ?? input));
|
|
42
|
+
}
|
|
43
|
+
return render(await run(toolName, input));
|
|
44
|
+
}
|
|
45
|
+
function render(result) {
|
|
46
|
+
if (typeof result === "string")
|
|
47
|
+
return result;
|
|
48
|
+
return JSON.stringify(result ?? null);
|
|
49
|
+
}
|
|
50
|
+
function parseArguments(raw) {
|
|
51
|
+
if (!raw)
|
|
52
|
+
return {};
|
|
53
|
+
try {
|
|
54
|
+
return JSON.parse(raw);
|
|
55
|
+
}
|
|
56
|
+
catch {
|
|
57
|
+
return raw;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
@@ -6,7 +6,8 @@ import type { ApprovalFactor, ApprovalRisk, Decision, FieldChange } from "../typ
|
|
|
6
6
|
*
|
|
7
7
|
* The adapters are written against each framework's own hook — the Claude
|
|
8
8
|
* Agent SDK's `canUseTool`, the AI SDK's `toolApproval`, the OpenAI Agents
|
|
9
|
-
* SDK's interruptions, LangGraph's `interrupt
|
|
9
|
+
* SDK's interruptions, LangGraph's `interrupt`, Mastra's suspended tool
|
|
10
|
+
* approvals, the function calls in a Muse Spark response — by shape rather than by
|
|
10
11
|
* import, so `@deliverd/sdk` keeps its promise of no dependencies. Each
|
|
11
12
|
* shape was taken from that framework's published type definitions and is
|
|
12
13
|
* checked against them in this package's tests.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/adapters/shared.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvF
|
|
1
|
+
{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/adapters/shared.ts"],"names":[],"mappings":"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"}
|