@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.
Files changed (51) hide show
  1. package/README.md +82 -3
  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 +389 -0
  16. package/dist/dev.d.ts.map +1 -1
  17. package/dist/dev.js +42 -2
  18. package/dist/governance.d.ts +94 -0
  19. package/dist/governance.d.ts.map +1 -0
  20. package/dist/governance.js +166 -0
  21. package/dist/index.d.ts +27 -0
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +30 -0
  24. package/dist/messages.d.ts +2 -0
  25. package/dist/messages.d.ts.map +1 -1
  26. package/dist/messages.js +8 -1
  27. package/dist/released.d.ts +1 -1
  28. package/dist/released.d.ts.map +1 -1
  29. package/dist/released.js +2184 -0
  30. package/dist/screen.d.ts +85 -0
  31. package/dist/screen.d.ts.map +1 -0
  32. package/dist/screen.js +69 -0
  33. package/dist/tasks.d.ts +38 -1
  34. package/dist/tasks.d.ts.map +1 -1
  35. package/dist/tasks.js +67 -0
  36. package/dist/types.d.ts +589 -3
  37. package/dist/types.d.ts.map +1 -1
  38. package/package.json +5 -5
  39. package/src/adapters/index.ts +11 -0
  40. package/src/adapters/mastra.ts +118 -0
  41. package/src/adapters/muse-spark.ts +147 -0
  42. package/src/adapters/shared.ts +2 -1
  43. package/src/data-screen.ts +533 -0
  44. package/src/dev.ts +45 -2
  45. package/src/governance.ts +204 -0
  46. package/src/index.ts +43 -0
  47. package/src/messages.ts +10 -1
  48. package/src/released.ts +2184 -0
  49. package/src/screen.ts +144 -0
  50. package/src/tasks.ts +88 -0
  51. 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
- <https://deliverd.dev/quickstart>
769
- - The API reference: <https://deliverd.dev/docs/api>
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
- <https://deliverd.dev/docs/developers/mcp>
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.
@@ -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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"}