ovr 7.0.0-next.2 → 7.0.0-next.21

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 (52) hide show
  1. package/CHANGELOG.md +1157 -0
  2. package/dist/auth/client-source.d.ts +2 -2
  3. package/dist/auth/client-source.d.ts.map +1 -1
  4. package/dist/auth/client-source.js +2 -2
  5. package/dist/auth/client.d.ts.map +1 -1
  6. package/dist/auth/client.js +7 -4
  7. package/dist/auth/configure.d.ts +21 -8
  8. package/dist/auth/configure.d.ts.map +1 -1
  9. package/dist/auth/configure.js +172 -6
  10. package/dist/auth/index.d.ts +48 -0
  11. package/dist/auth/index.d.ts.map +1 -1
  12. package/dist/auth/index.js +19 -0
  13. package/dist/auth/passkey.d.ts +14 -2
  14. package/dist/auth/passkey.d.ts.map +1 -1
  15. package/dist/auth/passkey.js +18 -5
  16. package/dist/auth/state.d.ts +6 -0
  17. package/dist/auth/state.d.ts.map +1 -1
  18. package/dist/auth/state.js +28 -5
  19. package/dist/auth/storage.d.ts +38 -0
  20. package/dist/auth/storage.d.ts.map +1 -1
  21. package/dist/auth/storage.js +60 -3
  22. package/dist/context/index.d.ts +4 -4
  23. package/dist/context/index.d.ts.map +1 -1
  24. package/dist/context/index.js +6 -3
  25. package/dist/form/index.d.ts +239 -31
  26. package/dist/form/index.d.ts.map +1 -1
  27. package/dist/form/index.js +657 -66
  28. package/dist/markdown/index.d.ts +6 -1
  29. package/dist/markdown/index.d.ts.map +1 -1
  30. package/dist/markdown/index.js +180 -9
  31. package/dist/mcp/index.d.ts.map +1 -1
  32. package/dist/mcp/index.js +154 -57
  33. package/dist/schema/index.d.ts +88 -19
  34. package/dist/schema/index.d.ts.map +1 -1
  35. package/dist/schema/index.js +32 -11
  36. package/dist/util/index.d.ts +12 -0
  37. package/dist/util/index.d.ts.map +1 -1
  38. package/dist/util/index.js +19 -0
  39. package/package.json +2 -1
  40. package/src/auth/client-source.ts +2 -2
  41. package/src/auth/client.ts +7 -4
  42. package/src/auth/configure.ts +189 -13
  43. package/src/auth/index.ts +44 -0
  44. package/src/auth/passkey.ts +25 -7
  45. package/src/auth/state.ts +32 -7
  46. package/src/auth/storage.ts +66 -3
  47. package/src/context/index.ts +14 -6
  48. package/src/form/index.ts +1174 -195
  49. package/src/markdown/index.ts +203 -12
  50. package/src/mcp/index.ts +205 -72
  51. package/src/schema/index.ts +195 -52
  52. package/src/util/index.ts +23 -0
@@ -64,13 +64,23 @@ export namespace Markdown {
64
64
  *
65
65
  * @param method Form method
66
66
  * @param action Resolved form action
67
- * @returns The tool's name, and the arguments from the address's parameters
67
+ * @returns The tool's name, the arguments from the address's parameters,
68
+ * the fields whose choices are given as the form renders, which its
69
+ * input schema can't list, and the fields it takes as an array, which
70
+ * the form shows as rows or lines
68
71
  */
69
72
  readonly [tools]?:
70
73
  | ((
71
74
  method: string,
72
75
  action: URL,
73
- ) => { name: string; args: Record<string, string> } | undefined)
76
+ ) =>
77
+ | {
78
+ name: string;
79
+ args: Record<string, string>;
80
+ choices: ReadonlySet<string>;
81
+ lists: ReadonlySet<string>;
82
+ }
83
+ | undefined)
74
84
  | undefined;
