@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.
Files changed (58) hide show
  1. package/README.md +104 -0
  2. package/dist/adapters/index.d.ts +4 -0
  3. package/dist/adapters/index.d.ts.map +1 -1
  4. package/dist/adapters/index.js +2 -0
  5. package/dist/adapters/mastra.d.ts +81 -0
  6. package/dist/adapters/mastra.d.ts.map +1 -0
  7. package/dist/adapters/mastra.js +54 -0
  8. package/dist/adapters/muse-spark.d.ts +79 -0
  9. package/dist/adapters/muse-spark.d.ts.map +1 -0
  10. package/dist/adapters/muse-spark.js +59 -0
  11. package/dist/adapters/shared.d.ts +2 -1
  12. package/dist/adapters/shared.d.ts.map +1 -1
  13. package/dist/data-screen.d.ts +233 -0
  14. package/dist/data-screen.d.ts.map +1 -0
  15. package/dist/data-screen.js +395 -0
  16. package/dist/decision-token.d.ts +102 -0
  17. package/dist/decision-token.d.ts.map +1 -0
  18. package/dist/decision-token.js +139 -0
  19. package/dist/dev.d.ts.map +1 -1
  20. package/dist/dev.js +57 -2
  21. package/dist/gates.d.ts +2 -0
  22. package/dist/gates.d.ts.map +1 -1
  23. package/dist/gates.js +3 -0
  24. package/dist/governance.d.ts +94 -0
  25. package/dist/governance.d.ts.map +1 -0
  26. package/dist/governance.js +166 -0
  27. package/dist/index.d.ts +31 -0
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +35 -0
  30. package/dist/messages.d.ts.map +1 -1
  31. package/dist/messages.js +4 -0
  32. package/dist/released.d.ts +1 -1
  33. package/dist/released.d.ts.map +1 -1
  34. package/dist/released.js +3803 -0
  35. package/dist/screen.d.ts +85 -0
  36. package/dist/screen.d.ts.map +1 -0
  37. package/dist/screen.js +69 -0
  38. package/dist/tasks.d.ts +38 -1
  39. package/dist/tasks.d.ts.map +1 -1
  40. package/dist/tasks.js +67 -0
  41. package/dist/types.d.ts +656 -4
  42. package/dist/types.d.ts.map +1 -1
  43. package/package.json +2 -2
  44. package/src/adapters/index.ts +11 -0
  45. package/src/adapters/mastra.ts +118 -0
  46. package/src/adapters/muse-spark.ts +147 -0
  47. package/src/adapters/shared.ts +2 -1
  48. package/src/data-screen.ts +536 -0
  49. package/src/decision-token.ts +184 -0
  50. package/src/dev.ts +63 -2
  51. package/src/gates.ts +3 -0
  52. package/src/governance.ts +204 -0
  53. package/src/index.ts +60 -0
  54. package/src/messages.ts +4 -0
  55. package/src/released.ts +3804 -0
  56. package/src/screen.ts +144 -0
  57. package/src/tasks.ts +88 -0
  58. 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
@@ -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"}
@@ -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` — by shape rather than by
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":"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"}
1
+ {"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/adapters/shared.ts"],"names":[],"mappings":"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"}