@datalayer/agent-runtimes 1.5.96 → 1.5.98

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 (92) hide show
  1. package/dist-embed/chunks/{index.esm-zOy6kFPv.js → index.esm-BLDeC6q1.js} +1 -1
  2. package/dist-embed/datalayer-app-main.js +80 -80
  3. package/lib/apps/apps/appspec.d.ts +11 -12
  4. package/lib/apps/apps/appspec.js +45 -87
  5. package/lib/components/cards/ToolApprovalCard.js +4 -2
  6. package/lib/components/teams/HarnessIcon.d.ts +11 -0
  7. package/lib/components/teams/HarnessIcon.js +17 -0
  8. package/lib/components/teams/SceneTranscript.d.ts +1 -1
  9. package/lib/components/teams/SceneTranscript.js +12 -7
  10. package/lib/components/teams/SceneView.d.ts +7 -1
  11. package/lib/components/teams/SceneView.js +2 -2
  12. package/lib/components/teams/backdrops/hero.js +1 -1
  13. package/lib/components/teams/backdrops/minimal.js +1 -1
  14. package/lib/components/teams/backdrops/nodes.js +4 -3
  15. package/lib/components/teams/backdrops/space.js +1 -1
  16. package/lib/components/teams/backdrops/types.d.ts +9 -0
  17. package/lib/components/teams/index.d.ts +2 -0
  18. package/lib/components/teams/index.js +2 -0
  19. package/lib/components/teams/memberHarness.d.ts +16 -0
  20. package/lib/components/teams/memberHarness.js +42 -0
  21. package/lib/components/teams/sceneTranscriptRules.js +6 -1
  22. package/lib/components/teams/transcript/LineSelect.d.ts +20 -0
  23. package/lib/components/teams/transcript/LineSelect.js +20 -0
  24. package/lib/components/teams/transcript/TranscriptTable.d.ts +11 -5
  25. package/lib/components/teams/transcript/TranscriptTable.js +24 -7
  26. package/lib/components/teams/transcript/TranscriptViews.js +1 -1
  27. package/lib/components/teams/transcript/recordingPlayback.d.ts +13 -0
  28. package/lib/components/teams/transcript/recordingPlayback.js +32 -0
  29. package/lib/components/teams/transcript/useSceneRecording.d.ts +1 -1
  30. package/lib/components/teams/transcript/useSceneRecording.js +19 -11
  31. package/lib/examples/PapAccountTokensExample.d.ts +1 -1
  32. package/lib/examples/PapAccountTokensExample.js +3 -3
  33. package/lib/examples/PapSessionJwtExample.d.ts +4 -0
  34. package/lib/examples/{PapDpopProofExample.js → PapSessionJwtExample.js} +9 -9
  35. package/lib/examples/PapSessionLifecycleExample.d.ts +1 -1
  36. package/lib/examples/PapSessionLifecycleExample.js +2 -2
  37. package/lib/examples/ScenesExample.js +15 -13
  38. package/lib/examples/example-selector.js +3 -3
  39. package/lib/examples/index.d.ts +1 -1
  40. package/lib/examples/index.js +1 -1
  41. package/lib/examples/main.js +1 -1
  42. package/lib/examples/pap/PapAccountTokensView.d.ts +1 -1
  43. package/lib/examples/pap/PapAuthorizationBoundaryView.js +15 -22
  44. package/lib/examples/pap/PapGuidedJourneyView.js +61 -60
  45. package/lib/examples/pap/PapSessionJwtView.d.ts +4 -0
  46. package/lib/examples/pap/PapSessionJwtView.js +69 -0
  47. package/lib/examples/pap/PapSessionLifecycleView.js +36 -58
  48. package/lib/examples/pap/PapSignInDisplayView.d.ts +1 -1
  49. package/lib/examples/pap/PapSignInDisplayView.js +1 -1
  50. package/lib/examples/pap/PapTraceView.d.ts +1 -1
  51. package/lib/examples/pap/PapTraceView.js +1 -1
  52. package/lib/examples/pap/traces/account-tokens.json +145 -173
  53. package/lib/examples/pap/traces/conversation-control.json +118 -140
  54. package/lib/examples/pap/traces/conversation-streaming.json +114 -134
  55. package/lib/examples/pap/traces/mediated-sign-in.json +151 -166
  56. package/lib/examples/pap/traces/operations.json +613 -391
  57. package/lib/examples/pap/traces/two-companies.json +380 -990
  58. package/lib/examples/pap/traces/user-with-a-company.json +319 -207
  59. package/lib/models/environments.generated.d.ts +2 -2
  60. package/lib/models/environments.generated.js +1 -1
  61. package/lib/pap/index.d.ts +1 -1
  62. package/lib/pap/index.js +3 -3
  63. package/lib/portable/displays.d.ts +13 -22
  64. package/lib/portable/displays.js +17 -65
  65. package/lib/portable/hosts/approvalRenderers.d.ts +4 -4
  66. package/lib/portable/hosts/approvalRenderers.js +26 -13
  67. package/lib/portable/hosts/contracts.json +5 -2
  68. package/lib/portable/index.d.ts +1 -1
  69. package/lib/portable/index.js +1 -1
  70. package/lib/protocols/decks/index.d.ts +37 -0
  71. package/lib/protocols/decks/index.js +48 -0
  72. package/lib/protocols/decks/pact-a-personal-agent-at-a-business.d.ts +2 -0
  73. package/lib/protocols/decks/pact-a-personal-agent-at-a-business.js +148 -0
  74. package/lib/protocols/decks/ucp-a-purchase-approved.d.ts +2 -0
  75. package/lib/protocols/decks/ucp-a-purchase-approved.js +154 -0
  76. package/lib/specs/actions.d.ts +1 -1
  77. package/lib/specs/actions.js +2 -2
  78. package/lib/specs/agents/agents.js +3 -3
  79. package/lib/specs/apps.d.ts +1 -1
  80. package/lib/specs/apps.js +10 -11
  81. package/lib/specs/appspecSchema.js +4 -112
  82. package/lib/specs/envvars.js +2 -2
  83. package/lib/specs/harnesses.js +9 -9
  84. package/lib/specs/scenes.js +10 -33
  85. package/lib/specs/teams/teams.js +2 -2
  86. package/lib/types/agentspecs.d.ts +91 -127
  87. package/package.json +409 -409
  88. package/scripts/codegen/generate_apps.py +6 -7
  89. package/scripts/validate_pap_examples.py +1 -1
  90. package/lib/examples/PapDpopProofExample.d.ts +0 -4
  91. package/lib/examples/pap/PapDpopProofView.d.ts +0 -4
  92. package/lib/examples/pap/PapDpopProofView.js +0 -61
