effect-assistant 0.15.0 → 0.16.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.
@@ -1,15 +1,8 @@
1
- import * as Context from "effect/Context";
2
1
  import * as Schema from "effect/Schema";
3
2
  import * as Tool from "effect/ai/Tool";
4
3
  declare namespace ToolStatus_d_exports {
5
- export { Described, described, isDescribed, parameterDescription, parameterName };
4
+ export { StatusField, WithoutStatus, isDescribed, parameterDescription, parameterName, withStatus };
6
5
  }
7
- type Schemas = {
8
- readonly parameters: Schema.Constraint;
9
- readonly success: Schema.Constraint;
10
- readonly failure: Schema.Constraint;
11
- readonly failureMode: Tool.FailureMode;
12
- };
13
6
  /**
14
7
  * The name of the parameter the model fills with a call's status.
15
8
  *
@@ -25,44 +18,54 @@ export declare const parameterName = "description";
25
18
  */
26
19
  export declare const parameterDescription = "Shown to the user while this runs: 3 to 8 plain words in the user's language about what you're doing, like \"Checking last summer's campaign budget\". No tool names, ids or code.";
27
20
  /**
28
- * Annotation for whether a tool's calls show a status, set with {@link described}.
21
+ * The schema of the status field {@link withStatus} adds.
29
22
  *
30
- * @category annotations
31
- * @since 0.13.0
23
+ * @category schemas
24
+ * @since 0.16.0
32
25
  */
33
- export declare const Described: Context.Reference<boolean>;
26
+ export declare const StatusField: Schema.String;
34
27
  /**
35
- * Marks a tool whose calls show a status while they run.
28
+ * The parameter fields a struct can't have to take a status field: a `description` field of its own.
29
+ *
30
+ * @category models
31
+ * @since 0.16.0
32
+ */
33
+ export type WithoutStatus<Fields extends Schema.Struct.Fields> = typeof parameterName extends keyof Fields ? "Error: these parameters have a description field already, so they can't take a status: rename it" : unknown;
34
+ /**
35
+ * Adds the status field to a tool's parameters, so its calls show a status while they run.
36
36
  *
37
37
  * **Details**
38
38
  *
39
- * The model sees a required `description` parameter on the tool, and the chat shows what it
40
- * writes there while the call runs. Required, because models leave optional parameters out; a call
41
- * without it still runs, with no status. The handler gets its parameters without it. A tool that has a
42
- * parameter of that name already can't be marked: the loop stops with a defect when it offers one.
39
+ * The struct gets a required `description` field ({@link StatusField}), and keeps its own
40
+ * annotations and checks. Required, because models leave optional parameters out. The chat shows
41
+ * what the model writes there while the call runs; a call with a blank one runs with no status,
42
+ * and a call without it fails validation like a call without any other required parameter. The
43
+ * handler gets `description` like any other parameter. A struct that has a `description` field
44
+ * already is a type error. A tool without parameters takes `Schema.Struct({})`.
43
45
  *
44
- * **Example** (A slow report with a status)
46
+ * **Example** (A tool whose calls show a status)
45
47
  *
46
48
  * ```ts
47
49
  * import { ToolStatus } from "effect-assistant"
48
50
  * import * as Tool from "effect/ai/Tool"
49
51
  * import * as Schema from "effect/Schema"
50
52
  *
51
- * export const CampaignReport = ToolStatus.described(
52
- * Tool.make("campaign_report", {
53
- * description: "The spend and results of a past campaign.",
54
- * parameters: Schema.Struct({ campaignId: Schema.String }),
55
- * success: Schema.Struct({ spent: Schema.Finite })
56
- * })
57
- * )
53
+ * export const ArchiveNote = Tool.make("archive_note", {
54
+ * description: "Archives a note and the files attached to it.",
55
+ * parameters: Schema.Struct({ noteId: Schema.String }).pipe(ToolStatus.withStatus),
56
+ * success: Schema.Struct({ archived: Schema.Boolean })
57
+ * })
58
58
  * ```
59
59
  *
60
- * @category annotations
61
- * @since 0.13.0
60
+ * @category combinators
61
+ * @since 0.16.0
62
62
  */
63
- export declare const described: <Name extends string, Config extends Schemas, R>(tool: Tool.Tool<Name, Config, R>) => Tool.Tool<Name, Config, R>;
63
+ export declare const withStatus: <Fields extends Schema.Struct.Fields>(self: Schema.Struct<Fields> & WithoutStatus<Fields>) => Schema.Struct<Readonly<Fields & {
64
+ description: Schema.String;
65
+ }> extends (infer T) ? { [K in keyof T]: T[K]; } : never>;
64
66
  /**
65
- * Returns whether a tool's calls show a status.
67
+ * Returns whether a tool's calls show a status: its parameters have the field {@link withStatus}
68
+ * adds. A `description` parameter of its own doesn't count.
66
69
  *
67
70
  * @category guards
68
71
  * @since 0.13.0
@@ -1 +1 @@
1
- {"version":3,"file":"ToolStatus.d.ts","names":[],"sources":["../src/ToolStatus.ts"],"mappings":";;;;;;KAiBK;WACM,YAAY,OAAO;WACnB,SAAS,OAAO;WAChB,SAAS,OAAO;WAChB,aAAa,KAAK;;;;;;;;qBAShB;;;;;;;qBAQA;;;;;;;qBASA,WAAS,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiCT,YAAa,qBAAqB,eAAe,SAAS,GAAC,MAChE,KAAK,KAAK,MAAM,QAAQ,OAC7B,KAAK,KAAK,MAAM,QAAQ;;;;;;;qBAQd,cAAW,MAAU,KAAK"}
1
+ {"version":3,"file":"ToolStatus.d.ts","names":[],"sources":["../src/ToolStatus.ts"],"mappings":";;;;;;;;;;;qBAuBa;;;;;;;qBAQA;;;;;;;qBAWA,aAAW,OAAA;;;;;;;YAQZ,cAAc,eAAe,OAAO,OAAO,iBAAiB,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiCvF,aAAc,eAAe,OAAO,OAAO,QAAM,MACtD,OAAO,OAAO,UAAU,cAAc,YAAO,OAAA,OAAA,SAAA;;kBAYpD,QAAA,WAAA,IAAA,EAAA;;;;;;;;qBASY,cAAW,MAAU,KAAK"}
@@ -1,12 +1,13 @@
1
1
  import { __exportAll } from "./_virtual/_rolldown/runtime.js";
2
- import * as Context from "effect/Context";
2
+ import * as Schema from "effect/Schema";
3
+ import * as SchemaAST from "effect/SchemaAST";
3
4
  //#region src/ToolStatus.ts
4
5
  var ToolStatus_exports = /* @__PURE__ */ __exportAll({
5
- Described: () => Described,
6
- described: () => described,
6
+ StatusField: () => StatusField,
7
7
  isDescribed: () => isDescribed,
8
8
  parameterDescription: () => parameterDescription,
9
- parameterName: () => parameterName
9
+ parameterName: () => parameterName,
10
+ withStatus: () => withStatus
10
11
  });
11
12
  /**
12
13
  * The name of the parameter the model fills with a call's status.
@@ -22,51 +23,65 @@ const parameterName = "description";
22
23
  * @since 0.13.0
23
24
  */
24
25
  const parameterDescription = "Shown to the user while this runs: 3 to 8 plain words in the user's language about what you're doing, like \"Checking last summer's campaign budget\". No tool names, ids or code.";
26
+ const statusFieldKey = "effect-assistant/ToolStatus/statusField";
25
27
  /**
26
- * Annotation for whether a tool's calls show a status, set with {@link described}.
28
+ * The schema of the status field {@link withStatus} adds.
27
29
  *
28
- * @category annotations
29
- * @since 0.13.0
30
+ * @category schemas
31
+ * @since 0.16.0
30
32
  */
31
- const Described = Context.Reference("effect-assistant/ToolStatus/Described", { defaultValue: () => false });
33
+ const StatusField = Schema.String.annotate({
34
+ description: parameterDescription,
35
+ [statusFieldKey]: true
36
+ });
32
37
  /**
33
- * Marks a tool whose calls show a status while they run.
38
+ * Adds the status field to a tool's parameters, so its calls show a status while they run.
34
39
  *
35
40
  * **Details**
36
41
  *
37
- * The model sees a required `description` parameter on the tool, and the chat shows what it
38
- * writes there while the call runs. Required, because models leave optional parameters out; a call
39
- * without it still runs, with no status. The handler gets its parameters without it. A tool that has a
40
- * parameter of that name already can't be marked: the loop stops with a defect when it offers one.
42
+ * The struct gets a required `description` field ({@link StatusField}), and keeps its own
43
+ * annotations and checks. Required, because models leave optional parameters out. The chat shows
44
+ * what the model writes there while the call runs; a call with a blank one runs with no status,
45
+ * and a call without it fails validation like a call without any other required parameter. The
46
+ * handler gets `description` like any other parameter. A struct that has a `description` field
47
+ * already is a type error. A tool without parameters takes `Schema.Struct({})`.
41
48
  *
42
- * **Example** (A slow report with a status)
49
+ * **Example** (A tool whose calls show a status)
43
50
  *
44
51
  * ```ts
45
52
  * import { ToolStatus } from "effect-assistant"
46
53
  * import * as Tool from "effect/ai/Tool"
47
54
  * import * as Schema from "effect/Schema"
48
55
  *
49
- * export const CampaignReport = ToolStatus.described(
50
- * Tool.make("campaign_report", {
51
- * description: "The spend and results of a past campaign.",
52
- * parameters: Schema.Struct({ campaignId: Schema.String }),
53
- * success: Schema.Struct({ spent: Schema.Finite })
54
- * })
55
- * )
56
+ * export const ArchiveNote = Tool.make("archive_note", {
57
+ * description: "Archives a note and the files attached to it.",
58
+ * parameters: Schema.Struct({ noteId: Schema.String }).pipe(ToolStatus.withStatus),
59
+ * success: Schema.Struct({ archived: Schema.Boolean })
60
+ * })
56
61
  * ```
57
62
  *
58
- * @category annotations
59
- * @since 0.13.0
63
+ * @category combinators
64
+ * @since 0.16.0
60
65
  */