75
85
  };
76
86
  }
@@ -166,6 +176,9 @@ class Writer {
166
176
  /** Writing a form's table, where a control in a cell is named */
167
177
  #controls = false;
168
178
 
179
+ /** The array fields of the tool whose form's table is being written */
180
+ #arrays: ReadonlySet<string> | undefined;
181
+
169
182
  /** Reader mode: before, inside, or after `<main>` */
170
183
  #main: "before" | "inside" | "after" = "before";
171
184
 
@@ -710,6 +723,8 @@ class Writer {
710
723
  if (child.tag === "option") {
711
724
  const text = Writer.#plain(child);
712
725
  const value = child.attrs.value ?? text;
726
+ // the empty choice of a select that may be left empty
727
+ if (!value) continue;
713
728
  entry.options.push(
714
729
  `${value}${text && text !== value ? ` (${text})` : ""}`,
715
730
  );
@@ -780,11 +795,23 @@ class Writer {
780
795
  // its controls are fields, and the table is kept, with each
781
796
  // control named in its cell, a row's button included
782
797
  const before = submits.length;
798
+ const from = fields.length;
783
799
  visit(child, label, true);
784
800
  submits.length = before;
801
+ // a table of a list's rows alone is left out: the tool's
802
+ // form lists its items as the array an agent sends
803
+ const within = fields.slice(from);
804
+ if (
805
+ tool &&
806
+ within.length &&
807
+ within.every((f) => Writer.#cell(f.name, tool.lists))
808
+ )
809
+ break;
785
810
  this.#controls = true;
811
+ this.#arrays = tool?.lists;
786
812
  block(this.#table(child));
787
813
  this.#controls = false;
814
+ this.#arrays = undefined;
788
815
  break;
789
816
  }
790
817
  case "pre":
@@ -849,16 +876,20 @@ class Writer {
849
876
 
850
877
  const lines = tool
851
878
  ? // the tool's input schema describes the fields, so only what the
852
- // page adds: current values, such as an edit form's, and messages
853
- fields
854
- .map((f) =>
879
+ // page adds: current values, such as an edit form's, choices
880
+ // known only as it renders, such as a record's own IDs, and messages
881
+ Writer.#gather(fields, tool.lists)
882
+ .map((f) => ({
855
883
  // a single checkbox is a boolean argument, unchecked included
856
- f.lone ? { ...f, value: [String(f.value.length > 0)] } : f,
857
- )
858
- .filter((f) => f.value.length || f.notes.length)
884
+ ...(f.lone ? { ...f, value: [String(f.value.length > 0)] } : f),
885
+ options: tool.choices.has(f.name) ? f.options : [],
886
+ }))
887
+ .filter((f) => f.value.length || f.options.length || f.notes.length)
859
888
  .map((f) => {
860
889
  let line = `- ${Writer.#code(f.name)}`;
861
890
  if (f.value.length) line += `: ${Writer.#codes(f.value)}`;
891
+ if (f.options.length)
892
+ line += `, options: ${Writer.#codes(f.options)}`;
862
893
  return Writer.#notes(f, line);
863
894
  })
864
895
  : fields.map((f) => {
@@ -895,6 +926,153 @@ class Writer {
895
926
  ].join("\n");
896
927
  }
897
928
 
929
+ /**
930
+ * @param name A control's name
931
+ * @param lists The fields a tool takes as an array
932
+ * @returns The list, place, and field of the row the control is in, named
933
+ * `steps.0` or `ingredients.0.amount`, `undefined` for any other control
934
+ */
935
+ static #cell(
936
+ name: string,
937
+ lists: ReadonlySet<string>,
938
+ ): [list: string, place: number, key: string | undefined] | undefined {
939
+ for (const list of lists) {
940
+ if (!name.startsWith(`${list}.`)) continue;
941
+ const [, place, key] =
942
+ /^(\d+)(?:\.(.+))?$/s.exec(name.slice(list.length + 1)) ?? [];
943
+ if (place !== undefined) return [list, Number(place), key];
944
+ }
945
+ }
946
+
947
+ /**
948
+ * @param select `<select>` element
949
+ * @returns The value of its selected option, `undefined` without one
950
+ */
951
+ static #chosen(select: Node): string | undefined {
952
+ for (const child of select.children) {
953
+ if (typeof child === "string") continue;
954
+ if (child.tag !== "option") {
955
+ const chosen = Writer.#chosen(child);
956
+ if (chosen !== undefined) return chosen;
957
+ } else if ("selected" in child.attrs)
958
+ return child.attrs.value ?? Writer.#plain(child);
959
+ }
960
+ }
961
+
962
+ /**
963
+ * @param fields A tool's form's fields, one for each control
964
+ * @param lists The fields the tool takes as an array
965
+ * @returns The fields as the tool takes them: a list's rows together, and
966
+ * lines apart, each as the array an agent sends
967
+ */
968
+ static #gather(fields: Field[], lists: ReadonlySet<string>) {
969
+ if (!lists.size) return fields;
970
+
971
+ const gathered: Field[] = [];
972
+ const found = new Map<
973
+ string,
974
+ { entry: Field; rows: Map<number, { value: unknown; filled: boolean }> }
975
+ >();
976
+
977
+ /** A control's value, as its argument's type */
978
+ const typed = (f: Field): unknown => {
979
+ if (f.lone) return f.value.length > 0 || undefined;
980
+ if (f.type === "checkbox" || f.type === "select multiple")
981
+ return f.value.length ? f.value : undefined;
982
+
983
+ const [value] = f.value;
984
+ if (!value) return;
985
+
986
+ return (f.type === "number" || f.type === "range") &&
987
+ Number.isFinite(Number(value))
988
+ ? Number(value)
989
+ : value;
990
+ };
991
+
992
+ for (const f of fields) {
993
+ if (lists.has(f.name)) {
994
+ // lines, one on each line of a textarea
995
+ const lines = (f.value[0] ?? "")
996
+ .split(/\r?\n/)
997
+ .map((line) => line.trim())
998
+ .filter(Boolean);
999
+ gathered.push({
1000
+ ...f,
1001
+ value: lines.length ? [JSON.stringify(lines)] : [],
1002
+ });
1003
+ continue;
1004
+ }
1005
+
1006
+ const cell = Writer.#cell(f.name, lists);
1007
+ if (!cell) {
1008
+ gathered.push(f);
1009
+ continue;
1010
+ }
1011
+
1012
+ const [list, place, key] = cell;
1013
+ let group = found.get(list);
1014
+ if (!group) {
1015
+ group = {
1016
+ entry: {
1017
+ ...f,
1018
+ label: list,
1019
+ name: list,
1020
+ value: [],
1021
+ notes: [],
1022
+ lone: false,
1023
+ },
1024
+ rows: new Map(),
1025
+ };
1026
+ // one row's choices are every row's
1027
+ if (key !== undefined) group.entry.options = [];
1028
+ found.set(list, group);
1029
+ gathered.push(group.entry);
1030
+ }
1031
+ group.entry.notes.push(...f.notes);
1032
+
1033
+ let row = group.rows.get(place);
1034
+ if (!row) {
1035
+ row = {
1036
+ // no prototype, a control's name is its key
1037
+ value: key === undefined ? undefined : Object.create(null),
1038
+ filled: false,
1039
+ };
1040
+ group.rows.set(place, row);
1041
+ }
1042
+
1043
+ const value = typed(f);
1044
+ if (key === undefined) row.value = value;
1045
+ else if (value !== undefined)
1046
+ (row.value as Record<string, unknown>)[key] = value;
1047
+ // a hidden value, such as a row's ID, is in an empty row too
1048
+ if (value !== undefined && f.type !== "hidden") row.filled = true;
1049
+
1050
+ // a column's choices, given once
1051
+ const column = `${list}.${key}`;
1052
+ if (key !== undefined && f.options.length && !found.has(column)) {
1053
+ const entry = {
1054
+ ...f,
1055
+ label: column,
1056
+ name: column,
1057
+ value: [],
1058
+ notes: [],
1059
+ lone: false,
1060
+ };
1061
+ found.set(column, { entry, rows: new Map() });
1062
+ gathered.push(entry);
1063
+ }
1064
+ }
1065
+
1066
+ for (const { entry, rows } of found.values()) {
1067
+ const items = [...rows]
1068
+ .sort(([a], [b]) => a - b)
1069
+ .flatMap(([, row]) => (row.filled ? [row.value] : []));
1070
+ if (items.length) entry.value = [JSON.stringify(items)];
1071
+ }
1072
+
1073
+ return gathered;
1074
+ }
1075
+
898
1076
  /**
899
1077
  * @param tool Tool and the arguments an address gave
900
1078
  * @returns The call, as an agent makes it
@@ -995,11 +1173,22 @@ class Writer {
995
1173
  if (!this.#controls) break;
996
1174
  const { name, value, type } = child.attrs;
997
1175
  if (child.tag === "button") out += inner();
1176
+ // a list's row, whose items its tool's form lists
1177
+ if (name && this.#arrays && Writer.#cell(name, this.#arrays)) break;
998
1178
  if (name && type !== "hidden") {
999
- // a box sends "on" without a value, others what is typed
1000
- const sent =
1001
- value ?? (type === "checkbox" || type === "radio" ? "on" : "");
1002
- out += ` ${Writer.#code(sent ? `${name}=${sent}` : name)} `;
1179
+ const box = type === "checkbox" || type === "radio";
1180
+ const checked = "checked" in child.attrs;
1181
+ // what it holds now: a box with a value names its row and
1182
+ // says if it is checked, one without is "on" when it is, and
1183
+ // a select is the option chosen
1184
+ const sent = box
1185
+ ? (value ?? (checked ? "on" : ""))
1186
+ : child.tag === "select"
1187
+ ? (Writer.#chosen(child) ?? "")
1188
+ : (value ?? "");
1189
+ out += ` ${Writer.#code(sent ? `${name}=${sent}` : name)}${
1190
+ box && value !== undefined && checked ? " (checked)" : ""
1191
+ } `;
1003
1192
  }
1004
1193
  break;
1005
1194
  }
@@ -1123,6 +1312,8 @@ class Writer {
1123
1312
  let text = "";
1124
1313
  for (const child of node.children) {
1125
1314
  if (typeof child === "string") text += child;
1315
+ // an image is read as its alternative text, such as a label's
1316
+ else if (child.tag === "img") text += ` ${child.attrs.alt ?? ""} `;
1126
1317
  else if (!omitControls || !["select", "textarea"].includes(child.tag))
1127
1318
  text += " " + Writer.#plain(child, omitControls) + " ";
1128
1319
  }
package/src/mcp/index.ts CHANGED
@@ -1,10 +1,18 @@
1
1
  import { type App, agents, direct, mount } from "../app/index.js";
2
2
  import { type Context, agent } from "../context/index.js";
3
- import { type Field, forms } from "../form/index.js";
3
+ import { type Field, forms, field as isField } from "../form/index.js";
4
4
  import type { Middleware } from "../middleware/index.js";
5
5
  import { Route, parameters, schemas } from "../route/index.js";
6
6
  import { Schema } from "../schema/index.js";
7
- import { Codec, Header, Method, Mime, Size, noStore } from "../util/index.js";
7
+ import {
8
+ Codec,
9
+ Header,
10
+ Method,
11
+ Mime,
12
+ Prose,
13
+ Size,
14
+ noStore,
15
+ } from "../util/index.js";
8
16
 
9
17
  /** JSON-RPC request id */
10
18
  type Id = string | number | null;
@@ -672,39 +680,11 @@ export class Mcp<P extends string = string> {
672
680
  Object.assign(properties, schema.properties);
673
681
  for (const field of (schema.required ?? []) as string[])
674
682
  required.add(field);
675
- // a tool's arguments are JSON, so a file is sent as its contents,
676
- // and a JSON field as the value it parses, not a string of it
677
- for (const name in shape) {
678
- const field = shape[name]!;
679
- const property = properties[name] as Json;
680
- if (field.type === "file")
681
- properties[name] =
682
- field.parts > 1
683
- ? { ...property, items: Mcp.#file }
684
- : {
685
- ...property,
686
- ...Mcp.#file,
687
- // the field's own, such as a size limit, then how to send it
688
- description: [
689
- (property.description as string | undefined)?.replace(
690
- /\.$/,
691
- "",
692
- ),
693
- Mcp.#file.description,
694
- ]
695
- .filter(Boolean)
696
- .join(". "),
697
- };
698
- else if (Mcp.#whole(field)) {
699
- const {
700
- type: _,
701
- contentMediaType: __,
702
- contentSchema,
703
- ...keywords
704
- } = properties[name] as Json;
705
- properties[name] = { ...(contentSchema as Json), ...keywords };
706
- }
707
- }
683
+ for (const name in shape)
684
+ properties[name] = Mcp.#property(
685
+ shape[name]!,
686
+ properties[name] as Json,
687
+ );
708
688
  }
709
689
 
710
690
  for (const [param, key] of Mcp.#params(route)) {
@@ -733,6 +713,56 @@ export class Mcp<P extends string = string> {
733
713
  return tools;
734
714
  }
735
715
 
716
+ /**
717
+ * A tool's arguments are JSON, so a file is sent as its contents, and a
718
+ * JSON field as the value it parses, not a string of it.
719
+ *
720
+ * @param field Form field
721
+ * @param property The field's JSON Schema
722
+ * @returns The JSON Schema of the argument an agent sends for it
723
+ */
724
+ static #property(field: Field.Any, property: Json): Json {
725
+ const { item } = field;
726
+
727
+ if (item) {
728
+ // each item of a list, as its own fields are sent
729
+ const items = property.items as Json | undefined;
730
+ if (!items) return property;
731
+ if (isField(item))
732
+ return { ...property, items: Mcp.#property(item, items) };
733
+
734
+ const cells = { ...(items.properties as Json) };
735
+ for (const key of Object.keys(item))
736
+ cells[key] = Mcp.#property(item[key]!, cells[key] as Json);
737
+ return { ...property, items: { ...items, properties: cells } };
738
+ }
739
+
740
+ if (field.type === "file")
741
+ return field.parts > 1
742
+ ? { ...property, items: Mcp.#file }
743
+ : {
744
+ ...property,
745
+ ...Mcp.#file,
746
+ // the field's own, such as a size limit, then how to send it
747
+ description: Prose.join(
748
+ property.description as string | undefined,
749
+ Mcp.#file.description,
750
+ ),
751
+ };
752
+
753
+ if (Mcp.#whole(field)) {
754
+ const {
755
+ type: _,
756
+ contentMediaType: __,
757
+ contentSchema,
758
+ ...keywords
759
+ } = property;
760
+ return { ...(contentSchema as Json), ...keywords };
761
+ }
762
+
763
+ return property;
764
+ }
765
+
736
766
  /**
737
767
  * @param route Route a tool calls
738
768
  * @returns Pattern parameters by the argument that fills them, `wildcard`
@@ -782,6 +812,19 @@ export class Mcp<P extends string = string> {
782
812
  return Boolean(def);
783
813
  }
784
814
 
815
+ /**
816
+ * @param field Form field
817
+ * @returns `true` for a field of lines, `Field.textarea().lines()`, also when made
818
+ * optional
819
+ */
820
+ static #lines(field: Field.Any) {
821
+ if (field.tag !== "textarea") return false;
822
+
823
+ let def: Schema.Def = field.def;
824
+ while ("inner" in def) def = def.inner.def;
825
+ return def.type === "array";
826
+ }
827
+
785
828
  /**
786
829
  * @param value Tool argument for a file field
787
830
  * @returns The file, `undefined` when the argument does not describe one
@@ -907,36 +950,54 @@ export class Mcp<P extends string = string> {
907
950
  true,
908
951
  );
909
952
  }
910
- for (const [name, value] of Object.entries(args)) {
911
- const field =
912
- shape && Object.hasOwn(shape, name) ? shape[name] : undefined;
913
- // a parameter is in the path, and also sent when a field has its name
914
- if (pathParams.has(name) && !field) continue;
953
+ /**
954
+ * @param field The field the argument is for, if there is one
955
+ * @param name Form data name
956
+ * @param value The argument
957
+ * @returns The name of a file field whose argument is not a file
958
+ */
959
+ const send = (
960
+ field: Field.Any | undefined,
961
+ name: string,
962
+ value: unknown,
963
+ ): string | undefined => {
964
+ const item = field?.item;
965
+ if (item) {
966
+ // each item's fields are named by its place, as a row's are
967
+ let place = 0;
968
+ for (const row of Array.isArray(value) ? value : []) {
969
+ const at = `${name}.${place++}`;
970
+ if (isField(item)) {
971
+ const failed = send(item, at, row);
972
+ if (failed) return failed;
973
+ } else if (row && typeof row === "object") {
974
+ for (const key of Object.keys(item)) {
975
+ const failed = send(
976
+ item[key],
977
+ `${at}.${key}`,
978
+ (row as Json)[key],
979
+ );
980
+ if (failed) return failed;
981
+ }
982
+ }
983
+ }
984
+ return;
985
+ }
986
+
915
987
  const upload = !read && field?.type === "file";
916
988
  // a JSON field reads one value, so an array is sent whole, as its
917
989
  // input schema describes it
918
- const whole = field && Mcp.#whole(field);
919
- if (whole && value != null) {
990
+ if (field && Mcp.#whole(field) && value != null) {
920
991
  const text = JSON.stringify(value);
921
992
  if (read) url.searchParams.append(name, text);
922
993
  else body.append(name, text);
923
- continue;
994
+ return;
924
995
  }
925
996
  for (const item of Array.isArray(value) ? value : [value]) {
926
997
  if (item == null || item === false) continue;
927
998
  if (upload) {
928
999
  const file = Mcp.#upload(item);
929
- if (!file)
930
- return Mcp.#result(
931
- Mcp.#issues([
932
- {
933
- path: name,
934
- message:
935
- "Expected a file: its name, and its contents as text or base64",
936
- },
937
- ]),
938
- true,
939
- );
1000
+ if (!file) return name;
940
1001
  body.append(name, file);
941
1002
  continue;
942
1003
  }
@@ -949,6 +1010,26 @@ export class Mcp<P extends string = string> {
949
1010
  if (read) url.searchParams.append(name, text);
950
1011
  else body.append(name, text);
951
1012
  }
1013
+ };
1014
+
1015
+ for (const [name, value] of Object.entries(args)) {
1016
+ const field =
1017
+ shape && Object.hasOwn(shape, name) ? shape[name] : undefined;
1018
+ // a parameter is in the path, and also sent when a field has its name
1019
+ if (pathParams.has(name) && !field) continue;
1020
+
1021
+ const path = send(field, name, value);
1022
+ if (path)
1023
+ return Mcp.#result(
1024
+ Mcp.#issues([
1025
+ {
1026
+ path,
1027
+ message:
1028
+ "Expected a file: its name, and its contents as text or base64",
1029
+ },
1030
+ ]),
1031
+ true,
1032
+ );
952
1033
  }
953
1034
 
954
1035
  return this.#fetch(
@@ -956,6 +1037,10 @@ export class Mcp<P extends string = string> {
956
1037
  session,
957
1038
  url,
958
1039
  read ? undefined : { method: route.method, body },
1040
+ // the form's fields among the arguments, which are all a write updates
1041
+ new Set(
1042
+ Object.keys(args).filter((name) => shape && Object.hasOwn(shape, name)),
1043
+ ),
959
1044
  );
960
1045
  }