@@ -75,9 +75,9 @@ export interface AgentCapability {
75
75
  tags?: string[];
76
76
  }
77
77
  /**
78
- * A visual component a UI plugin renders (C-13), named as a surface names
78
+ * A visual component a UI plugin renders, named as a surface names
79
79
  * it. A standard one's properties are its protocol's own; Datalayer's own
80
- * carry theirs as a JSON Schema, from which its properties form is drawn (C-14).
80
+ * carry theirs as a JSON Schema, from which its properties form is drawn.
81
81
  */
82
82
  export interface ComponentSpec {
83
83
  /** The name a surface gives it (e.g. 'Table'). */
@@ -93,7 +93,7 @@ export interface ComponentSpec {
93
93
  version: string;
94
94
  /** Named and drawn as its protocol says (A2UI's basic catalog). */
95
95
  standard: boolean;
96
- /** Its properties as a JSON Schema: what a builder sets (C-13). */
96
+ /** Its properties as a JSON Schema: what a builder sets. */
97
97
  properties: Record<string, unknown>;
98
98
  /** What it can be bound to: what it shows, what it sends. */
99
99
  bindings?: {
@@ -146,7 +146,7 @@ export interface UISpec {
146
146
  renderers: string[];
147
147
  /** The catalog its components are written in. */
148
148
  catalog: string;
149
- /** The visual components it renders (C-13). */
149
+ /** The visual components it renders. */
150
150
  components: ComponentSpec[];
151
151
  }
152
152
  /**
@@ -174,8 +174,8 @@ export interface UiChoice {
174
174
  /** The layer of an agent's visit a protocol answers. */
175
175
  export type ProtocolLayer = 'transport' | 'consent' | 'identity' | 'commerce' | 'ui';
176
176
  /**
177
- * An agent protocol Datalayer targets (`agentspecs/protocols`,
178
- * PS-01). An agent spec's or an application's `protocols` names the ones it speaks.
177
+ * An agent protocol Datalayer targets (`agentspecs/protocols`).
178
+ * An agent spec's or an application's `protocols` names the ones it speaks.
179
179
  */
180
180
  export interface ProtocolSpec {
181
181
  /** What `protocols` lists (e.g. 'pap'). */
@@ -224,12 +224,12 @@ export interface HarnessAcpSpec {
224
224
  }
225
225
  /**
226
226
  * An agent program driven over the Agent Client Protocol
227
- * (`agentspecs/harnesses`, SH-01). An agent spec's `harness:` names
227
+ * (`agentspecs/harnesses`). An agent spec's `harness:` names
228
228
  * one beside `pydantic-ai` and `vercel-ai`; the Datalayer runtime serves it
229
- * through its ACP adapter, `ACPAgent` (SH-10), never the browser.
229
+ * through its ACP adapter, `ACPAgent`, never the browser.
230
230
  */
231
231
  /**
232
- * A Shield policy document the platform ships or shows (`agentspecs/policies`, SH-50):
232
+ * A Shield policy document the platform ships or shows (`agentspecs/policies`):
233
233
  * the catalogue's fields around a document of
234
234
  * `@datalayer/agent-shield`'s `Policy`, whose schema agentspecs carries verbatim.
235
235
  */
@@ -334,7 +334,7 @@ export interface StandardControl {
334
334
  coverage_note?: string;
335
335
  }
336
336
  /**
337
- * A standard a conformance report answers (`agentspecs/standards`, SH-60):
337
+ * A standard a conformance report answers (`agentspecs/standards`):
338
338
  * its version, domains and controls, carried whole.
339
339
  */
340
340
  export interface StandardSpec {
@@ -363,7 +363,7 @@ export interface StandardSpec {
363
363
  controls: StandardControl[];
364
364
  }
365
365
  /**
366
- * A harness of the register's *listed* tier (SH-57): known to speak ACP,
366
+ * A harness of the register's *listed* tier: known to speak ACP,
367
367
  * its documented command, licence, terms and credential read and cited; not
368
368
  * drilled, so offered by nothing — naming one is refused *listed, not drilled yet*.
369
369
  */
@@ -438,7 +438,7 @@ export interface HarnessSpec {
438
438
  subagents: boolean;
439
439
  };
440
440
  /**
441
- * What a session may rely on of it (MH-20): read by swap, clone and
441
+ * What a session may rely on of it: read by swap, clone and
442
442
  * resume instead of branching on the harness's id.
443
443
  */
444
444
  capabilities: HarnessCapabilitiesSpec;
@@ -702,7 +702,7 @@ export interface ServerActionsSpec {
702
702
  tools: Record<string, ActionClass[]>;
703
703
  /** What an argument makes a tool do besides, by tool. */
704
704
  conditions: Record<string, ActionConditionSpec[]>;
705
- /** The argument carrying what a tool sends, signed with the application's byline (I-10), by tool. */
705
+ /** The argument carrying what a tool sends, signed with the application's byline, by tool. */
706
706
  signs?: Record<string, string>;
707
707
  }
708
708
  /** What kind of application it is: what its user meets. */
@@ -718,12 +718,12 @@ export type AppBehaviour = 'do_it' | 'if_asked' | 'ask_first' | 'leave_to_me';
718
718
  export type AppLayout = 'chat' | 'page' | 'split';
719
719
  /** The one colour of an application; everything else is neutral. */
720
720
  export type AppAccent = 'green' | 'rose' | 'sky' | 'lime' | 'sun' | 'violet';
721
- /** A theme of Appearance's, which an application may run in (T-30). */
721
+ /** A theme of Appearance's, which an application may run in. */
722
722
  export type AppThemeVariant = 'datalayer' | 'spatial' | 'lovely' | 'matrix' | 'earth' | 'sand' | 'ivory' | 'sun' | 'loop' | 'vscode';
723
723
  /** The colour mode it is worn in: `auto` follows the device. */
724
724
  export type AppThemeMode = 'light' | 'dark' | 'auto';
725
725
  /**
726
- * The theme an application runs in by default (T-30): at its address,
726
+ * The theme an application runs in by default: at its address,
727
727
  * embedded, in the Studio's Preview and as an example. The person's own
728
728
  * when unsaid; the mode, when unsaid, is the person's.
729
729
  */
@@ -732,7 +732,7 @@ export interface AppThemeSpec {
732
732
  mode?: AppThemeMode;
733
733
  }
734
734
  /**
735
- * An avatar named by id (T-24): the id an enabled plugin contributes it
735
+ * An avatar named by id: the id an enabled plugin contributes it
736
736
  * under to `loop.assistant.character` — Datalayer's orb is `orb`, in the
737
737
  * theme's colours, acting out each of the assistant's states; its own drawings are
738
738
  * `paperclip`, `wizard`, `cat` and `eyes`; the characters clippy.js
@@ -756,9 +756,9 @@ export interface AppAvatarModel3D {
756
756
  * id (a drawing, or a Microsoft Agent character), or a 3D model.
757
757
  */
758
758
  export type AppAvatar = AppAvatarId | AppAvatarModel3D;
759
- /** How a floating assistant's balloon shows the conversation (T-23). */
759
+ /** How a floating assistant's balloon shows the conversation. */
760
760
  export type AppBalloonDisplay = 'history' | 'current';
761
- /** How an application sits in another product's page (D-07). */
761
+ /** How an application sits in another product's page. */
762
762
  export type AppEmbedMode = 'inline' | 'bubble' | 'panel' | 'assistant';
763
763
  /** Something an application reaches. */
764
764
  export interface AppConnectionSpec {
@@ -816,8 +816,7 @@ export interface AppPapExcludedTaskSpec {
816
816
  alternative?: AppPapAlternativeSpec;
817
817
  }
818
818
  /**
819
- * A company the application works with as a personal agent
820
- * (S-01): named by its domain, nothing else; what discovery
819
+ * A company the application works with as a personal agent: named by its domain, nothing else; what discovery
821
820
  * verifies is the deployment's, never the spec's.
822
821
  */
823
822
  export interface AppPapConnectionSpec {
@@ -835,7 +834,7 @@ export interface AppPapConnectionSpec {
835
834
  signIn: PapSignIn[];
836
835
  extensions: string[];
837
836
  }
838
- /** The application as a company personal agents work with (U-04). */
837
+ /** The application as a company personal agents work with. */
839
838
  export interface AppPapCompanySpec {
840
839
  /** Whether it publishes itself as a company at Ship. */
841
840
  enabled: boolean;
@@ -852,60 +851,26 @@ export interface AppPapCompanySpec {
852
851
  /** The personal agents it accepts when `registered` only, by `client_id` URL. */
853
852
  registeredAgents: string[];
854
853
  /**
855
- * What it does for the person once they confirm (B-04, the
854
+ * What it does for the person once they confirm (the
856
855
  * `operations` extension): each action and each tool once.
857
856
  */
858
857
  operations: AppPapOperationSpec[];
859
858
  }
860
- /**
861
- * One bound of a standing permission (R-07): a term of the other
862
- * company's operations, by its dotted path, bounded by a term of this one —
863
- * its maximum, or the one value allowed (one of the two).
864
- */
865
- export interface AppPapStandingLimitSpec {
866
- path: string;
867
- maximum?: string;
868
- allowed?: string;
869
- }
870
- /**
871
- * What an operation gives instead of calling a tool (R-07, the
872
- * Ledgerly pattern): once the person confirms it, the application may confirm,
873
- * at one of its own company connections and in their account there, what stays
874
- * within these bounds — recorded as the approval in advance they would give in
875
- * Datalayer.
876
- */
877
- export interface AppPapStandingSpec {
878
- /** The id of one of its own company connections (`as: user`, `write`). */
879
- connection: string;
880
- /** What confirming there does. */
881
- action: 'write' | 'buy';
882
- /** Every term bounded, 1 to 20. */
883
- limits: AppPapStandingLimitSpec[];
884
- /** The term of this operation giving how many times, at most. */
885
- uses: string;
886
- /** The term of this operation giving for how many days, at most 90. */
887
- days: string;
888
- }
889
859
  /**
890
860
  * Something a personal agent may ask the application to do for the person,
891
- * done only once they confirm its exact terms (B-04): the call
892
- * of `tool` is proposed instead of made, its arguments the terms — or, for one
893
- * that `allows`, a standing permission given (R-07).
861
+ * done only once they approve its exact terms: the call of `tool` is proposed
862
+ * instead of made, its arguments the terms.
894
863
  */
895
864
  export interface AppPapOperationSpec {
896
865
  /** The action's name at this company: `orders.exchange`. */
897
866
  action: string;
898
- /** The application's tool that does it, called with the terms; `''` for one that `allows`. */
867
+ /** The application's tool that does it, called with the terms. */
899
868
  tool: string;
900
- /** Instead of a tool: the standing permission confirming it gives (R-07). */
901
- allows?: AppPapStandingSpec;
902
869
  /** What the person is shown, `{term}` for each term; never the model's. */
903
870
  summary: string;
904
- /** Whether only the person may confirm it, never an approval in advance. */
905
- userApprovalRequired: boolean;
906
871
  }
907
872
  /**
908
- * A Personal Agent Protocol profile Datalayer speaks (S-03): `draft-01` names
873
+ * A Personal Agent Protocol profile Datalayer speaks: `draft-01` names
909
874
  * the profile the Appspec has said since the first draft; the SDK it is read
910
875
  * with implements draft 0.3.
911
876
  */
@@ -918,8 +883,7 @@ export interface AppPapSpec {
918
883
  company: AppPapCompanySpec;
919
884
  }
920
885
  /**
921
- * A business the application asks for each person over PACT 1.0
922
- * (PI-01): its domain, and the audience its Provider
886
+ * A business the application asks for each person over PACT 1.0: its domain, and the audience its Provider
923
887
  * assigned. Always in each person's own name; never a credential.
924
888
  */
925
889
  export interface AppPactConnectionSpec {
@@ -942,7 +906,7 @@ export interface AppPactRegisteredAgentSpec {
942
906
  jwksUri: string;
943
907
  }
944
908
  /**
945
- * The application as a PACT business (PR-13, PI-32): its card
909
+ * The application as a PACT business: its card
946
910
  * names Datalayer as the Provider and its owner as the Brand; it accepts the
947
911
  * personal agents its Maker registered, and a person delegates the scopes it
948
912
  * offers through their Datalayer sign-in.
@@ -959,10 +923,10 @@ export interface AppPactBusinessSpec {
959
923
  /** PACT: the businesses it asks for each person, and whether it answers as one. */
960
924
  export interface AppPactSpec {
961
925
  connections: AppPactConnectionSpec[];
962
- /** As a business (PR-13): absent or not `enabled`, it is none. Read, it is always said. */
926
+ /** As a business: absent or not `enabled`, it is none. Read, it is always said. */
963
927
  business?: AppPactBusinessSpec;
964
928
  }
965
- /** The most one purchase may cost at a merchant (PI-22). */
929
+ /** The most one purchase may cost at a merchant. */
966
930
  export interface AppSpendLimitSpec {
967
931
  /** As written: `50`, `12.50`. */
968
932
  amount: string;
@@ -971,7 +935,7 @@ export interface AppSpendLimitSpec {
971
935
  }
972
936
  /**
973
937
  * A merchant the application shops at for each person, over UCP or ACP
974
- * (PI-01). Test merchants only, every purchase asked of the
938
+ *. Test merchants only, every purchase asked of the
975
939
  * person (decided 2026-10-13). Never a credential.
976
940
  */
977
941
  export interface AppCommerceMerchantSpec {
@@ -991,7 +955,7 @@ export interface AppCommerceSpec {
991
955
  }
992
956
  /**
993
957
  * A website the application reads pages of, each request signed with its
994
- * own Web Bot Auth key (EX-11, decided 2026-10-13): the
958
+ * own Web Bot Auth key (decided 2026-10-13): the
995
959
  * gateway's `signed-fetch` toolset reads there with GET only. Never a
996
960
  * credential.
997
961
  */
@@ -1007,7 +971,7 @@ export interface AppSignedFetchSpec {
1007
971
  }
1008
972
  /**
1009
973
  * One of a pair of examples, a PACT business and the personal agent that
1010
- * asks it (PR-13; decided 2026-10-13): when a person has
974
+ * asks it (decided 2026-10-13): when a person has
1011
975
  * copied both, the Studio registers the personal agent's copy with the
1012
976
  * business's copy and points the personal agent there.
1013
977
  */
@@ -1019,7 +983,7 @@ export interface AppPairSpec {
1019
983
  }
1020
984
  /**
1021
985
  * An A2A extension the application's Agent Card advertises, beside the
1022
- * runtime's own (PR-02). Its params are public: never a
986
+ * runtime's own. Its params are public: never a
1023
987
  * credential.
1024
988
  */
1025
989
  export interface AppA2AExtensionSpec {
@@ -1071,13 +1035,13 @@ export interface AppStarterSpec {
1071
1035
  label: string;
1072
1036
  message: string;
1073
1037
  /**
1074
- * The heading it is offered under (P-20): the starters of one
1038
+ * The heading it is offered under: the starters of one
1075
1039
  * category together, those without one first. Absent when unsaid.
1076
1040
  */
1077
1041
  category?: string;
1078
1042
  }
1079
1043
  /**
1080
- * One of several assistants in one application (P-20): picked before
1044
+ * One of several assistants in one application: picked before
1081
1045
  * the conversation starts — the first unless another is — and kept to its
1082
1046
  * end. Its instructions are told in every run, its model run in place of the
1083
1047
  * application's (a mode's wins over it), its starters offered in place of
@@ -1092,7 +1056,7 @@ export interface AppProfileSpec {
1092
1056
  starters: AppStarterSpec[];
1093
1057
  }
1094
1058
  /**
1095
- * What a person reads of an application in another language (P-26):
1059
+ * What a person reads of an application in another language:
1096
1060
  * each part keyed by what names it in the spec — a starter by its label, a
1097
1061
  * category by its words, a setting by its field, a command by its name, a
1098
1062
  * mode and a profile by their ids. Every key present; empty is untranslated.
@@ -1124,7 +1088,7 @@ export interface AppTranslationSpec {
1124
1088
  description: string;
1125
1089
  }>;
1126
1090
  }
1127
- /** A slash command the user picks in the composer (P-19). */
1091
+ /** A slash command the user picks in the composer. */
1128
1092
  export interface AppCommandSpec {
1129
1093
  /** What follows the slash: lower-case letters, digits and hyphens. */
1130
1094
  name: string;
@@ -1134,7 +1098,7 @@ export interface AppCommandSpec {
1134
1098
  prompt: string;
1135
1099
  }
1136
1100
  /**
1137
- * An action of its code a person presses (RU-5): `@app.action`,
1101
+ * An action of its code a person presses: `@app.action`,
1138
1102
  * typed — the JSON Schema of its payload, written from the pydantic model its
1139
1103
  * code declares; none when it takes nothing. The runtime offers it with a
1140
1104
  * token and refuses a press of anything else, or with anything else.
@@ -1146,7 +1110,7 @@ export interface AppActionSpec {
1146
1110
  /** The JSON Schema of its payload, an object; none when it takes nothing. */
1147
1111
  payload?: Record<string, unknown>;
1148
1112
  }
1149
- /** One position of a mode switch (P-19). */
1113
+ /** One position of a mode switch. */
1150
1114
  export interface AppModeOptionSpec {
1151
1115
  id: string;
1152
1116
  label: string;
@@ -1156,7 +1120,7 @@ export interface AppModeOptionSpec {
1156
1120
  /** The model a run in this mode runs on, in place of the application's. */
1157
1121
  model?: string | null;
1158
1122
  }
1159
- /** A mode switch in the composer (P-19). */
1123
+ /** A mode switch in the composer. */
1160
1124
  export interface AppModeSpec {
1161
1125
  id: string;
1162
1126
  label: string;
@@ -1166,7 +1130,7 @@ export interface AppModeSpec {
1166
1130
  default?: string | null;
1167
1131
  }
1168
1132
  /**
1169
- * What a run in the modes chosen is told, and the model it runs on (P-19): agentspecs' `ModeEffect`.
1133
+ * What a run in the modes chosen is told, and the model it runs on: agentspecs' `ModeEffect`.
1170
1134
  */
1171
1135
  export interface AppModeEffect {
1172
1136
  /** The instructions of the options chosen, in the order of the modes. */
@@ -1175,7 +1139,7 @@ export interface AppModeEffect {
1175
1139
  model?: string;
1176
1140
  }
1177
1141
  /**
1178
- * One field of a form (C-16): its JSON Schema — a `type`, the `title` a
1142
+ * One field of a form: its JSON Schema — a `type`, the `title` a
1179
1143
  * person reads, its `default`, and what it takes (`enum`, `minimum`,
1180
1144
  * `maximum`…).
1181
1145
  */
@@ -1190,7 +1154,7 @@ export type AppFormField = {
1190
1154
  [keyword: string]: unknown;
1191
1155
  };
1192
1156
  /**
1193
- * The JSON Schema of a form (C-16): an object of named fields, drawn with
1157
+ * The JSON Schema of a form: an object of named fields, drawn with
1194
1158
  * `@datalayer/primer-rjsf` and checked by the runtime against the same schema.
1195
1159
  * An application's settings are one (`interface.settings`), as a Form block's
1196
1160
  * schema is.
@@ -1212,10 +1176,10 @@ export interface AppSurfaceSpec {
1212
1176
  composedBy: string;
1213
1177
  composedAt: string;
1214
1178
  }
1215
- /** What a page's output is drawn with of the catalog (P-05). */
1179
+ /** What a page's output is drawn with of the catalog. */
1216
1180
  export type AppPageOutputComponent = 'Text' | 'Image' | 'Table' | 'Chart';
1217
1181
  /**
1218
- * A component its developer wrote (P-17), of one application only: the
1182
+ * A component its developer wrote, of one application only: the
1219
1183
  * catalog grows for it, it does not open. Reviewed as the catalog's own — its
1220
1184
  * properties a JSON Schema, what it shows and sends bindings — and drawn in a
1221
1185
  * sandboxed frame of no origin from the built ES module at `source`.
@@ -1240,7 +1204,7 @@ export interface AppCustomComponentSpec {
1240
1204
  /** A configuration its schema accepts: what the palette previews. */
1241
1205
  example?: Record<string, unknown>;
1242
1206
  }
1243
- /** One thing a widget's page shows for its inputs (P-05), at `/outputs/<name>`. */
1207
+ /** One thing a widget's page shows for its inputs, at `/outputs/<name>`. */
1244
1208
  export interface AppPageOutputSpec {
1245
1209
  name: string;
1246
1210
  /** What a person reads above it; none when empty. */
@@ -1248,14 +1212,14 @@ export interface AppPageOutputSpec {
1248
1212
  /**
1249
1213
  * `Text` (words) unless said, `Image` (an address), `Table` (rows), `Chart`
1250
1214
  * (points) — an `AppPageOutputComponent` — or a component of the
1251
- * application's own (P-17), its value what it shows first.
1215
+ * application's own, its value what it shows first.
1252
1216
  */
1253
1217
  component: string;
1254
1218
  /** The component's other properties: a Table's `columns`, a Chart's `kind`, `x`, `y`. */
1255
1219
  props: Record<string, unknown>;
1256
1220
  }
1257
1221
  /**
1258
- * A widget's page written in its code (P-05, `@app.page`): its inputs a
1222
+ * A widget's page written in its code (`@app.page`): its inputs a
1259
1223
  * form, drawn at `/inputs/<name>`; its outputs values, shown at
1260
1224
  * `/outputs/<name>`. As an input changes, the function its code names runs
1261
1225
  * again on all of them, and the outputs change in place.
@@ -1271,14 +1235,14 @@ export interface AppPageSpec {
1271
1235
  live: boolean;
1272
1236
  }
1273
1237
  /**
1274
- * An application's voice (VO-41), off unless said: whether a person
1238
+ * An application's voice, off unless said: whether a person
1275
1239
  * may talk to it, whether its answers are heard, with which voice of the
1276
1240
  * catalogue (`specs/voices`), in which language (BCP 47) and where its
1277
1241
  * speech runs.
1278
1242
  */
1279
1243
  export interface AppVoiceSpec {
1280
1244
  enabled: boolean;
1281
- /** `hands_free` (VO-12) is refused until it is built. */
1245
+ /** `hands_free` is refused until it is built. */
1282
1246
  input: 'off' | 'push_to_talk' | 'hands_free';
1283
1247
  output: 'off' | 'on_request' | 'always';
1284
1248
  voice: string;
@@ -1286,7 +1250,7 @@ export interface AppVoiceSpec {
1286
1250
  where: 'auto' | 'device' | 'server';
1287
1251
  }
1288
1252
  /**
1289
- * A kind of file a person may send, and how large (P-21): a media type
1253
+ * A kind of file a person may send, and how large: a media type
1290
1254
  * (`application/pdf`), a family (`image/*`, `audio/*`) or an extension
1291
1255
  * (`.csv`), lowercase.
1292
1256
  */
@@ -1296,7 +1260,7 @@ export interface AppUploadKindSpec {
1296
1260
  maxMb: number;
1297
1261
  }
1298
1262
  /**
1299
- * What a person may send in the composer without being asked (P-21):
1263
+ * What a person may send in the composer without being asked:
1300
1264
  * the kinds it takes, each with its largest size, and how many at once.
1301
1265
  */
1302
1266
  export interface AppUploadsSpec {
@@ -1312,52 +1276,52 @@ export interface AppInterfaceSpec {
1312
1276
  * theme's own colours (decided 2026-10-07).
1313
1277
  */
1314
1278
  accent?: AppAccent;
1315
- /** The theme it runs in by default; the person's own when unsaid (T-30). */
1279
+ /** The theme it runs in by default; the person's own when unsaid. */
1316
1280
  theme?: AppThemeSpec;
1317
1281
  welcome: string;
1318
1282
  starters: AppStarterSpec[];
1319
- /** Slash commands picked in the composer: typing `/` lists them (P-19). */
1283
+ /** Slash commands picked in the composer: typing `/` lists them. */
1320
1284
  commands: AppCommandSpec[];
1321
- /** Mode switches in the composer, the option picked going with every run (P-19). */
1285
+ /** Mode switches in the composer, the option picked going with every run. */
1322
1286
  modes: AppModeSpec[];
1323
1287
  /**
1324
- * The actions of its code a person presses, typed (RU-5):
1288
+ * The actions of its code a person presses, typed:
1325
1289
  * written by its code (`@app.action`); absent from a spec without code.
1326
1290
  */
1327
1291
  actions?: AppActionSpec[];
1328
1292
  /**
1329
- * Several assistants in one application (P-20): two at least, or none.
1293
+ * Several assistants in one application: two at least, or none.
1330
1294
  * Absent from a spec made before profiles.
1331
1295
  */
1332
1296
  profiles?: AppProfileSpec[];
1333
1297
  /**
1334
- * What a person may set: the JSON Schema of a form (C-16), drawn beside the
1298
+ * What a person may set: the JSON Schema of a form, drawn beside the
1335
1299
  * conversation and on a deployment's Ship card; none when unsaid.
1336
1300
  */
1337
1301
  settings?: AppFormSchema;
1338
1302
  /**
1339
- * How the settings' fields are drawn (P-20): a uiSchema as
1303
+ * How the settings' fields are drawn: a uiSchema as
1340
1304
  * `@datalayer/primer-rjsf` reads it, by field name — `ui:widget` one of
1341
1305
  * `select`, `radio`, `range`, `updown`, `switch`, `checkbox`, `text`,
1342
1306
  * `textarea`, `date`, `checkboxes`, `tags`. Each field's own when unsaid.
1343
1307
  */
1344
1308
  settingsUi?: Record<string, unknown>;
1345
- /** The language its own words are in, BCP 47 (P-26); `en` when absent. */
1309
+ /** The language its own words are in, BCP 47; `en` when absent. */
1346
1310
  language?: string;
1347
- /** Its words in other languages, by BCP 47 tag (P-26). */
1311
+ /** Its words in other languages, by BCP 47 tag. */
1348
1312
  translations?: Record<string, AppTranslationSpec>;
1349
1313
  /**
1350
- * What a person may send in the composer without being asked (P-21): none
1314
+ * What a person may send in the composer without being asked: none
1351
1315
  * when unsaid — the composer offers no attachment, and the runtime refuses
1352
1316
  * a file sent with a message.
1353
1317
  */
1354
1318
  uploads?: AppUploadsSpec;
1355
1319
  /** The components of the catalog the surface may use. */
1356
1320
  components: string[];
1357
- /** Components its developer wrote (P-17); absent from a spec made before them. */
1321
+ /** Components its developer wrote; absent from a spec made before them. */
1358
1322
  customComponents?: AppCustomComponentSpec[];
1359
1323
  surface?: AppSurfaceSpec;
1360
- /** A widget's page written in its code (P-05); none when unsaid. */
1324
+ /** A widget's page written in its code; none when unsaid. */
1361
1325
  page?: AppPageSpec;
1362
1326
  /**
1363
1327
  * The avatar its floating assistant shows; the paper clip when unsaid.
@@ -1370,7 +1334,7 @@ export interface AppInterfaceSpec {
1370
1334
  * does now). The page's own when unsaid.
1371
1335
  */
1372
1336
  balloon?: AppBalloonDisplay;
1373
- /** Its voice: off unless said (VO-41); absent from a spec made before voice. */
1337
+ /** Its voice: off unless said; absent from a spec made before voice. */
1374
1338
  voice?: AppVoiceSpec;
1375
1339
  /**
1376
1340
  * The formats its answers come in, by media type, words first:
@@ -1411,8 +1375,8 @@ export interface AppTestCaseSpec {
1411
1375
  turns?: AppTestTurnSpec[];
1412
1376
  expect: string;
1413
1377
  /**
1414
- * The function of its code that decides the case, by name (P-06:
1415
- * `@app.test`); `expect` still says it in words, and decides it without
1378
+ * The function of its code that decides the case, by name
1379
+ * (`@app.test`); `expect` still says it in words, and decides it without
1416
1380
  * the file. Empty, or absent, for a case in words alone.
1417
1381
  */
1418
1382
  code?: string;
@@ -1423,7 +1387,7 @@ export interface AppTestCaseSpec {
1423
1387
  files?: AppTestFileSpec[];
1424
1388
  }
1425
1389
  /**
1426
- * What was verified, and how, each in a sentence a person reads (E-14):
1390
+ * What was verified, and how, each in a sentence a person reads:
1427
1391
  * what was tried live, what runs on recorded data, what is not verified yet.
1428
1392
  */
1429
1393
  export interface AppVerifiedSpec {
@@ -1447,14 +1411,14 @@ export interface AppRecordSpec {
1447
1411
  retentionDays: number;
1448
1412
  include: string[];
1449
1413
  /**
1450
- * Whether its conversations may be used to suggest tests (V-16): off
1414
+ * Whether its conversations may be used to suggest tests: off
1451
1415
  * unless said, and only those kept while it is on are sampled.
1452
1416
  */
1453
1417
  suggestTests: boolean;
1454
1418
  }
1455
- /** Where a check of an application's code runs (P-06). */
1419
+ /** Where a check of an application's code runs. */
1456
1420
  export type AppCheckStage = 'answer' | 'tool_call';
1457
- /** A check written in an application's code (P-06: `@app.check`). */
1421
+ /** A check written in an application's code (`@app.check`). */
1458
1422
  export interface AppCodeCheckSpec {
1459
1423
  /** The function of its code that checks. */
1460
1424
  name: string;
@@ -1468,12 +1432,12 @@ export interface AppChecksSpec {
1468
1432
  guards: string[];
1469
1433
  gates: string[];
1470
1434
  track: string;
1471
- /** Checks written in its code (P-06); absent when it has none. */
1435
+ /** Checks written in its code; absent when it has none. */
1472
1436
  code?: AppCodeCheckSpec[];
1473
1437
  }
1474
1438
  /**
1475
- * A tool of an application's own, written in its code (P-06:
1476
- * `@app.tool`): its agent calls it, and the rules decide each call by what
1439
+ * A tool of an application's own, written in its code
1440
+ * (`@app.tool`): its agent calls it, and the rules decide each call by what
1477
1441
  * it `does`, or by a rule that names it by its name alone.
1478
1442
  */
1479
1443
  export interface AppToolSpec {
@@ -1485,7 +1449,7 @@ export interface AppToolSpec {
1485
1449
  /** What it does, by class of action: `read`, `write`, `send`… */
1486
1450
  does: string[];
1487
1451
  }
1488
- /** A function of the host page the application's agent may call (D-10). */
1452
+ /** A function of the host page the application's agent may call. */
1489
1453
  export interface AppHostFunctionSpec {
1490
1454
  /** Lower-case words joined by `_`: called as the tool `host_<name>`. */
1491
1455
  name: string;
@@ -1495,7 +1459,7 @@ export interface AppHostFunctionSpec {
1495
1459
  parameters: Record<string, unknown>;
1496
1460
  }
1497
1461
  /**
1498
- * What the host page and an embedded application say to each other (D-10): the host's values it reads (`user`, `page`, or the host's own),
1462
+ * What the host page and an embedded application say to each other: the host's values it reads (`user`, `page`, or the host's own),
1499
1463
  * through the tool `host_context`, and the host's functions it may call,
1500
1464
  * each through `host_<name>` — every one of them decided by a rule that
1501
1465
  * names it.
@@ -1504,20 +1468,20 @@ export interface AppHostBridgeSpec {
1504
1468
  context: string[];
1505
1469
  functions: AppHostFunctionSpec[];
1506
1470
  /**
1507
- * Who its user is (D-21): `claimed`, what the page says (unless
1471
+ * Who its user is: `claimed`, what the page says (unless
1508
1472
  * said); `signed`, only a token the host's server signed with the
1509
1473
  * deployment's secret — the unsigned one refused.
1510
1474
  */
1511
1475
  user?: AppHostUser;
1512
1476
  }
1513
- /** What the host page's word on its visitor is worth (D-21). */
1477
+ /** What the host page's word on its visitor is worth. */
1514
1478
  export type AppHostUser = 'claimed' | 'signed';
1515
1479
  export interface AppDeploymentSpec {
1516
1480
  hosted?: {
1517
1481
  visibility: 'private' | 'invited' | 'organization' | 'link' | 'public';
1518
1482
  slug: string;
1519
1483
  /**
1520
- * At its address, only its avatar (T-21): the conversation
1484
+ * At its address, only its avatar: the conversation
1521
1485
  * opens in its balloon, as when it is shipped as `assistant`. Off
1522
1486
  * unless said.
1523
1487
  */
@@ -1526,7 +1490,7 @@ export interface AppDeploymentSpec {
1526
1490
  embedded?: {
1527
1491
  mode: AppEmbedMode;
1528
1492
  origins: string[];
1529
- /** What the host page passes it and the functions of the host it may call (D-10). */
1493
+ /** What the host page passes it and the functions of the host it may call. */
1530
1494
  host?: AppHostBridgeSpec;
1531
1495
  };
1532
1496
  }
@@ -1579,7 +1543,7 @@ export interface AppSampleAlternativeSpec {
1579
1543
  metrics: Record<string, number>;
1580
1544
  }
1581
1545
  /**
1582
- * What it is tried on before it is anybody's (E-06, E-11): published
1546
+ * What it is tried on before it is anybody's: published
1583
1547
  * with it by Datalayer, read only — what a visitor without an account
1584
1548
  * computes from, or decides on, in the browser.
1585
1549
  */
@@ -1611,7 +1575,7 @@ export interface AppSpec {
1611
1575
  skills: string[];
1612
1576
  /** Backend tools (agentspecs/backend-tools) it adds to its agent's. */
1613
1577
  backendTools: string[];
1614
- /** Tools of its own, written in its code (P-06); absent when it has none. */
1578
+ /** Tools of its own, written in its code; absent when it has none. */
1615
1579
  tools?: AppToolSpec[];
1616
1580
  /** The Frames it works under. */
1617
1581
  context: string[];
@@ -1619,7 +1583,7 @@ export interface AppSpec {
1619
1583
  contents: string[];
1620
1584
  connections: AppConnectionSpec[];
1621
1585
  /**
1622
- * The agent protocols it speaks, ids of `agentspecs/protocols` (PS-02): its `pap`, `pact` and `a2a` blocks are refused unless their protocol
1586
+ * The agent protocols it speaks, ids of `agentspecs/protocols`: its `pap`, `pact` and `a2a` blocks are refused unless their protocol
1623
1587
  * is listed, and a planned one only while it is not offered.
1624
1588
  */
1625
1589
  protocols: string[];
@@ -1627,15 +1591,15 @@ export interface AppSpec {
1627
1591
  ui: UiChoice[];
1628
1592
  /** Personal Agent Protocol; absent, the application has none. */
1629
1593
  pap?: AppPapSpec;
1630
- /** PACT: the businesses it asks for each person (PI-01). */
1594
+ /** PACT: the businesses it asks for each person. */
1631
1595
  pact?: AppPactSpec;
1632
- /** UCP and ACP: the merchants it shops at for each person (PI-01). */
1596
+ /** UCP and ACP: the merchants it shops at for each person. */
1633
1597
  commerce?: AppCommerceSpec;
1634
- /** Signed fetch: the sites it reads pages of, each request signed (EX-11). */
1598
+ /** Signed fetch: the sites it reads pages of, each request signed. */
1635
1599
  signed_fetch?: AppSignedFetchSpec;
1636
- /** One of a pair of examples: a PACT business, or the personal agent that asks it (PR-13). */
1600
+ /** One of a pair of examples: a PACT business, or the personal agent that asks it. */
1637
1601
  pair?: AppPairSpec;
1638
- /** A2A: the extensions its Agent Card advertises (PR-02). */
1602
+ /** A2A: the extensions its Agent Card advertises. */
1639
1603
  a2a?: AppA2ASpec;
1640
1604
  rules: AppRuleSpec[];
1641
1605
  permissions: AppPermissionsSpec;
@@ -1742,7 +1706,7 @@ export interface Agentspec {
1742
1706
  /** User-facing objective for the agent */
1743
1707
  goal?: string;
1744
1708
  /**
1745
- * What work this agent can be delegated (O2-07).
1709
+ * What work this agent can be delegated.
1746
1710
  *
1747
1711
  * `protocol` below says how a client and an agent talk; this says what it
1748
1712
  * is worth handing the agent. Ids come from a closed vocabulary, because
@@ -1758,7 +1722,7 @@ export interface Agentspec {
1758
1722
  /** Communication protocol (e.g., 'ag-ui', 'acp', 'a2a', 'vercel-ai') */
1759
1723
  protocol?: string;
1760
1724
  /**
1761
- * The agent protocols it speaks, ids of `agentspecs/protocols` (PS-02). `protocol` says how a page reaches it; this, what it speaks to the world.
1725
+ * The agent protocols it speaks, ids of `agentspecs/protocols`. `protocol` says how a page reaches it; this, what it speaks to the world.
1762
1726
  */
1763
1727
  protocols?: string[];
1764
1728
  /** Its UI plugins, each with the renderer it is exposed through, when it is (R8). */
@@ -1803,7 +1767,7 @@ export interface Agentspec {
1803
1767
  /** Subagent delegation configuration. */
1804
1768
  subagents?: SubAgentsConfig;
1805
1769
  /**
1806
- * Its voice, for an agent that is not an application (VO-41):
1770
+ * Its voice, for an agent that is not an application:
1807
1771
  * the fields an Appspec says under `interface.voice`; absent when unsaid.
1808
1772
  */
1809
1773
  voice?: AppVoiceSpec;