@deliverd/sdk 0.25.1 → 0.27.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 +104 -0
- 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 +395 -0
- package/dist/decision-token.d.ts +102 -0
- package/dist/decision-token.d.ts.map +1 -0
- package/dist/decision-token.js +139 -0
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +57 -2
- package/dist/gates.d.ts +2 -0
- package/dist/gates.d.ts.map +1 -1
- package/dist/gates.js +3 -0
- 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 +31 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +35 -0
- package/dist/messages.d.ts.map +1 -1
- package/dist/messages.js +4 -0
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +3803 -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 +656 -4
- package/dist/types.d.ts.map +1 -1
- package/package.json +2 -2
- 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 +536 -0
- package/src/decision-token.ts +184 -0
- package/src/dev.ts +63 -2
- package/src/gates.ts +3 -0
- package/src/governance.ts +204 -0
- package/src/index.ts +60 -0
- package/src/messages.ts +4 -0
- package/src/released.ts +3804 -0
- package/src/screen.ts +144 -0
- package/src/tasks.ts +88 -0
- package/src/types.ts +646 -4
package/README.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
You build the action. Deliverd handles the human.
|
|
4
4
|
|
|
5
|
+
> **Now published from a public repository. From 0.26.0, `@deliverd/sdk` is built and released from [deliverd-dev/deliverd-sdk](https://github.com/deliverd-dev/deliverd-sdk), Deliverd's public SDK repository, by GitHub Actions with npm's trusted publishing, so each release carries provenance linking it to the commit and workflow that built it. Versions up to 0.25.1 were published from a private repository under a single developer's account. Deliverd is growing, and as a company that supports open source it no longer made sense to keep it there: the source is now public, under the MIT licence. If npm shows a change of provenance or source repository at 0.26.0, this is why.**
|
|
6
|
+
|
|
5
7
|
```bash
|
|
6
8
|
npm install @deliverd/sdk
|
|
7
9
|
```
|
|
@@ -221,6 +223,43 @@ the handle exposed, for work that resumes on a webhook rather than in this call.
|
|
|
221
223
|
Try it before you have an account: `DELIVERD_DEV_OUTCOME=denied` rehearses a
|
|
222
224
|
policy refusal, which is the branch agents most often forget to write.
|
|
223
225
|
|
|
226
|
+
### Checking the yes where the action happens
|
|
227
|
+
|
|
228
|
+
A gate on its own is advisory: the agent asks, then acts. When the code that
|
|
229
|
+
actually performs the action is yours — the refund service, the deploy job —
|
|
230
|
+
make it check. Every gate that may be acted on carries `decisionToken`, the yes
|
|
231
|
+
signed with your deployment's Ed25519 key. Pass it along with the request, and
|
|
232
|
+
verify it against what you are about to do:
|
|
233
|
+
|
|
234
|
+
```ts
|
|
235
|
+
// In the agent
|
|
236
|
+
await fetch(REFUND_SERVICE, {
|
|
237
|
+
method: "POST",
|
|
238
|
+
headers: { "deliverd-decision": decision.decisionToken ?? "" },
|
|
239
|
+
body: JSON.stringify(decision.input),
|
|
240
|
+
});
|
|
241
|
+
|
|
242
|
+
// In the refund service
|
|
243
|
+
const check = await deliverd.decisionTokens.verify(req.headers["deliverd-decision"], {
|
|
244
|
+
action: "finance.refund",
|
|
245
|
+
input: req.body,
|
|
246
|
+
});
|
|
247
|
+
if (!check.ok) return res.status(403).json({ error: check.reason });
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
It refuses a token signed by any other key, an expired one (tokens last at most
|
|
251
|
+
fifteen minutes, and never past the permission's own window), one for another
|
|
252
|
+
action, and one agreed for a different input: a yes for £1200 does not cover
|
|
253
|
+
£1240. When the gate named a `destination` or an artifact, pass `destination`
|
|
254
|
+
and `artifactSha256` too. The public key is fetched once from
|
|
255
|
+
`/.well-known/deliverd-evidence-key` on the deployment the client talks to, and
|
|
256
|
+
the token must have been issued by that deployment. With the key already in
|
|
257
|
+
hand, `verifyDecisionToken(token, expected, { publicKey, issuer })` does the
|
|
258
|
+
same with no network at all.
|
|
259
|
+
|
|
260
|
+
A token does not count uses. Record the execution against the gate to spend
|
|
261
|
+
it, and the server refuses a second.
|
|
262
|
+
|
|
224
263
|
## Flows
|
|
225
264
|
|
|
226
265
|
A job that takes more than one of them is one job, and a firm asking about it
|
|
@@ -324,6 +363,47 @@ A finding of kind `decision` is a suggestion until a person confirms it.
|
|
|
324
363
|
`task.requestDecisionApproval(findingId)` puts it to somebody. Only a person
|
|
325
364
|
changes what a task is for; an agent proposes that as a finding too.
|
|
326
365
|
|
|
366
|
+
## Compliance Mode
|
|
367
|
+
|
|
368
|
+
On Business and Enterprise, a task can be governed: the AI system doing the
|
|
369
|
+
work, its purpose, owners, risk, data and oversight, the controls that follow
|
|
370
|
+
from them, and a gate that says whether the work may proceed.
|
|
371
|
+
|
|
372
|
+
```ts
|
|
373
|
+
const system = await deliverd.governance.aiSystems.register({
|
|
374
|
+
name: "Claims triage",
|
|
375
|
+
provider: "Anthropic",
|
|
376
|
+
model: "claude-opus",
|
|
377
|
+
promptHash: "sha256:9f2c…", // a digest, never the prompt
|
|
378
|
+
});
|
|
379
|
+
|
|
380
|
+
await task.govern({ aiSystemId: system.id, purpose: "Route claims", risk: "high", personalData: true });
|
|
381
|
+
await task.submitEvidence({ type: "model_evaluation", title: "Eval run", controls: ["model_evaluation"], results });
|
|
382
|
+
await task.requestControlApproval("deployment_approval");
|
|
383
|
+
|
|
384
|
+
const gate = await task.checkGovernanceGate({ action: "deploy" });
|
|
385
|
+
if (!gate.allowed) throw new Error(gate.reason);
|
|
386
|
+
|
|
387
|
+
const pack = await task.evidencePack(); // profile, controls, evidence, decisions, timeline, digest
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
`deliverd.governance` covers the organisation as a whole:
|
|
391
|
+
|
|
392
|
+
- `checkAuthority({ action })` says whether this agent may `send`, `deploy`,
|
|
393
|
+
`delete` and the rest on its own, only with approval, or not at all.
|
|
394
|
+
- `incidents.report()`, `get()`, `list()` and `draftReport()` record AI
|
|
395
|
+
incidents and draft the DORA reports a person signs off.
|
|
396
|
+
- `aiSystems.recordModelChange()` records a new model or prompt, and every
|
|
397
|
+
task that uses the system is reassessed. `task.triggerReassessment(reason)`
|
|
398
|
+
asks for one by hand.
|
|
399
|
+
- `frameworks()`, `frameworkMapping({ taskId })` and `createCustomFramework()`
|
|
400
|
+
show how requirements map onto controls. `ictRegister()` and `summary()`
|
|
401
|
+
are read-only views.
|
|
402
|
+
|
|
403
|
+
An agent can raise a risk or add facts. Only a person can lower them, set
|
|
404
|
+
thresholds, waive a control or resolve an incident. Every answer records
|
|
405
|
+
governance and certifies nothing.
|
|
406
|
+
|
|
327
407
|
## Evidence
|
|
328
408
|
|
|
329
409
|
Show your working. One call assembles the whole record of a piece of work —
|
|
@@ -696,6 +776,30 @@ import { runWithDeliverdApprovals } from "@deliverd/sdk/adapters";
|
|
|
696
776
|
const result = await runWithDeliverdApprovals((input) => run(agent, input), "Refund order 1042", { deliverd });
|
|
697
777
|
```
|
|
698
778
|
|
|
779
|
+
**Mastra** — mark tools `requireApproval: true` (or pass `requireToolApproval`), then:
|
|
780
|
+
|
|
781
|
+
```ts
|
|
782
|
+
import { generateWithDeliverdApprovals } from "@deliverd/sdk/adapters";
|
|
783
|
+
|
|
784
|
+
const output = await generateWithDeliverdApprovals(agent, agent.generate("Refund order 1042", { requireToolApproval: true }), { deliverd });
|
|
785
|
+
```
|
|
786
|
+
|
|
787
|
+
Each suspended call is approved with `agent.approveToolCallGenerate` or declined
|
|
788
|
+
with `agent.declineToolCallGenerate`, and the person's reason reaches the model.
|
|
789
|
+
|
|
790
|
+
**Muse Spark** (Meta Model API) — the loop runs the calls, so hand them over with the function that runs them:
|
|
791
|
+
|
|
792
|
+
```ts
|
|
793
|
+
import { runMuseFunctionCalls } from "@deliverd/sdk/adapters";
|
|
794
|
+
|
|
795
|
+
const results = await runMuseFunctionCalls(resp.output, runTool, { deliverd, when: (tool) => tool === "refund" });
|
|
796
|
+
resp = await muse.responses.create({ model: "muse-spark-1.1", input: results, tools, previous_response_id: resp.id });
|
|
797
|
+
```
|
|
798
|
+
|
|
799
|
+
Only approved calls run; a declined one's result tells the model a person said
|
|
800
|
+
no, and why. `runMuseToolCalls(message, runTool, { deliverd })` does the same
|
|
801
|
+
for Chat Completions' `tool_calls`.
|
|
802
|
+
|
|
699
803
|
**LangGraph** — pause the graph rather than a process, and resume it from the callback:
|
|
700
804
|
|
|
701
805
|
```ts
|
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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"}
|