961
1046
 
@@ -1058,7 +1143,8 @@ export class Mcp<P extends string = string> {
1058
1143
  /**
1059
1144
  * @param c Request context
1060
1145
  * @returns The name of the tool a form submits to, so the page an agent
1061
- * reads points to the tool instead of repeating its fields
1146
+ * reads points to the tool instead of repeating its fields, and the fields
1147
+ * whose choices only the page lists
1062
1148
  */
1063
1149
  #tool(c: Context) {
1064
1150
  return (method: string, action: URL) => {
@@ -1071,7 +1157,33 @@ export class Mcp<P extends string = string> {
1071
1157
  for (const param in match.params)
1072
1158
  args[param === "*" ? "wildcard" : param] = match.params[param]!;
1073
1159
 
1074
- return { name, args };
1160
+ // choices from a schema, given as the form renders, and the fields
1161
+ // an agent sends as an array, which the page shows as rows or lines
1162
+ const choices = new Set<string>();
1163
+ const lists = new Set<string>();
1164
+ const shape = forms.get(match.route)?.shape;
1165
+ const rendered = (field: Field.Any) => field.options?.length === 0;
1166
+
1167
+ for (const name in shape) {
1168
+ const field = shape[name]!;
1169
+ const { item } = field;
1170
+
1171
+ if (!item) {
1172
+ if (rendered(field)) choices.add(name);
1173
+ if (Mcp.#lines(field)) lists.add(name);
1174
+ continue;
1175
+ }
1176
+
1177
+ lists.add(name);
1178
+ if (isField(item)) {
1179
+ if (rendered(item)) choices.add(name);
1180
+ } else {
1181
+ for (const key of Object.keys(item))
1182
+ if (rendered(item[key]!)) choices.add(`${name}.${key}`);
1183
+ }
1184
+ }
1185
+
1186
+ return { name, args, choices, lists };
1075
1187
  };
1076
1188
  }
1077
1189
 
@@ -1147,7 +1259,13 @@ export class Mcp<P extends string = string> {
1147
1259
  * @param init Method and body
1148
1260
  * @returns The response, or the form's issues instead of the redirect back to it
1149
1261
  */
1150
- async #run(c: Context, session: unknown, url: URL, init?: RequestInit) {
1262
+ async #run(
1263
+ c: Context,
1264
+ session: unknown,
1265
+ url: URL,
1266
+ init?: RequestInit,
1267
+ sent?: ReadonlySet<string>,
1268
+ ) {
1151
1269
  const language = this.#languages.get(c.req);
1152
1270
  const req = new Request(url, {
1153
1271
  ...init,
@@ -1162,6 +1280,7 @@ export class Mcp<P extends string = string> {
1162
1280
  const call: Parameters<typeof agent.set>[1] = {
1163
1281
  session,
1164
1282
  tool: this.#tool(c),
1283
+ ...(sent && { sent }),
1165
1284
  };
1166
1285
  agent.set(req, call);
1167
1286
  const res = await this.#app!.fetch(req, { ip: c.ip });
@@ -1175,7 +1294,8 @@ export class Mcp<P extends string = string> {
1175
1294
  }
1176
1295
 
1177
1296
  /**
1178
- * Calls the app as the agent, following redirects to pages it can read.
1297
+ * Calls the app as the agent. A read follows redirects to pages it can
1298
+ * read, and a write that redirects is answered with where.
1179
1299
  *
1180
1300
  * @param c Request context
1181
1301
  * @param session Session the token authorizes
@@ -1183,7 +1303,13 @@ export class Mcp<P extends string = string> {
1183
1303
  * @param init Method and body
1184
1304
  * @returns Tool result
1185
1305
  */
1186
- async #fetch(c: Context, session: unknown, url: URL, init?: RequestInit) {
1306
+ async #fetch(
1307
+ c: Context,
1308
+ session: unknown,
1309
+ url: URL,
1310
+ init?: RequestInit,
1311
+ sent?: ReadonlySet<string>,
1312
+ ) {
1187
1313
  let redirected: URL | undefined;
1188
1314
  /** The call writes, so a redirect from it means it was done */
1189
1315
  const wrote = init !== undefined;
@@ -1192,7 +1318,7 @@ export class Mcp<P extends string = string> {
1192
1318
  `Redirected to ${page.pathname}${page.search}`;
1193
1319
 
1194
1320
  for (let i = 0; ; i++) {
1195
- const res = await this.#run(c, session, url, init);
1321
+ const res = await this.#run(c, session, url, init, sent);
1196
1322
  if (typeof res === "string") return Mcp.#result(res, true);
1197
1323
 
1198
1324
  const location = res.headers.get(Header.name.loc);
@@ -1202,9 +1328,11 @@ export class Mcp<P extends string = string> {
1202
1328
  const next = new URL(location, url);
1203
1329
  const readable = this.#readable(c, next);
1204
1330
 
1205
- if (readable && i < Mcp.#redirects) {
1331
+ // a read follows it, as a browser does. A write that redirects is
1332
+ // done, and the agent is told where: the page it goes to, such as a
1333
+ // whole list after deleting one item, is its to read if it wants
1334
+ if (readable && i < Mcp.#redirects && !wrote) {
1206
1335
  url = redirected = next;
1207
- init = undefined;
1208
1336
  continue;
1209
1337
  }
1210
1338
 
@@ -1220,16 +1348,6 @@ export class Mcp<P extends string = string> {
1220
1348
  );
1221
1349
  }
1222
1350
 
1223
- // the route answered a write by redirecting, so the write is done. A
1224
- // page it sends to that then fails, such as on a rate limit, must not
1225
- // read as the write failing, or an agent would make it again
1226
- if (redirected && wrote && !res.ok) {
1227
- await res.body?.cancel();
1228
- return Mcp.#result(
1229
- `${redirect(redirected)}, which could not be read: ${Mcp.#status(res)}`,
1230
- );
1231
- }
1232
-
1233
1351
  if (res.status >= 500) throw await Mcp.#failed(res);
1234
1352
 
1235
1353
  const { type, text, blob, live } = await Mcp.#body(res);
@@ -1250,6 +1368,21 @@ export class Mcp<P extends string = string> {
1250
1368
  );
1251
1369
 
1252
1370
  const [kind] = type?.split("/") ?? [];
1371
+ // a page the route sends as a file to download, such as one to
1372
+ // print: the agent gets the file, not its text to read
1373
+ const disposition = res.headers.get("content-disposition") ?? "";
1374
+ if (text !== undefined && res.ok && /^\s*attachment/i.test(disposition))
1375
+ return Mcp.#result(
1376
+ // the file's name, without what could read as more than a name
1377
+ (/filename="?([^";]+)"?/i.exec(disposition)?.[1] ?? "")
1378
+ .replace(/[^\w .-]+/g, "_")
1379
+ .slice(0, 100),
1380
+ false,
1381
+ {
1382
+ type: "resource",
1383
+ resource: { uri: this.#name(url), mimeType: type, text },
1384
+ },
1385
+ );
1253
1386
 
1254
1387
  return Mcp.#result(
1255
1388
  [redirected && redirect(redirected), !res.ok && Mcp.#status(res), text]