61
- const described = (tool) => tool.annotate(Described, true);
66
+ const withStatus = (self) => {
67
+ const struct = self.mapFields((fields) => ({
68
+ ...fields,
69
+ [parameterName]: StatusField
70
+ }));
71
+ return struct.rebuild(new SchemaAST.Objects(struct.ast.propertySignatures, struct.ast.indexSignatures, self.ast.annotations, self.ast.checks));
72
+ };
62
73
  /**
63
- * Returns whether a tool's calls show a status.
74
+ * Returns whether a tool's calls show a status: its parameters have the field {@link withStatus}
75
+ * adds. A `description` parameter of its own doesn't count.
64
76
  *
65
77
  * @category guards
66
78
  * @since 0.13.0
67
79
  */
68
- const isDescribed = (tool) => Context.get(tool.annotations, Described);
80
+ const isDescribed = (tool) => {
81
+ const ast = tool.parametersSchema.ast;
82
+ return SchemaAST.isObjects(ast) && ast.propertySignatures.some((property) => property.name === "description" && SchemaAST.resolveAt(statusFieldKey)(property.type) === true);
83
+ };
69
84
  //#endregion
70
- export { Described, ToolStatus_exports, described, isDescribed, parameterDescription, parameterName };
85
+ export { StatusField, ToolStatus_exports, isDescribed, parameterDescription, parameterName, withStatus };
71
86
 
72
87
  //# sourceMappingURL=ToolStatus.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"ToolStatus.js","names":[],"sources":["../src/ToolStatus.ts"],"sourcesContent":["/**\n * This module provides status labels for tool calls: while a call runs, the chat shows the user a\n * short line about what the assistant is doing, like \"Checking last summer's campaign budget\".\n *\n * Mark the tools that take a while or act on something with {@link described}: workflows, reports\n * from other systems, orders, specialists. The model then sees a required `description` parameter\n * on them and fills it in the chat's language. When the call starts, the chat sends the\n * description as a `ChatSignal.Status`; it shows until the next status, so it stays after the call\n * ends. The tool's handler never receives the parameter. Quick reads need no label: the chat shows its generic working state for\n * them.\n *\n * @since 0.13.0\n */\nimport type * as Tool from \"effect/ai/Tool\"\nimport * as Context from \"effect/Context\"\nimport type * as Schema from \"effect/Schema\"\n\ntype Schemas = {\n readonly parameters: Schema.Constraint\n readonly success: Schema.Constraint\n readonly failure: Schema.Constraint\n readonly failureMode: Tool.FailureMode\n}\n\n/**\n * The name of the parameter the model fills with a call's status.\n *\n * @category constants\n * @since 0.13.0\n */\nexport const parameterName = \"description\"\n\n/**\n * What the model reads about the parameter.\n *\n * @category constants\n * @since 0.13.0\n */\nexport const parameterDescription =\n \"Shown to the user while this runs: 3 to 8 plain words in the user's language about what you're doing, like \\\"Checking last summer's campaign budget\\\". No tool names, ids or code.\"\n\n/**\n * Annotation for whether a tool's calls show a status, set with {@link described}.\n *\n * @category annotations\n * @since 0.13.0\n */\nexport const Described = Context.Reference<boolean>(\"effect-assistant/ToolStatus/Described\", {\n defaultValue: () => false\n})\n\n/**\n * Marks a tool whose calls show a status while they run.\n *\n * **Details**\n *\n * The model sees a required `description` parameter on the tool, and the chat shows what it\n * writes there while the call runs. Required, because models leave optional parameters out; a call\n * without it still runs, with no status. The handler gets its parameters without it. A tool that has a\n * parameter of that name already can't be marked: the loop stops with a defect when it offers one.\n *\n * **Example** (A slow report with a status)\n *\n * ```ts\n * import { ToolStatus } from \"effect-assistant\"\n * import * as Tool from \"effect/ai/Tool\"\n * import * as Schema from \"effect/Schema\"\n *\n * export const CampaignReport = ToolStatus.described(\n * Tool.make(\"campaign_report\", {\n * description: \"The spend and results of a past campaign.\",\n * parameters: Schema.Struct({ campaignId: Schema.String }),\n * success: Schema.Struct({ spent: Schema.Finite })\n * })\n * )\n * ```\n *\n * @category annotations\n * @since 0.13.0\n */\nexport const described = <Name extends string, Config extends Schemas, R>(\n tool: Tool.Tool<Name, Config, R>\n): Tool.Tool<Name, Config, R> => tool.annotate(Described, true)\n\n/**\n * Returns whether a tool's calls show a status.\n *\n * @category guards\n * @since 0.13.0\n */\nexport const isDescribed = (tool: Tool.Any): boolean => Context.get(tool.annotations, Described)\n"],"mappings":";;;;;;;;;;;;;;;;AA8BA,MAAa,gBAAgB;;;;;;;AAQ7B,MAAa,uBACX;;;;;;;AAQF,MAAa,YAAY,QAAQ,UAAmB,yCAAyC,EAC3F,oBAAoB,MACtB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BD,MAAa,aACX,SAC+B,KAAK,SAAS,WAAW,IAAI;;;;;;;AAQ9D,MAAa,eAAe,SAA4B,QAAQ,IAAI,KAAK,aAAa,SAAS"}
1
+ {"version":3,"file":"ToolStatus.js","names":[],"sources":["../src/ToolStatus.ts"],"sourcesContent":["/**\n * This module provides status labels for tool calls: while a call runs, the chat shows the user a\n * short line about what the assistant is doing, like \"Checking last summer's campaign budget\".\n *\n * Give the tools that take a while or act on something a status field with {@link withStatus}:\n * workflows, reports from other systems, orders, specialists. Their parameters get a required\n * `description` field that the model fills in the chat's language. When the call starts, the chat\n * sends the description as a `ChatSignal.Status`; it shows until the next status, so it stays\n * after the call ends. The call runs unchanged: the handler gets `description` with its other\n * parameters. Quick reads need no label: the chat shows its generic working state for them.\n *\n * @since 0.13.0\n */\nimport type * as Tool from \"effect/ai/Tool\"\nimport * as Schema from \"effect/Schema\"\nimport * as SchemaAST from \"effect/SchemaAST\"\n\n/**\n * The name of the parameter the model fills with a call's status.\n *\n * @category constants\n * @since 0.13.0\n */\nexport const parameterName = \"description\"\n\n/**\n * What the model reads about the parameter.\n *\n * @category constants\n * @since 0.13.0\n */\nexport const parameterDescription =\n \"Shown to the user while this runs: 3 to 8 plain words in the user's language about what you're doing, like \\\"Checking last summer's campaign budget\\\". No tool names, ids or code.\"\n\nconst statusFieldKey = \"effect-assistant/ToolStatus/statusField\"\n\n/**\n * The schema of the status field {@link withStatus} adds.\n *\n * @category schemas\n * @since 0.16.0\n */\nexport const StatusField = Schema.String.annotate({ description: parameterDescription, [statusFieldKey]: true })\n\n/**\n * The parameter fields a struct can't have to take a status field: a `description` field of its own.\n *\n * @category models\n * @since 0.16.0\n */\nexport type WithoutStatus<Fields extends Schema.Struct.Fields> = typeof parameterName extends keyof Fields\n ? \"Error: these parameters have a description field already, so they can't take a status: rename it\"\n : unknown\n\n/**\n * Adds the status field to a tool's parameters, so its calls show a status while they run.\n *\n * **Details**\n *\n * The struct gets a required `description` field ({@link StatusField}), and keeps its own\n * annotations and checks. Required, because models leave optional parameters out. The chat shows\n * what the model writes there while the call runs; a call with a blank one runs with no status,\n * and a call without it fails validation like a call without any other required parameter. The\n * handler gets `description` like any other parameter. A struct that has a `description` field\n * already is a type error. A tool without parameters takes `Schema.Struct({})`.\n *\n * **Example** (A tool whose calls show a status)\n *\n * ```ts\n * import { ToolStatus } from \"effect-assistant\"\n * import * as Tool from \"effect/ai/Tool\"\n * import * as Schema from \"effect/Schema\"\n *\n * export const ArchiveNote = Tool.make(\"archive_note\", {\n * description: \"Archives a note and the files attached to it.\",\n * parameters: Schema.Struct({ noteId: Schema.String }).pipe(ToolStatus.withStatus),\n * success: Schema.Struct({ archived: Schema.Boolean })\n * })\n * ```\n *\n * @category combinators\n * @since 0.16.0\n */\nexport const withStatus = <Fields extends Schema.Struct.Fields>(\n self: Schema.Struct<Fields> & WithoutStatus<Fields>\n) => {\n const struct = self.mapFields((fields) => ({ ...fields, [parameterName]: StatusField }))\n\n return struct.rebuild(\n new SchemaAST.Objects(\n struct.ast.propertySignatures,\n struct.ast.indexSignatures,\n self.ast.annotations,\n self.ast.checks\n )\n )\n}\n\n/**\n * Returns whether a tool's calls show a status: its parameters have the field {@link withStatus}\n * adds. A `description` parameter of its own doesn't count.\n *\n * @category guards\n * @since 0.13.0\n */\nexport const isDescribed = (tool: Tool.Any): boolean => {\n const ast = tool.parametersSchema.ast\n\n return (\n SchemaAST.isObjects(ast) &&\n ast.propertySignatures.some(\n (property) =>\n property.name === parameterName && SchemaAST.resolveAt<boolean>(statusFieldKey)(property.type) === true\n )\n )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAuBA,MAAa,gBAAgB;;;;;;;AAQ7B,MAAa,uBACX;AAEF,MAAM,iBAAiB;;;;;;;AAQvB,MAAa,cAAc,OAAO,OAAO,SAAS;CAAE,aAAa;EAAuB,iBAAiB;AAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyC/G,MAAa,cACX,SACG;CACH,MAAM,SAAS,KAAK,WAAW,YAAY;EAAE,GAAG;GAAS,gBAAgB;CAAY,EAAE;CAEvF,OAAO,OAAO,QACZ,IAAI,UAAU,QACZ,OAAO,IAAI,oBACX,OAAO,IAAI,iBACX,KAAK,IAAI,aACT,KAAK,IAAI,MACX,CACF;AACF;;;;;;;;AASA,MAAa,eAAe,SAA4B;CACtD,MAAM,MAAM,KAAK,iBAAiB;CAElC,OACE,UAAU,UAAU,GAAG,KACvB,IAAI,mBAAmB,MACpB,aACC,SAAS,SAAA,iBAA0B,UAAU,UAAmB,cAAc,CAAC,CAAC,SAAS,IAAI,MAAM,IACvG;AAEJ"}
@@ -1 +1 @@
1
- {"version":3,"file":"loop.d.ts","names":[],"sources":["../../src/internal/loop.ts"],"mappings":";;;;;;;;;;;;;;;YA2BY,QACR,cACA,cACA,aACA;;qBAKS,eAAa,QAAA,UAAA,OAAA;WACW,UAAA,OAAO,OAAO,cAAc;;;qBAMpD,WAAS,QAAA,UAAA,OAAA,OAAA;;iBAKL;WACN,UAAU,cAAc,OAAO;WAC/B;;;iBAUM,YAAY;WAClB,uBAAuB;WACvB,UAAU,MAAe;WACzB,SAAS,OAAO,OAAO,cAAc,OAAO,WAAW;WACvD,aAAa,cAAc;;;iBAIrB,QAAQ,mBAAmB,YAAY;WAC7C;;;iBAKM;;WAEN,QAAQ;;;;;;WAMR;;;;WAIA;;;YAkOC,KAAK,GAAG,KAAK,KAAK;EAC5B;aAAkB,OAAO;;EACzB;aAAiB,OAAO;;EACxB,MAAM;;;qBAUK,QAAS,GAAC,OAAS,MAAI,KAAK;;qBAG5B,OAAQ,GAAC,OAAS,MAAI,OAAO,OAAO,YAAY;;qBAIhD,OAAQ,gBAAc,OAAO,OAAO,YAAY;;qBAOhD,OAAQ,GAAG,GAAG,GAAG,GAAC,SACpB,GAAC,OACH,OAAO,MAAM,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,OAChD,OAAO,OAAO,GAAG,GAAG;;qBAmBV,OAAQ,GAAG,GAAG,YAAY,YAAU,SACtC,YAAY,IAAE,OAChB,QAAQ,eAAe,OAAO,OAAO,YAAY,IAAI,IAAI,QAC/D,OAAO,OAAO,KAAK,OAAO,IAAI,QAAQ,UAAU,IAAI,cAAc,gBAAgB,IAAI;;qBA8E5E,MAAO,WAAS,SAClB,QAAQ,OAChB,OAAO,OAAO,OAAO,QAAQ,SAAS,cAAc,gBAAgB"}
1
+ {"version":3,"file":"loop.d.ts","names":[],"sources":["../../src/internal/loop.ts"],"mappings":";;;;;;;;;;;;;;;YA0BY,QACR,cACA,cACA,aACA;;qBAKS,eAAa,QAAA,UAAA,OAAA;WACW,UAAA,OAAO,OAAO,cAAc;;;qBAMpD,WAAS,QAAA,UAAA,OAAA,OAAA;;iBAKL;WACN,UAAU,cAAc,OAAO;WAC/B;;;iBAUM,YAAY;WAClB,uBAAuB;WACvB,UAAU,MAAe;WACzB,SAAS,OAAO,OAAO,cAAc,OAAO,WAAW;WACvD,aAAa,cAAc;;;iBAIrB,QAAQ,mBAAmB,YAAY;WAC7C;;;iBAKM;;WAEN,QAAQ;;;;;;WAMR;;;;WAIA;;;YA4LC,KAAK,GAAG,KAAK,KAAK;EAC5B;aAAkB,OAAO;;EACzB;aAAiB,OAAO;;EACxB,MAAM;;;qBAUK,QAAS,GAAC,OAAS,MAAI,KAAK;;qBAG5B,OAAQ,GAAC,OAAS,MAAI,OAAO,OAAO,YAAY;;qBAIhD,OAAQ,gBAAc,OAAO,OAAO,YAAY;;qBAOhD,OAAQ,GAAG,GAAG,GAAG,GAAC,SACpB,GAAC,OACH,OAAO,MAAM,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,OAChD,OAAO,OAAO,GAAG,GAAG;;qBAmBV,OAAQ,GAAG,GAAG,YAAY,YAAU,SACtC,YAAY,IAAE,OAChB,QAAQ,eAAe,OAAO,OAAO,YAAY,IAAI,IAAI,QAC/D,OAAO,OAAO,KAAK,OAAO,IAAI,QAAQ,UAAU,IAAI,cAAc,gBAAgB,IAAI;;qBA8E5E,MAAO,WAAS,SAClB,QAAQ,OAChB,OAAO,OAAO,OAAO,QAAQ,SAAS,cAAc,gBAAgB"}
@@ -2,7 +2,7 @@ import { ApprovalRequested, ModelOutput, ModelPart, ToolResult, ToolStarted } fr
2
2
  import { collect } from "./stream.js";
3
3
  import { annotateModelCall, toolOutput, toolSpan } from "./telemetry.js";
4
4
  import { unansweredCalls } from "./history.js";
5
- import { isDescribed, parameterDescription, parameterName } from "../ToolStatus.js";
5
+ import { isDescribed, parameterName } from "../ToolStatus.js";
6
6
  import { use } from "./live.js";
7
7
  import { empty, failed } from "./toolkit.js";
8
8
  import { isTurnEnding, isUserMessage } from "./tools.js";
@@ -15,7 +15,6 @@ import * as Stream from "effect/Stream";
15
15
  import * as Data from "effect/Data";
16
16
  import * as Model from "effect/ai/Model";
17
17
  import * as Prompt from "effect/ai/Prompt";
18
- import * as SchemaAST from "effect/SchemaAST";
19
18
  import * as LanguageModel from "effect/ai/LanguageModel";
20
19
  import * as Clock from "effect/Clock";
21
20
  //#region src/internal/loop.ts
@@ -30,19 +29,8 @@ const readHistory = (read) => "messages" in read ? {
30
29
  messages: read,
31
30
  throughSequence: void 0
32
31
  };
33
- const statusParameter = Schema.String.annotate({ description: parameterDescription });
34
- const withStatusParameter = (tool) => {
35
- const ast = tool.parametersSchema.ast;
36
- if (!isDescribed(tool) || !SchemaAST.isObjects(ast)) return tool;
37
- if (ast.propertySignatures.some((property) => property.name === "description")) throw new Error(`${tool.name} has a parameter named ${parameterName} already, so it can't show a status: rename it.`);
38
- const added = Schema.Struct({ [parameterName]: statusParameter }).ast.propertySignatures;
39
- return tool.setParameters(Schema.make(new SchemaAST.Objects([...ast.propertySignatures, ...added], ast.indexSignatures.filter((index) => !SchemaAST.isNever(index.type)), ast.annotations)));
40
- };
41
32
  const requestToolkit = (definitions) => ({
42
- tools: Object.fromEntries(definitions.map((tool) => {
43
- const requested = withStatusParameter(tool);
44
- return [tool.name, requested.needsApproval === void 0 || requested.needsApproval === false ? requested : requested.setNeedsApproval(false)];
45
- })),
33
+ tools: Object.fromEntries(definitions.map((tool) => [tool.name, tool.needsApproval === void 0 || tool.needsApproval === false ? tool : tool.setNeedsApproval(false)])),
46
34
  handle: () => Effect.succeed(Stream.empty)
47
35
  });
48
36
  const startsMessage = (part) => part.type === "text-start" || part.type === "tool-params-start" && part.name === "send_user_message";
@@ -58,21 +46,12 @@ const modelParts = (content) => content.flatMap((part) => Option.toArray(decodeP
58
46
  const toolCalls = (parts) => parts.flatMap((part) => part.type === "tool-call" ? [part] : []);
59
47
  const decodeParams = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Json));
60
48
  const isDescribedCall = (tools, call) => tools.definitions.some((tool) => tool.name === call.name && isDescribed(tool));
61
- const splitStatus = (call) => {
62
- const params = decodeParams(call.params);
63
- if (Option.isNone(params) || !Object.hasOwn(params.value, "description")) return [void 0, call];
64
- const { [parameterName]: written, ...rest } = params.value;
65
- const status = Predicate.isString(written) ? written.trim() : "";
66
- return [status === "" ? void 0 : status, {
67
- ...call,
68
- params: rest
69
- }];
70
- };
49
+ const statusOf = (call) => decodeParams(call.params).pipe(Option.flatMapNullishOr((params) => params[parameterName]), Option.filter(Predicate.isString), Option.map((written) => written.trim()), Option.filter((status) => status !== ""), Option.getOrUndefined);
71
50
  const runCall = Effect.fnUntraced(function* (tools, call) {
72
- const [status, run] = isDescribedCall(tools, call) ? splitStatus(call) : [void 0, call];
51
+ const status = isDescribedCall(tools, call) ? statusOf(call) : void 0;
73
52
  const result = yield* Effect.gen(function* () {
74
53
  if (status !== void 0) yield* use((live) => live.callStarted(call.id, status));
75
- const result = yield* tools.run(run);
54
+ const result = yield* tools.run(call);
76
55
  yield* toolOutput(result.result);
77
56
  return result;
78
57
  }).pipe(toolSpan(call), Effect.ensuring(use((live) => Effect.andThen(live.callEnded(call.id), call.name === "send_user_message" ? live.typing(false) : Effect.void))));
@@ -1 +1 @@
1
- {"version":3,"file":"loop.js","names":["ToolStatus.parameterDescription","ToolStatus.isDescribed","ToolStatus.parameterName","Live.use","Streamed.collect","AssistantEvent.ModelPart","Telemetry.toolOutput","Telemetry.toolSpan","Toolkits.failed","Toolkits.empty","History.unansweredCalls","Telemetry.annotateModelCall"],"sources":["../../src/internal/loop.ts"],"sourcesContent":["import type * as AiError from \"effect/ai/AiError\"\nimport * as LanguageModel from \"effect/ai/LanguageModel\"\nimport * as Model from \"effect/ai/Model\"\nimport * as Prompt from \"effect/ai/Prompt\"\nimport type * as Response from \"effect/ai/Response\"\nimport type * as Tool from \"effect/ai/Tool\"\nimport type * as Toolkit from \"effect/ai/Toolkit\"\nimport * as Clock from \"effect/Clock\"\nimport * as Context from \"effect/Context\"\nimport * as Data from \"effect/Data\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as Schema from \"effect/Schema\"\nimport * as SchemaAST from \"effect/SchemaAST\"\nimport * as Stream from \"effect/Stream\"\nimport * as AssistantEvent from \"../AssistantEvent.ts\"\nimport type * as Instructions from \"../Instructions.ts\"\nimport * as ToolStatus from \"../ToolStatus.ts\"\nimport * as History from \"./history.ts\"\nimport * as Live from \"./live.ts\"\nimport * as Streamed from \"./stream.ts\"\nimport * as Telemetry from \"./telemetry.ts\"\nimport * as Toolkits from \"./toolkit.ts\"\nimport { isTurnEnding, isUserMessage, sendUserMessageName } from \"./tools.ts\"\n\n/** @internal */\nexport type Event =\n | AssistantEvent.ModelOutput\n | AssistantEvent.ToolStarted\n | AssistantEvent.ToolResult\n | AssistantEvent.ApprovalRequested\n\n// Only a turn's loop can wait for the user's approval, and runs the calls they approved. A turn's specialists inherit\n// its context, so their runs set it back to none.\n/** @internal */\nexport const TurnApprovals = Context.Reference<\n Option.Option<{ readonly approved: Effect.Effect<ReadonlyArray<AssistantEvent.ToolCallPart>> }>\n>(\"effect-assistant/TurnApprovals\", { defaultValue: Option.none })\n\n// The assistant's own tools with the turn's services, so an app's own loop in a turn can message the user. A\n// specialist's run has none.\n/** @internal */\nexport const TurnTools = Context.Reference<Option.Option<Toolkits.Tools>>(\"effect-assistant/TurnTools\", {\n defaultValue: Option.none\n})\n\n/** @internal */\nexport interface ChatHistory {\n readonly messages: ReadonlyArray<Prompt.Message>\n readonly throughSequence: number\n}\n\nconst readHistory = (read: ReadonlyArray<Prompt.Message> | ChatHistory) =>\n \"messages\" in read\n ? { messages: read.messages, throughSequence: read.throughSequence }\n : { messages: read, throughSequence: undefined }\n\n// `AssistantLoop` takes native toolkits; turns and specialist runs come here with their tools already merged.\n/** @internal */\nexport interface StepOptions<R = never> {\n readonly instructions: string | Instructions.Resolved\n readonly toolkit?: Toolkits.Tools<R> | undefined\n readonly history: Effect.Effect<ReadonlyArray<Prompt.Message> | ChatHistory>\n readonly toolChoice?: LanguageModel.ToolChoice<string> | undefined\n}\n\n/** @internal */\nexport interface Options<R = never> extends StepOptions<R> {\n readonly maxSteps?: number | undefined\n}\n\n// Its member docs show through `AssistantLoop.StepResult`.\n/** @internal */\nexport interface StepResult {\n /** The model's output; unset when the step only ran calls a crash cut off. */\n readonly output: AssistantEvent.ModelOutput | undefined\n /**\n * Whether the model is done: it made no tool calls, one of its calls waits for the user's\n * approval, or it ended its turn (`wait`, or a message with `wait: true`) and none of the step's\n * calls failed.\n */\n readonly done: boolean\n /**\n * The history's length with this step's output and results: a longer one got something new meanwhile.\n */\n readonly historyLength: number\n}\n\n// A tool as `Tool.isUserDefined` narrows one. With `Tool.Any`, generateText's types ask for the services that encode\n// every tool's params, `unknown` for a schema of unknown type, though deferred validation encodes none.\ntype RequestTool = Tool.Tool<string, any, any>\n\n// Required in what the model reads, so it writes one with every call; a call without it still runs.\nconst statusParameter = Schema.String.annotate({ description: ToolStatus.parameterDescription })\n\n// What the model reads of a described tool: its parameters with the status one. Only the request has it; the call\n// runs without it (see `withoutStatus`). A record of no keys (a tool without parameters) becomes an object with it.\nconst withStatusParameter = (tool: Tool.Any): Tool.Any => {\n const ast = tool.parametersSchema.ast\n\n if (!ToolStatus.isDescribed(tool) || !SchemaAST.isObjects(ast)) return tool\n\n if (ast.propertySignatures.some((property) => property.name === ToolStatus.parameterName)) {\n throw new Error(\n `${tool.name} has a parameter named ${ToolStatus.parameterName} already, so it can't show a status: rename it.`\n )\n }\n\n const added = Schema.Struct({ [ToolStatus.parameterName]: statusParameter }).ast.propertySignatures\n\n return tool.setParameters(\n Schema.make<Schema.Top>(\n new SchemaAST.Objects(\n [...ast.propertySignatures, ...added],\n ast.indexSignatures.filter((index) => !SchemaAST.isNever(index.type)),\n ast.annotations\n )\n )\n )\n}\n\n// The loop runs the calls itself, after storing each as started, so the model call runs none. It also decides which\n// calls wait for approval: the model call would ask for approvals of its own.\nconst requestToolkit = (definitions: ReadonlyArray<Tool.Any>): Toolkit.WithHandler<Record<string, RequestTool>> => ({\n tools: Object.fromEntries(\n definitions.map((tool) => {\n const requested = withStatusParameter(tool)\n\n return [\n tool.name,\n requested.needsApproval === undefined || requested.needsApproval === false\n ? requested\n : requested.setNeedsApproval(false)\n ]\n })\n ),\n handle: () => Effect.succeed(Stream.empty)\n})\n\n// The model starts a message to the user: a `send_user_message` call, or text of its own, which the reply pass turns\n// into one.\nconst startsMessage = (part: Response.AnyPart) =>\n part.type === \"text-start\" || (part.type === \"tool-params-start\" && part.name === sendUserMessageName)\n\n// Validation is deferred: a call to a tool that isn't in the toolkit (one in the history the turn no longer offers),\n// or with params that don't fit its schema, would otherwise fail the whole model call. The loop runs it instead, and\n// the model reads why it failed.\n// Streamed, so the chat can show the user that a message is on its way while the model writes it.\nconst generate = (\n prompt: Prompt.Prompt,\n definitions: ReadonlyArray<Tool.Any>,\n toolChoice: LanguageModel.ToolChoice<string> | undefined\n): Effect.Effect<ReadonlyArray<Response.AnyPart>, AiError.AiError, LanguageModel.LanguageModel> =>\n Stream.suspend(() =>\n LanguageModel.streamText({\n prompt,\n toolkit: requestToolkit(definitions),\n toolChoice,\n disableToolCallResolution: true,\n toolCallValidation: \"deferred\"\n })\n ).pipe(\n Stream.tap((part) => (startsMessage(part) ? Live.use((live) => live.typing(true)) : Effect.void)),\n Stream.runCollect,\n Effect.map(Streamed.collect)\n )\n\nconst decodePart = Schema.decodeUnknownOption(AssistantEvent.ModelPart)\n\nconst modelParts = (content: ReadonlyArray<Response.AnyPart>) =>\n content.flatMap((part) =>\n Option.toArray(decodePart(part)).filter((decoded) => !(decoded.type === \"tool-call\" && decoded.providerExecuted))\n )\n\nconst toolCalls = (parts: ReadonlyArray<AssistantEvent.ModelPart>): ReadonlyArray<AssistantEvent.ToolCallPart> =>\n parts.flatMap((part) => (part.type === \"tool-call\" ? [part] : []))\n\nconst decodeParams = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Json))\n\nconst isDescribedCall = <R>(tools: Toolkits.Tools<R>, call: AssistantEvent.ToolCallPart) =>\n tools.definitions.some((tool) => tool.name === call.name && ToolStatus.isDescribed(tool))\n\n// The status the model wrote for a described tool's call, and the call as the tool's handler gets it.\nconst splitStatus = (call: AssistantEvent.ToolCallPart): readonly [string | undefined, AssistantEvent.ToolCallPart] => {\n const params = decodeParams(call.params)\n\n if (Option.isNone(params) || !Object.hasOwn(params.value, ToolStatus.parameterName)) return [undefined, call]\n\n const { [ToolStatus.parameterName]: written, ...rest } = params.value\n const status = Predicate.isString(written) ? written.trim() : \"\"\n\n return [status === \"\" ? undefined : status, { ...call, params: rest }]\n}\n\n// A call's status shows when it starts; a message's typing stops once the message is stored.\nconst runCall = Effect.fnUntraced(function* <R>(tools: Toolkits.Tools<R>, call: AssistantEvent.ToolCallPart) {\n const [status, run] = isDescribedCall(tools, call) ? splitStatus(call) : [undefined, call]\n\n const result = yield* Effect.gen(function* () {\n if (status !== undefined) yield* Live.use((live) => live.callStarted(call.id, status))\n\n const result = yield* tools.run(run)\n\n yield* Telemetry.toolOutput(result.result)\n\n return result\n }).pipe(\n Telemetry.toolSpan(call),\n Effect.ensuring(\n Live.use((live) =>\n Effect.andThen(live.callEnded(call.id), call.name === sendUserMessageName ? live.typing(false) : Effect.void)\n )\n )\n )\n\n return AssistantEvent.ToolResult.make({ callId: call.id, tool: call.name, ...result })\n})\n\n// A call that needs approval waits for the user in a turn. A specialist's run can't ask them, so its call fails.\nconst awaitApproval = Effect.fnUntraced(function* (call: AssistantEvent.ToolCallPart) {\n if (Option.isNone(yield* TurnApprovals)) {\n return AssistantEvent.ToolResult.make({\n callId: call.id,\n tool: call.name,\n ...Toolkits.failed(\n `${call.name} needs the user's approval, and only the assistant can ask for it. Don't run it: say in your answer what needs approving, with the details.`,\n \"NeedsApproval\"\n )\n })\n }\n\n return AssistantEvent.ApprovalRequested.make({ callId: call.id, tool: call.name, params: call.params })\n})\n\ninterface Pending {\n readonly call: AssistantEvent.ToolCallPart\n /** The user approved it: it runs without asking again. */\n readonly approved: boolean\n}\n\ninterface Ran {\n /** One of the calls failed, so the model has to read the results. */\n readonly failed: boolean\n /** One of the calls waits for the user's approval, so the turn ends. */\n readonly waiting: boolean\n}\n\n// The approval shows the call, not what it does: the user learns that from the assistant's message beside it.\nconst unexplained = (call: AssistantEvent.ToolCallPart) =>\n AssistantEvent.ToolResult.make({\n callId: call.id,\n tool: call.name,\n ...Toolkits.failed(\n `Not sent for approval: the user would see buttons without knowing what they approve. In one step, send them a message with send_user_message saying what ${call.name} will do (what, to whom, how many), and call ${call.name} again.`,\n \"ApprovalNeedsMessage\"\n )\n })\n\n// Every `ToolStarted` is stored before any call runs; a call that waits for approval doesn't start.\nconst runCalls = <R, S, E, R2>(\n tools: Toolkits.Tools<R>,\n pending: ReadonlyArray<Pending>,\n history: ReadonlyArray<Prompt.Message>,\n then: (ran: Ran) => Stream.Stream<Step<never, S>, E, R2>\n): Stream.Stream<Step<Event, S>, E, R | R2> =>\n Stream.unwrap(\n Effect.gen(function* () {\n const waits = yield* Effect.forEach(pending, ({ call, approved }) =>\n approved ? Effect.succeed(false) : tools.needsApproval(call, history)\n )\n\n const started = pending.flatMap(({ call }, i) =>\n waits[i] === true ? [] : [value(AssistantEvent.ToolStarted.make({ callId: call.id, tool: call.name }))]\n )\n\n return Stream.fromIterable(started).pipe(\n Stream.concat(\n Stream.unwrap(\n Effect.gen(function* () {\n const explained = pending.some(({ call }) => isUserMessage(call))\n\n // Text that became no message, or a message that failed, stops the typing too.\n const done = yield* Effect.forEach(\n pending,\n ({ call }, i): Effect.Effect<Event, never, R> =>\n waits[i] !== true\n ? runCall(tools, call)\n : explained\n ? awaitApproval(call)\n : Effect.succeed(unexplained(call)),\n { concurrency: \"unbounded\" }\n ).pipe(Effect.ensuring(Live.use((live) => live.typing(false))))\n\n return Stream.fromIterable(done.map(value)).pipe(\n Stream.concat(\n then({\n failed: done.some(isFailure),\n waiting: done.some((event) => Predicate.isTagged(event, \"ApprovalRequested\"))\n })\n )\n )\n })\n )\n )\n )\n })\n )\n\nconst isFailure = (event: Event) => Predicate.isTagged(event, \"ToolResult\") && event.outcome === \"failure\"\n\n/** @internal */\nexport type Step<A, S> = Data.TaggedEnum<{\n Value: { readonly value: A }\n Next: { readonly state: S }\n Stop: Record<never, never>\n}>\n\ninterface StepDefinition extends Data.TaggedEnum.WithGenerics<2> {\n readonly taggedEnum: Step<this[\"A\"], this[\"B\"]>\n}\n\nconst Steps = Data.taggedEnum<StepDefinition>()\n\n/** @internal */\nexport const value = <A>(value: A): Step<A, never> => Steps.Value({ value })\n\n/** @internal */\nexport const next = <S>(state: S): Stream.Stream<Step<never, S>> => Stream.succeed(Steps.Next({ state }))\n\n/** @internal */\n// oxlint-disable-next-line no-unnecessary-type-parameters -- `stop<number>()` types a loop's state where inference can't.\nexport const stop = <S = never>(): Stream.Stream<Step<never, S>> => Stream.succeed(Steps.Stop())\n\nconst isValue = <A, S>(step: Step<A, S>): step is Data.TaggedEnum.Value<Step<A, S>, \"Value\"> =>\n Predicate.isTagged(step, \"Value\")\n\n// A body that ends without `next` or `stop` stops too.\n/** @internal */\nexport const loop = <S, A, E, R>(\n initial: S,\n body: (state: S) => Stream.Stream<Step<A, S>, E, R>\n): Stream.Stream<A, E, R> => {\n const go = (state: S): Stream.Stream<A, E, R> =>\n Stream.suspend(() => {\n let after: Option.Option<S> = Option.none()\n\n return body(state).pipe(\n Stream.tap((step) =>\n Effect.sync(() => (after = Predicate.isTagged(step, \"Next\") ? Option.some(step.state) : after))\n ),\n Stream.filter(isValue),\n Stream.map((step) => step.value),\n Stream.concat(Stream.suspend(() => Option.match(after, { onNone: () => Stream.empty, onSome: go })))\n )\n })\n\n return go(initial)\n}\n\n/** @internal */\nexport const step = <R, S, E2 = never, R2 = never>(\n options: StepOptions<R>,\n then: (result: StepResult) => Stream.Stream<Step<never, S>, E2, R2>\n): Stream.Stream<Step<Event, S>, AiError.AiError | E2, LanguageModel.LanguageModel | R | R2> => {\n const toolkit = options.toolkit ?? Toolkits.empty\n const instructions = Predicate.isString(options.instructions) ? { text: options.instructions } : options.instructions\n\n const after = (result: StepResult) => Stream.suspend(() => then(result))\n\n return Stream.unwrap(\n Effect.gen(function* () {\n const { messages: history, throughSequence } = readHistory(yield* options.history)\n // Calls a crash cut off, with no result: they run again, with the same ids, before the model goes on.\n const cutOff = History.unansweredCalls(history)\n const approvals = yield* TurnApprovals\n\n // Calls the user approved: they run as the model made them, with the same ids, before the model goes on. Not in\n // a loop without their tools.\n const approved = Option.isNone(approvals)\n ? []\n : (yield* approvals.value.approved).filter(\n (call) =>\n toolkit.definitions.some((tool) => tool.name === call.name) && !cutOff.some((cut) => cut.id === call.id)\n )\n\n if (cutOff.length > 0 || approved.length > 0) {\n const pending = [\n ...cutOff.map((call) => ({ call, approved: false })),\n ...approved.map((call) => ({ call, approved: true }))\n ]\n\n return runCalls(toolkit, pending, history, ({ waiting }) =>\n after({ output: undefined, done: waiting, historyLength: history.length + pending.length })\n )\n }\n\n const prompt = Prompt.fromMessages([Prompt.systemMessage({ content: instructions.text }), ...history])\n const name = yield* Effect.serviceOption(Model.ModelName)\n const started = yield* Clock.currentTimeMillis\n\n const content = yield* generate(prompt, toolkit.definitions, options.toolChoice).pipe(\n Telemetry.annotateModelCall(instructions.attributes)\n )\n\n const metadata = content.find((part) => part.type === \"response-metadata\")\n const finish = content.find((part) => part.type === \"finish\")\n\n const output = AssistantEvent.ModelOutput.make({\n parts: modelParts(content),\n seenThroughSequence: throughSequence,\n model: metadata?.modelId ?? Option.getOrUndefined(name),\n responseId: metadata?.id,\n usage: finish?.usage,\n durationMillis: (yield* Clock.currentTimeMillis) - started\n })\n\n const calls = toolCalls(output.parts)\n const historyLength = history.length + Prompt.fromResponseParts(output.parts).content.length + calls.length\n\n // A failed call doesn't end the turn: a message that failed never reached the user, so the model reads why. A call\n // that waits for approval does: the turn waits for the user.\n return Stream.make(value(output)).pipe(\n Stream.concat(\n runCalls(\n toolkit,\n calls.map((call) => ({ call, approved: false })),\n history,\n ({ failed, waiting }) =>\n after({\n output,\n done: calls.length === 0 || waiting || (!failed && calls.some(isTurnEnding)),\n historyLength\n })\n )\n )\n )\n })\n )\n}\n\n/** @internal */\nexport const run = <R = never>(\n options: Options<R>\n): Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | R> => {\n const maxSteps = options.maxSteps ?? 16\n\n // Done: stop, unless something arrived while the model was working; then it reads that first.\n const afterDone = (steps: number, historyLength: number) =>\n Stream.unwrap(\n Effect.gen(function* () {\n const read = yield* options.history\n\n return readHistory(read).messages.length > historyLength ? next(steps) : stop<number>()\n })\n )\n\n return loop(0, (steps: number) =>\n step(options, (result) => {\n const taken = result.output === undefined ? steps : steps + 1\n\n if (taken >= maxSteps) return stop<number>()\n\n return result.done ? afterDone(taken, result.historyLength) : next(taken)\n })\n )\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"loop.js","names":["Live.use","Streamed.collect","AssistantEvent.ModelPart","ToolStatus.isDescribed","ToolStatus.parameterName","Telemetry.toolOutput","Telemetry.toolSpan","Toolkits.failed","Toolkits.empty","History.unansweredCalls","Telemetry.annotateModelCall"],"sources":["../../src/internal/loop.ts"],"sourcesContent":["import type * as AiError from \"effect/ai/AiError\"\nimport * as LanguageModel from \"effect/ai/LanguageModel\"\nimport * as Model from \"effect/ai/Model\"\nimport * as Prompt from \"effect/ai/Prompt\"\nimport type * as Response from \"effect/ai/Response\"\nimport type * as Tool from \"effect/ai/Tool\"\nimport type * as Toolkit from \"effect/ai/Toolkit\"\nimport * as Clock from \"effect/Clock\"\nimport * as Context from \"effect/Context\"\nimport * as Data from \"effect/Data\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as Schema from \"effect/Schema\"\nimport * as Stream from \"effect/Stream\"\nimport * as AssistantEvent from \"../AssistantEvent.ts\"\nimport type * as Instructions from \"../Instructions.ts\"\nimport * as ToolStatus from \"../ToolStatus.ts\"\nimport * as History from \"./history.ts\"\nimport * as Live from \"./live.ts\"\nimport * as Streamed from \"./stream.ts\"\nimport * as Telemetry from \"./telemetry.ts\"\nimport * as Toolkits from \"./toolkit.ts\"\nimport { isTurnEnding, isUserMessage, sendUserMessageName } from \"./tools.ts\"\n\n/** @internal */\nexport type Event =\n | AssistantEvent.ModelOutput\n | AssistantEvent.ToolStarted\n | AssistantEvent.ToolResult\n | AssistantEvent.ApprovalRequested\n\n// Only a turn's loop can wait for the user's approval, and runs the calls they approved. A turn's specialists inherit\n// its context, so their runs set it back to none.\n/** @internal */\nexport const TurnApprovals = Context.Reference<\n Option.Option<{ readonly approved: Effect.Effect<ReadonlyArray<AssistantEvent.ToolCallPart>> }>\n>(\"effect-assistant/TurnApprovals\", { defaultValue: Option.none })\n\n// The assistant's own tools with the turn's services, so an app's own loop in a turn can message the user. A\n// specialist's run has none.\n/** @internal */\nexport const TurnTools = Context.Reference<Option.Option<Toolkits.Tools>>(\"effect-assistant/TurnTools\", {\n defaultValue: Option.none\n})\n\n/** @internal */\nexport interface ChatHistory {\n readonly messages: ReadonlyArray<Prompt.Message>\n readonly throughSequence: number\n}\n\nconst readHistory = (read: ReadonlyArray<Prompt.Message> | ChatHistory) =>\n \"messages\" in read\n ? { messages: read.messages, throughSequence: read.throughSequence }\n : { messages: read, throughSequence: undefined }\n\n// `AssistantLoop` takes native toolkits; turns and specialist runs come here with their tools already merged.\n/** @internal */\nexport interface StepOptions<R = never> {\n readonly instructions: string | Instructions.Resolved\n readonly toolkit?: Toolkits.Tools<R> | undefined\n readonly history: Effect.Effect<ReadonlyArray<Prompt.Message> | ChatHistory>\n readonly toolChoice?: LanguageModel.ToolChoice<string> | undefined\n}\n\n/** @internal */\nexport interface Options<R = never> extends StepOptions<R> {\n readonly maxSteps?: number | undefined\n}\n\n// Its member docs show through `AssistantLoop.StepResult`.\n/** @internal */\nexport interface StepResult {\n /** The model's output; unset when the step only ran calls a crash cut off. */\n readonly output: AssistantEvent.ModelOutput | undefined\n /**\n * Whether the model is done: it made no tool calls, one of its calls waits for the user's\n * approval, or it ended its turn (`wait`, or a message with `wait: true`) and none of the step's\n * calls failed.\n */\n readonly done: boolean\n /**\n * The history's length with this step's output and results: a longer one got something new meanwhile.\n */\n readonly historyLength: number\n}\n\n// A tool as `Tool.isUserDefined` narrows one. With `Tool.Any`, generateText's types ask for the services that encode\n// every tool's params, `unknown` for a schema of unknown type, though deferred validation encodes none.\ntype RequestTool = Tool.Tool<string, any, any>\n\n// The loop runs the calls itself, after storing each as started, so the model call runs none. It also decides which\n// calls wait for approval: the model call would ask for approvals of its own.\nconst requestToolkit = (definitions: ReadonlyArray<Tool.Any>): Toolkit.WithHandler<Record<string, RequestTool>> => ({\n tools: Object.fromEntries(\n definitions.map((tool) => [\n tool.name,\n tool.needsApproval === undefined || tool.needsApproval === false ? tool : tool.setNeedsApproval(false)\n ])\n ),\n handle: () => Effect.succeed(Stream.empty)\n})\n\n// The model starts a message to the user: a `send_user_message` call, or text of its own, which the reply pass turns\n// into one.\nconst startsMessage = (part: Response.AnyPart) =>\n part.type === \"text-start\" || (part.type === \"tool-params-start\" && part.name === sendUserMessageName)\n\n// Validation is deferred: a call to a tool that isn't in the toolkit (one in the history the turn no longer offers),\n// or with params that don't fit its schema, would otherwise fail the whole model call. The loop runs it instead, and\n// the model reads why it failed.\n// Streamed, so the chat can show the user that a message is on its way while the model writes it.\nconst generate = (\n prompt: Prompt.Prompt,\n definitions: ReadonlyArray<Tool.Any>,\n toolChoice: LanguageModel.ToolChoice<string> | undefined\n): Effect.Effect<ReadonlyArray<Response.AnyPart>, AiError.AiError, LanguageModel.LanguageModel> =>\n Stream.suspend(() =>\n LanguageModel.streamText({\n prompt,\n toolkit: requestToolkit(definitions),\n toolChoice,\n disableToolCallResolution: true,\n toolCallValidation: \"deferred\"\n })\n ).pipe(\n Stream.tap((part) => (startsMessage(part) ? Live.use((live) => live.typing(true)) : Effect.void)),\n Stream.runCollect,\n Effect.map(Streamed.collect)\n )\n\nconst decodePart = Schema.decodeUnknownOption(AssistantEvent.ModelPart)\n\nconst modelParts = (content: ReadonlyArray<Response.AnyPart>) =>\n content.flatMap((part) =>\n Option.toArray(decodePart(part)).filter((decoded) => !(decoded.type === \"tool-call\" && decoded.providerExecuted))\n )\n\nconst toolCalls = (parts: ReadonlyArray<AssistantEvent.ModelPart>): ReadonlyArray<AssistantEvent.ToolCallPart> =>\n parts.flatMap((part) => (part.type === \"tool-call\" ? [part] : []))\n\nconst decodeParams = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Json))\n\nconst isDescribedCall = <R>(tools: Toolkits.Tools<R>, call: AssistantEvent.ToolCallPart) =>\n tools.definitions.some((tool) => tool.name === call.name && ToolStatus.isDescribed(tool))\n\nconst statusOf = (call: AssistantEvent.ToolCallPart): string | undefined =>\n decodeParams(call.params).pipe(\n Option.flatMapNullishOr((params) => params[ToolStatus.parameterName]),\n Option.filter(Predicate.isString),\n Option.map((written) => written.trim()),\n Option.filter((status) => status !== \"\"),\n Option.getOrUndefined\n )\n\n// A call's status shows when it starts; a message's typing stops once the message is stored.\nconst runCall = Effect.fnUntraced(function* <R>(tools: Toolkits.Tools<R>, call: AssistantEvent.ToolCallPart) {\n const status = isDescribedCall(tools, call) ? statusOf(call) : undefined\n\n const result = yield* Effect.gen(function* () {\n if (status !== undefined) yield* Live.use((live) => live.callStarted(call.id, status))\n\n const result = yield* tools.run(call)\n\n yield* Telemetry.toolOutput(result.result)\n\n return result\n }).pipe(\n Telemetry.toolSpan(call),\n Effect.ensuring(\n Live.use((live) =>\n Effect.andThen(live.callEnded(call.id), call.name === sendUserMessageName ? live.typing(false) : Effect.void)\n )\n )\n )\n\n return AssistantEvent.ToolResult.make({ callId: call.id, tool: call.name, ...result })\n})\n\n// A call that needs approval waits for the user in a turn. A specialist's run can't ask them, so its call fails.\nconst awaitApproval = Effect.fnUntraced(function* (call: AssistantEvent.ToolCallPart) {\n if (Option.isNone(yield* TurnApprovals)) {\n return AssistantEvent.ToolResult.make({\n callId: call.id,\n tool: call.name,\n ...Toolkits.failed(\n `${call.name} needs the user's approval, and only the assistant can ask for it. Don't run it: say in your answer what needs approving, with the details.`,\n \"NeedsApproval\"\n )\n })\n }\n\n return AssistantEvent.ApprovalRequested.make({ callId: call.id, tool: call.name, params: call.params })\n})\n\ninterface Pending {\n readonly call: AssistantEvent.ToolCallPart\n /** The user approved it: it runs without asking again. */\n readonly approved: boolean\n}\n\ninterface Ran {\n /** One of the calls failed, so the model has to read the results. */\n readonly failed: boolean\n /** One of the calls waits for the user's approval, so the turn ends. */\n readonly waiting: boolean\n}\n\n// The approval shows the call, not what it does: the user learns that from the assistant's message beside it.\nconst unexplained = (call: AssistantEvent.ToolCallPart) =>\n AssistantEvent.ToolResult.make({\n callId: call.id,\n tool: call.name,\n ...Toolkits.failed(\n `Not sent for approval: the user would see buttons without knowing what they approve. In one step, send them a message with send_user_message saying what ${call.name} will do (what, to whom, how many), and call ${call.name} again.`,\n \"ApprovalNeedsMessage\"\n )\n })\n\n// Every `ToolStarted` is stored before any call runs; a call that waits for approval doesn't start.\nconst runCalls = <R, S, E, R2>(\n tools: Toolkits.Tools<R>,\n pending: ReadonlyArray<Pending>,\n history: ReadonlyArray<Prompt.Message>,\n then: (ran: Ran) => Stream.Stream<Step<never, S>, E, R2>\n): Stream.Stream<Step<Event, S>, E, R | R2> =>\n Stream.unwrap(\n Effect.gen(function* () {\n const waits = yield* Effect.forEach(pending, ({ call, approved }) =>\n approved ? Effect.succeed(false) : tools.needsApproval(call, history)\n )\n\n const started = pending.flatMap(({ call }, i) =>\n waits[i] === true ? [] : [value(AssistantEvent.ToolStarted.make({ callId: call.id, tool: call.name }))]\n )\n\n return Stream.fromIterable(started).pipe(\n Stream.concat(\n Stream.unwrap(\n Effect.gen(function* () {\n const explained = pending.some(({ call }) => isUserMessage(call))\n\n // Text that became no message, or a message that failed, stops the typing too.\n const done = yield* Effect.forEach(\n pending,\n ({ call }, i): Effect.Effect<Event, never, R> =>\n waits[i] !== true\n ? runCall(tools, call)\n : explained\n ? awaitApproval(call)\n : Effect.succeed(unexplained(call)),\n { concurrency: \"unbounded\" }\n ).pipe(Effect.ensuring(Live.use((live) => live.typing(false))))\n\n return Stream.fromIterable(done.map(value)).pipe(\n Stream.concat(\n then({\n failed: done.some(isFailure),\n waiting: done.some((event) => Predicate.isTagged(event, \"ApprovalRequested\"))\n })\n )\n )\n })\n )\n )\n )\n })\n )\n\nconst isFailure = (event: Event) => Predicate.isTagged(event, \"ToolResult\") && event.outcome === \"failure\"\n\n/** @internal */\nexport type Step<A, S> = Data.TaggedEnum<{\n Value: { readonly value: A }\n Next: { readonly state: S }\n Stop: Record<never, never>\n}>\n\ninterface StepDefinition extends Data.TaggedEnum.WithGenerics<2> {\n readonly taggedEnum: Step<this[\"A\"], this[\"B\"]>\n}\n\nconst Steps = Data.taggedEnum<StepDefinition>()\n\n/** @internal */\nexport const value = <A>(value: A): Step<A, never> => Steps.Value({ value })\n\n/** @internal */\nexport const next = <S>(state: S): Stream.Stream<Step<never, S>> => Stream.succeed(Steps.Next({ state }))\n\n/** @internal */\n// oxlint-disable-next-line no-unnecessary-type-parameters -- `stop<number>()` types a loop's state where inference can't.\nexport const stop = <S = never>(): Stream.Stream<Step<never, S>> => Stream.succeed(Steps.Stop())\n\nconst isValue = <A, S>(step: Step<A, S>): step is Data.TaggedEnum.Value<Step<A, S>, \"Value\"> =>\n Predicate.isTagged(step, \"Value\")\n\n// A body that ends without `next` or `stop` stops too.\n/** @internal */\nexport const loop = <S, A, E, R>(\n initial: S,\n body: (state: S) => Stream.Stream<Step<A, S>, E, R>\n): Stream.Stream<A, E, R> => {\n const go = (state: S): Stream.Stream<A, E, R> =>\n Stream.suspend(() => {\n let after: Option.Option<S> = Option.none()\n\n return body(state).pipe(\n Stream.tap((step) =>\n Effect.sync(() => (after = Predicate.isTagged(step, \"Next\") ? Option.some(step.state) : after))\n ),\n Stream.filter(isValue),\n Stream.map((step) => step.value),\n Stream.concat(Stream.suspend(() => Option.match(after, { onNone: () => Stream.empty, onSome: go })))\n )\n })\n\n return go(initial)\n}\n\n/** @internal */\nexport const step = <R, S, E2 = never, R2 = never>(\n options: StepOptions<R>,\n then: (result: StepResult) => Stream.Stream<Step<never, S>, E2, R2>\n): Stream.Stream<Step<Event, S>, AiError.AiError | E2, LanguageModel.LanguageModel | R | R2> => {\n const toolkit = options.toolkit ?? Toolkits.empty\n const instructions = Predicate.isString(options.instructions) ? { text: options.instructions } : options.instructions\n\n const after = (result: StepResult) => Stream.suspend(() => then(result))\n\n return Stream.unwrap(\n Effect.gen(function* () {\n const { messages: history, throughSequence } = readHistory(yield* options.history)\n // Calls a crash cut off, with no result: they run again, with the same ids, before the model goes on.\n const cutOff = History.unansweredCalls(history)\n const approvals = yield* TurnApprovals\n\n // Calls the user approved: they run as the model made them, with the same ids, before the model goes on. Not in\n // a loop without their tools.\n const approved = Option.isNone(approvals)\n ? []\n : (yield* approvals.value.approved).filter(\n (call) =>\n toolkit.definitions.some((tool) => tool.name === call.name) && !cutOff.some((cut) => cut.id === call.id)\n )\n\n if (cutOff.length > 0 || approved.length > 0) {\n const pending = [\n ...cutOff.map((call) => ({ call, approved: false })),\n ...approved.map((call) => ({ call, approved: true }))\n ]\n\n return runCalls(toolkit, pending, history, ({ waiting }) =>\n after({ output: undefined, done: waiting, historyLength: history.length + pending.length })\n )\n }\n\n const prompt = Prompt.fromMessages([Prompt.systemMessage({ content: instructions.text }), ...history])\n const name = yield* Effect.serviceOption(Model.ModelName)\n const started = yield* Clock.currentTimeMillis\n\n const content = yield* generate(prompt, toolkit.definitions, options.toolChoice).pipe(\n Telemetry.annotateModelCall(instructions.attributes)\n )\n\n const metadata = content.find((part) => part.type === \"response-metadata\")\n const finish = content.find((part) => part.type === \"finish\")\n\n const output = AssistantEvent.ModelOutput.make({\n parts: modelParts(content),\n seenThroughSequence: throughSequence,\n model: metadata?.modelId ?? Option.getOrUndefined(name),\n responseId: metadata?.id,\n usage: finish?.usage,\n durationMillis: (yield* Clock.currentTimeMillis) - started\n })\n\n const calls = toolCalls(output.parts)\n const historyLength = history.length + Prompt.fromResponseParts(output.parts).content.length + calls.length\n\n // A failed call doesn't end the turn: a message that failed never reached the user, so the model reads why. A call\n // that waits for approval does: the turn waits for the user.\n return Stream.make(value(output)).pipe(\n Stream.concat(\n runCalls(\n toolkit,\n calls.map((call) => ({ call, approved: false })),\n history,\n ({ failed, waiting }) =>\n after({\n output,\n done: calls.length === 0 || waiting || (!failed && calls.some(isTurnEnding)),\n historyLength\n })\n )\n )\n )\n })\n )\n}\n\n/** @internal */\nexport const run = <R = never>(\n options: Options<R>\n): Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | R> => {\n const maxSteps = options.maxSteps ?? 16\n\n // Done: stop, unless something arrived while the model was working; then it reads that first.\n const afterDone = (steps: number, historyLength: number) =>\n Stream.unwrap(\n Effect.gen(function* () {\n const read = yield* options.history\n\n return readHistory(read).messages.length > historyLength ? next(steps) : stop<number>()\n })\n )\n\n return loop(0, (steps: number) =>\n step(options, (result) => {\n const taken = result.output === undefined ? steps : steps + 1\n\n if (taken >= maxSteps) return stop<number>()\n\n return result.done ? afterDone(taken, result.historyLength) : next(taken)\n })\n )\n}\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "effect-assistant",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "description": "A colleague assistant on Effect: an append-only event log per chat, an interruptible agent loop, specialists, skills, and UI blocks",
5
5
  "license": "MIT",
6
6
  "repository": {
package/src/ToolStatus.ts CHANGED
@@ -2,25 +2,18 @@
2
2
  * This module provides status labels for tool calls: while a call runs, the chat shows the user a
3
3
  * short line about what the assistant is doing, like "Checking last summer's campaign budget".
4
4
  *
5
- * Mark the tools that take a while or act on something with {@link described}: workflows, reports
6
- * from other systems, orders, specialists. The model then sees a required `description` parameter
7
- * on them and fills it in the chat's language. When the call starts, the chat sends the
8
- * description as a `ChatSignal.Status`; it shows until the next status, so it stays after the call
9
- * ends. The tool's handler never receives the parameter. Quick reads need no label: the chat shows its generic working state for
10
- * them.
5
+ * Give the tools that take a while or act on something a status field with {@link withStatus}:
6
+ * workflows, reports from other systems, orders, specialists. Their parameters get a required
7
+ * `description` field that the model fills in the chat's language. When the call starts, the chat
8
+ * sends the description as a `ChatSignal.Status`; it shows until the next status, so it stays
9
+ * after the call ends. The call runs unchanged: the handler gets `description` with its other
10
+ * parameters. Quick reads need no label: the chat shows its generic working state for them.
11
11
  *
12
12
  * @since 0.13.0
13
13
  */
14
14
  import type * as Tool from "effect/ai/Tool"
15
- import * as Context from "effect/Context"
16
- import type * as Schema from "effect/Schema"
17
-
18
- type Schemas = {
19
- readonly parameters: Schema.Constraint
20
- readonly success: Schema.Constraint
21
- readonly failure: Schema.Constraint
22
- readonly failureMode: Tool.FailureMode
23
- }
15
+ import * as Schema from "effect/Schema"
16
+ import * as SchemaAST from "effect/SchemaAST"
24
17
 
25
18
  /**
26
19
  * The name of the parameter the model fills with a call's status.
@@ -39,53 +32,85 @@ export const parameterName = "description"
39
32
  export const parameterDescription =
40
33
  "Shown to the user while this runs: 3 to 8 plain words in the user's language about what you're doing, like \"Checking last summer's campaign budget\". No tool names, ids or code."
41
34
 
35
+ const statusFieldKey = "effect-assistant/ToolStatus/statusField"
36
+
42
37
  /**
43
- * Annotation for whether a tool's calls show a status, set with {@link described}.
38
+ * The schema of the status field {@link withStatus} adds.
44
39
  *
45
- * @category annotations
46
- * @since 0.13.0
40
+ * @category schemas
41
+ * @since 0.16.0
47
42
  */
48
- export const Described = Context.Reference<boolean>("effect-assistant/ToolStatus/Described", {
49
- defaultValue: () => false
50
- })
43
+ export const StatusField = Schema.String.annotate({ description: parameterDescription, [statusFieldKey]: true })
51
44
 
52
45
  /**
53
- * Marks a tool whose calls show a status while they run.
46
+ * The parameter fields a struct can't have to take a status field: a `description` field of its own.
47
+ *
48
+ * @category models
49
+ * @since 0.16.0
50
+ */
51
+ export type WithoutStatus<Fields extends Schema.Struct.Fields> = typeof parameterName extends keyof Fields
52
+ ? "Error: these parameters have a description field already, so they can't take a status: rename it"
53
+ : unknown
54
+
55
+ /**
56
+ * Adds the status field to a tool's parameters, so its calls show a status while they run.
54
57
  *
55
58
  * **Details**
56
59
  *
57
- * The model sees a required `description` parameter on the tool, and the chat shows what it
58
- * writes there while the call runs. Required, because models leave optional parameters out; a call
59
- * without it still runs, with no status. The handler gets its parameters without it. A tool that has a
60
- * parameter of that name already can't be marked: the loop stops with a defect when it offers one.
60
+ * The struct gets a required `description` field ({@link StatusField}), and keeps its own
61
+ * annotations and checks. Required, because models leave optional parameters out. The chat shows
62
+ * what the model writes there while the call runs; a call with a blank one runs with no status,
63
+ * and a call without it fails validation like a call without any other required parameter. The
64
+ * handler gets `description` like any other parameter. A struct that has a `description` field
65
+ * already is a type error. A tool without parameters takes `Schema.Struct({})`.
61
66
  *
62
- * **Example** (A slow report with a status)
67
+ * **Example** (A tool whose calls show a status)
63
68
  *
64
69
  * ```ts
65
70
  * import { ToolStatus } from "effect-assistant"
66
71
  * import * as Tool from "effect/ai/Tool"
67
72
  * import * as Schema from "effect/Schema"
68
73
  *
69
- * export const CampaignReport = ToolStatus.described(
70
- * Tool.make("campaign_report", {
71
- * description: "The spend and results of a past campaign.",
72
- * parameters: Schema.Struct({ campaignId: Schema.String }),
73
- * success: Schema.Struct({ spent: Schema.Finite })
74
- * })
75
- * )
74
+ * export const ArchiveNote = Tool.make("archive_note", {
75
+ * description: "Archives a note and the files attached to it.",
76
+ * parameters: Schema.Struct({ noteId: Schema.String }).pipe(ToolStatus.withStatus),
77
+ * success: Schema.Struct({ archived: Schema.Boolean })
78
+ * })
76
79
  * ```
77
80
  *
78
- * @category annotations
79
- * @since 0.13.0
81
+ * @category combinators
82
+ * @since 0.16.0
80
83
  */
81
- export const described = <Name extends string, Config extends Schemas, R>(
82
- tool: Tool.Tool<Name, Config, R>
83
- ): Tool.Tool<Name, Config, R> => tool.annotate(Described, true)
84
+ export const withStatus = <Fields extends Schema.Struct.Fields>(
85
+ self: Schema.Struct<Fields> & WithoutStatus<Fields>
86
+ ) => {
87
+ const struct = self.mapFields((fields) => ({ ...fields, [parameterName]: StatusField }))
88
+
89
+ return struct.rebuild(
90
+ new SchemaAST.Objects(
91
+ struct.ast.propertySignatures,
92
+ struct.ast.indexSignatures,
93
+ self.ast.annotations,
94
+ self.ast.checks
95
+ )
96
+ )
97
+ }
84
98
 
85
99
  /**
86
- * Returns whether a tool's calls show a status.
100
+ * Returns whether a tool's calls show a status: its parameters have the field {@link withStatus}
101
+ * adds. A `description` parameter of its own doesn't count.
87
102
  *
88
103
  * @category guards
89
104
  * @since 0.13.0
90
105
  */
91
- export const isDescribed = (tool: Tool.Any): boolean => Context.get(tool.annotations, Described)
106
+ export const isDescribed = (tool: Tool.Any): boolean => {
107
+ const ast = tool.parametersSchema.ast
108
+
109
+ return (
110
+ SchemaAST.isObjects(ast) &&
111
+ ast.propertySignatures.some(
112
+ (property) =>
113
+ property.name === parameterName && SchemaAST.resolveAt<boolean>(statusFieldKey)(property.type) === true
114
+ )
115
+ )
116
+ }
@@ -12,7 +12,6 @@ import * as Effect from "effect/Effect"
12
12
  import * as Option from "effect/Option"
13
13
  import * as Predicate from "effect/Predicate"
14
14
  import * as Schema from "effect/Schema"
15
- import * as SchemaAST from "effect/SchemaAST"
16
15
  import * as Stream from "effect/Stream"
17
16
  import * as AssistantEvent from "../AssistantEvent.ts"
18
17
  import type * as Instructions from "../Instructions.ts"
@@ -91,49 +90,14 @@ export interface StepResult {
91
90
  // every tool's params, `unknown` for a schema of unknown type, though deferred validation encodes none.
92
91
  type RequestTool = Tool.Tool<string, any, any>
93
92
 
94
- // Required in what the model reads, so it writes one with every call; a call without it still runs.
95
- const statusParameter = Schema.String.annotate({ description: ToolStatus.parameterDescription })
96
-
97
- // What the model reads of a described tool: its parameters with the status one. Only the request has it; the call
98
- // runs without it (see `withoutStatus`). A record of no keys (a tool without parameters) becomes an object with it.
99
- const withStatusParameter = (tool: Tool.Any): Tool.Any => {
100
- const ast = tool.parametersSchema.ast
101
-
102
- if (!ToolStatus.isDescribed(tool) || !SchemaAST.isObjects(ast)) return tool
103
-
104
- if (ast.propertySignatures.some((property) => property.name === ToolStatus.parameterName)) {
105
- throw new Error(
106
- `${tool.name} has a parameter named ${ToolStatus.parameterName} already, so it can't show a status: rename it.`
107
- )
108
- }
109
-
110
- const added = Schema.Struct({ [ToolStatus.parameterName]: statusParameter }).ast.propertySignatures
111
-
112
- return tool.setParameters(
113
- Schema.make<Schema.Top>(
114
- new SchemaAST.Objects(
115
- [...ast.propertySignatures, ...added],
116
- ast.indexSignatures.filter((index) => !SchemaAST.isNever(index.type)),
117
- ast.annotations
118
- )
119
- )
120
- )
121
- }
122
-
123
93
  // The loop runs the calls itself, after storing each as started, so the model call runs none. It also decides which
124
94
  // calls wait for approval: the model call would ask for approvals of its own.
125
95
  const requestToolkit = (definitions: ReadonlyArray<Tool.Any>): Toolkit.WithHandler<Record<string, RequestTool>> => ({
126
96
  tools: Object.fromEntries(
127
- definitions.map((tool) => {
128
- const requested = withStatusParameter(tool)
129
-
130
- return [
131
- tool.name,
132
- requested.needsApproval === undefined || requested.needsApproval === false
133
- ? requested
134
- : requested.setNeedsApproval(false)
135
- ]
136
- })
97
+ definitions.map((tool) => [
98
+ tool.name,
99
+ tool.needsApproval === undefined || tool.needsApproval === false ? tool : tool.setNeedsApproval(false)
100
+ ])
137
101
  ),
138
102
  handle: () => Effect.succeed(Stream.empty)
139
103
  })
@@ -181,26 +145,23 @@ const decodeParams = Schema.decodeUnknownOption(Schema.Record(Schema.String, Sch
181
145
  const isDescribedCall = <R>(tools: Toolkits.Tools<R>, call: AssistantEvent.ToolCallPart) =>
182
146
  tools.definitions.some((tool) => tool.name === call.name && ToolStatus.isDescribed(tool))
183
147
 
184
- // The status the model wrote for a described tool's call, and the call as the tool's handler gets it.
185
- const splitStatus = (call: AssistantEvent.ToolCallPart): readonly [string | undefined, AssistantEvent.ToolCallPart] => {
186
- const params = decodeParams(call.params)
187
-
188
- if (Option.isNone(params) || !Object.hasOwn(params.value, ToolStatus.parameterName)) return [undefined, call]
189
-
190
- const { [ToolStatus.parameterName]: written, ...rest } = params.value
191
- const status = Predicate.isString(written) ? written.trim() : ""
192
-
193
- return [status === "" ? undefined : status, { ...call, params: rest }]
194
- }
148
+ const statusOf = (call: AssistantEvent.ToolCallPart): string | undefined =>
149
+ decodeParams(call.params).pipe(
150
+ Option.flatMapNullishOr((params) => params[ToolStatus.parameterName]),
151
+ Option.filter(Predicate.isString),
152
+ Option.map((written) => written.trim()),
153
+ Option.filter((status) => status !== ""),
154
+ Option.getOrUndefined
155
+ )
195
156
 
196
157
  // A call's status shows when it starts; a message's typing stops once the message is stored.
197
158
  const runCall = Effect.fnUntraced(function* <R>(tools: Toolkits.Tools<R>, call: AssistantEvent.ToolCallPart) {
198
- const [status, run] = isDescribedCall(tools, call) ? splitStatus(call) : [undefined, call]
159
+ const status = isDescribedCall(tools, call) ? statusOf(call) : undefined
199
160
 
200
161
  const result = yield* Effect.gen(function* () {
201
162
  if (status !== undefined) yield* Live.use((live) => live.callStarted(call.id, status))
202
163
 
203
- const result = yield* tools.run(run)
164
+ const result = yield* tools.run(call)
204
165
 
205
166
  yield* Telemetry.toolOutput(result.result)
206
167