@mostra/protocol 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/dist/actions.d.ts +11 -3
  2. package/dist/actions.d.ts.map +1 -1
  3. package/dist/actions.js.map +1 -1
  4. package/dist/browser.d.ts +43 -1
  5. package/dist/browser.d.ts.map +1 -1
  6. package/dist/browser.js +29 -1
  7. package/dist/browser.js.map +1 -1
  8. package/dist/diagnostics/codes/action.d.ts +1 -1
  9. package/dist/diagnostics/codes/action.d.ts.map +1 -1
  10. package/dist/diagnostics/codes/action.js +12 -1
  11. package/dist/diagnostics/codes/action.js.map +1 -1
  12. package/dist/diagnostics/codes/index.d.ts +3 -2
  13. package/dist/diagnostics/codes/index.d.ts.map +1 -1
  14. package/dist/diagnostics/codes/index.js +3 -1
  15. package/dist/diagnostics/codes/index.js.map +1 -1
  16. package/dist/diagnostics/codes/remote.d.ts +1 -1
  17. package/dist/diagnostics/codes/remote.d.ts.map +1 -1
  18. package/dist/diagnostics/codes/remote.js +78 -1
  19. package/dist/diagnostics/codes/remote.js.map +1 -1
  20. package/dist/diagnostics/codes/submit.d.ts +1 -1
  21. package/dist/diagnostics/codes/submit.d.ts.map +1 -1
  22. package/dist/diagnostics/codes/submit.js +12 -1
  23. package/dist/diagnostics/codes/submit.js.map +1 -1
  24. package/dist/diagnostics/codes/team.d.ts +8 -0
  25. package/dist/diagnostics/codes/team.d.ts.map +1 -0
  26. package/dist/diagnostics/codes/team.js +44 -0
  27. package/dist/diagnostics/codes/team.js.map +1 -0
  28. package/dist/diagnostics/diagnostic.d.ts +1 -1
  29. package/dist/diagnostics/diagnostic.d.ts.map +1 -1
  30. package/dist/diagnostics/diagnostic.js +2 -1
  31. package/dist/diagnostics/diagnostic.js.map +1 -1
  32. package/dist/index.d.ts +17 -7
  33. package/dist/index.js +14 -4
  34. package/dist/interaction.d.ts +17 -3
  35. package/dist/interaction.d.ts.map +1 -1
  36. package/dist/interaction.js +17 -13
  37. package/dist/interaction.js.map +1 -1
  38. package/dist/manifest.d.ts +3 -0
  39. package/dist/manifest.d.ts.map +1 -1
  40. package/dist/manifest.js +5 -2
  41. package/dist/manifest.js.map +1 -1
  42. package/dist/methods/artifact/pause.d.ts +33 -0
  43. package/dist/methods/artifact/pause.d.ts.map +1 -0
  44. package/dist/methods/artifact/pause.js +33 -0
  45. package/dist/methods/artifact/pause.js.map +1 -0
  46. package/dist/methods/index.d.ts.map +1 -1
  47. package/dist/methods/index.js +16 -2
  48. package/dist/methods/index.js.map +1 -1
  49. package/dist/methods/port/relay-author.d.ts +28 -0
  50. package/dist/methods/port/relay-author.d.ts.map +1 -0
  51. package/dist/methods/port/relay-author.js +42 -0
  52. package/dist/methods/port/relay-author.js.map +1 -0
  53. package/dist/methods/port/trusted-controls-policy.d.ts +1 -1
  54. package/dist/methods/remote/link.d.ts +40 -0
  55. package/dist/methods/remote/link.d.ts.map +1 -0
  56. package/dist/methods/remote/link.js +40 -0
  57. package/dist/methods/remote/link.js.map +1 -0
  58. package/dist/methods/results/get.d.ts +3 -1
  59. package/dist/methods/results/get.d.ts.map +1 -1
  60. package/dist/methods/results/get.js +4 -3
  61. package/dist/methods/results/get.js.map +1 -1
  62. package/dist/methods/results/list.d.ts +33 -0
  63. package/dist/methods/results/list.d.ts.map +1 -0
  64. package/dist/methods/results/list.js +35 -0
  65. package/dist/methods/results/list.js.map +1 -0
  66. package/dist/methods/roster/add.d.ts +47 -0
  67. package/dist/methods/roster/add.d.ts.map +1 -0
  68. package/dist/methods/roster/add.js +46 -0
  69. package/dist/methods/roster/add.js.map +1 -0
  70. package/dist/methods/roster/get.d.ts +18 -0
  71. package/dist/methods/roster/get.d.ts.map +1 -0
  72. package/dist/methods/roster/get.js +22 -0
  73. package/dist/methods/roster/get.js.map +1 -0
  74. package/dist/methods/roster/remove.d.ts +28 -0
  75. package/dist/methods/roster/remove.d.ts.map +1 -0
  76. package/dist/methods/roster/remove.js +31 -0
  77. package/dist/methods/roster/remove.js.map +1 -0
  78. package/dist/methods/share/start.d.ts +15 -2
  79. package/dist/methods/share/start.d.ts.map +1 -1
  80. package/dist/methods/share/start.js +5 -1
  81. package/dist/methods/share/start.js.map +1 -1
  82. package/dist/methods/state/get.d.ts +1 -1
  83. package/dist/methods/state/patch.d.ts +1 -1
  84. package/dist/methods/view/url.d.ts +1 -1
  85. package/dist/methods/wait/wait.d.ts +1 -1
  86. package/dist/operator.d.ts +511 -0
  87. package/dist/operator.d.ts.map +1 -0
  88. package/dist/operator.js +134 -0
  89. package/dist/operator.js.map +1 -0
  90. package/dist/team-settings.d.ts +21 -0
  91. package/dist/team-settings.d.ts.map +1 -0
  92. package/dist/team-settings.js +27 -0
  93. package/dist/team-settings.js.map +1 -0
  94. package/dist/team.d.ts +221 -0
  95. package/dist/team.d.ts.map +1 -0
  96. package/dist/team.js +162 -0
  97. package/dist/team.js.map +1 -0
  98. package/dist/verify.d.ts +7 -0
  99. package/dist/verify.d.ts.map +1 -1
  100. package/dist/verify.js.map +1 -1
  101. package/dist/worker.d.ts +1 -1
  102. package/package.json +11 -1
  103. package/schemas/protocol.draft-07.json +1027 -45
  104. package/schemas/protocol.schema.json +996 -46
  105. package/src/actions.ts +8 -4
  106. package/src/browser.ts +64 -0
  107. package/src/diagnostics/codes/action.ts +12 -0
  108. package/src/diagnostics/codes/index.ts +6 -2
  109. package/src/diagnostics/codes/remote.ts +84 -0
  110. package/src/diagnostics/codes/submit.ts +12 -0
  111. package/src/diagnostics/codes/team.ts +53 -0
  112. package/src/diagnostics/diagnostic.ts +3 -1
  113. package/src/index.ts +66 -2
  114. package/src/interaction.ts +30 -5
  115. package/src/manifest.ts +5 -0
  116. package/src/methods/artifact/pause.ts +59 -0
  117. package/src/methods/index.ts +14 -0
  118. package/src/methods/port/relay-author.ts +57 -0
  119. package/src/methods/remote/link.ts +65 -0
  120. package/src/methods/results/get.ts +3 -2
  121. package/src/methods/results/list.ts +61 -0
  122. package/src/methods/roster/add.ts +77 -0
  123. package/src/methods/roster/get.ts +30 -0
  124. package/src/methods/roster/remove.ts +49 -0
  125. package/src/methods/share/start.ts +23 -3
  126. package/src/operator.ts +660 -0
  127. package/src/team-settings.ts +38 -0
  128. package/src/team.ts +398 -0
  129. package/src/verify.ts +7 -0
@@ -0,0 +1,59 @@
1
+ import * as z from "zod";
2
+ import { ArtifactRef } from "../../artifact.ts";
3
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
4
+ import { wireRegistry } from "../../wire-registry.ts";
5
+
6
+ /** Who paused an artifact (D165 item 14). */
7
+ export type PausedBy = "owner" | "operator";
8
+
9
+ /** The params of `artifact/pause` (INTERFACES §18.2, D165 item 14). */
10
+ export interface ArtifactPauseParams {
11
+ /** The artifact to pause or resume. */
12
+ readonly artifact: ArtifactRef;
13
+ /** `true` pauses it, `false` resumes it. */
14
+ readonly paused: boolean;
15
+ /** Why, shown to viewers as text while it is paused. */
16
+ readonly reason?: string;
17
+ /** Makes retries idempotent: a repeated `requestId` returns the recorded result (H-03). */
18
+ readonly requestId?: string;
19
+ }
20
+
21
+ /** The result of `artifact/pause`: whether the artifact is paused now, and by whom. */
22
+ export interface ArtifactPauseResult {
23
+ /** Whether it is paused after the call. */
24
+ readonly paused: boolean;
25
+ /** Who paused it, while it is paused. */
26
+ readonly by?: PausedBy;
27
+ }
28
+
29
+ const params: z.ZodType<ArtifactPauseParams> = z
30
+ .object({
31
+ artifact: ArtifactRef,
32
+ paused: z.boolean(),
33
+ reason: z.string().max(500).exactOptional(),
34
+ requestId: z.string().min(1).exactOptional(),
35
+ })
36
+ .register(wireRegistry, { id: "ArtifactPauseParams" });
37
+
38
+ const result: z.ZodType<ArtifactPauseResult> = z
39
+ .object({
40
+ paused: z.boolean(),
41
+ by: z.enum(["owner", "operator"]).exactOptional(),
42
+ })
43
+ .register(wireRegistry, { id: "ArtifactPauseResult" });
44
+
45
+ /**
46
+ * `artifact/pause`: pauses or resumes an artifact. While paused it stays viewable and its shell
47
+ * says so; submissions answer 423 `MOSTRA_SUBMIT_PAUSED` and actions 423 `MOSTRA_ACTION_PAUSED`,
48
+ * each keeping the draft; links stay valid. On an owner instance it acts on the local artifact and,
49
+ * for a hosted one, on every server it is hosted on. An operator's pause can't be resumed by the
50
+ * owner (`MOSTRA_REMOTE_PAUSED_BY_OPERATOR`).
51
+ */
52
+ export const artifactPauseMethod: MethodDefinition<ArtifactPauseParams, ArtifactPauseResult> =
53
+ defineMethod({
54
+ method: "artifact/pause",
55
+ direction: "client-to-instance",
56
+ mutating: true,
57
+ params,
58
+ result,
59
+ });
@@ -9,6 +9,7 @@ import { artifactExportMethod } from "./artifact/export.ts";
9
9
  import { artifactGetMethod } from "./artifact/get.ts";
10
10
  import { artifactImportMethod } from "./artifact/import.ts";
11
11
  import { artifactListMethod } from "./artifact/list.ts";
12
+ import { artifactPauseMethod } from "./artifact/pause.ts";
12
13
  import { artifactPublishMethod } from "./artifact/publish.ts";
13
14
  import { artifactVerifyMethod } from "./artifact/verify.ts";
14
15
  import { depsAddMethod } from "./deps/add.ts";
@@ -29,6 +30,7 @@ import { mostraShutdownMethod } from "./mostra/shutdown.ts";
29
30
  import { portAddressingExternalBaseMethod } from "./port/addressing-external-base.ts";
30
31
  import { portDraftsMirrorMethod } from "./port/drafts-mirror.ts";
31
32
  import { portIdentityResolveMethod } from "./port/identity-resolve.ts";
33
+ import { portRelayAuthorMethod } from "./port/relay-author.ts";
32
34
  import { portRelayCallMethod } from "./port/relay-call.ts";
33
35
  import { portRelayCancelMethod } from "./port/relay-cancel.ts";
34
36
  import { portRelayLiveMethod } from "./port/relay-live.ts";
@@ -42,12 +44,17 @@ import { relayCallBatchMethod } from "./relay/call-batch.ts";
42
44
  import { relayEffectMethod } from "./relay/effect.ts";
43
45
  import { relayLiveValueMethod } from "./relay/live-value.ts";
44
46
  import { relayRunUpdateMethod } from "./relay/run-update.ts";
47
+ import { remoteLinkMethod } from "./remote/link.ts";
45
48
  import { remoteLoginMethod } from "./remote/login.ts";
46
49
  import { remoteLoginWaitMethod } from "./remote/login-wait.ts";
47
50
  import { remoteLogoutMethod } from "./remote/logout.ts";
48
51
  import { remoteStatusMethod } from "./remote/status.ts";
49
52
  import { remoteTokenMethod } from "./remote/token.ts";
50
53
  import { resultsGetMethod } from "./results/get.ts";
54
+ import { resultsListMethod } from "./results/list.ts";
55
+ import { rosterAddMethod } from "./roster/add.ts";
56
+ import { rosterGetMethod } from "./roster/get.ts";
57
+ import { rosterRemoveMethod } from "./roster/remove.ts";
51
58
  import { secretDeleteMethod } from "./secret/delete.ts";
52
59
  import { secretListMethod } from "./secret/list.ts";
53
60
  import { secretSetMethod } from "./secret/set.ts";
@@ -124,6 +131,13 @@ export const hostMethods: readonly AnyMethod[] = [
124
131
  portRelayLiveMethod,
125
132
  relayLiveValueMethod,
126
133
  hostedSubmissionMethod,
134
+ artifactPauseMethod,
135
+ portRelayAuthorMethod,
136
+ remoteLinkMethod,
137
+ rosterAddMethod,
138
+ rosterRemoveMethod,
139
+ rosterGetMethod,
140
+ resultsListMethod,
127
141
  // gen:methods
128
142
  ];
129
143
 
@@ -0,0 +1,57 @@
1
+ import * as z from "zod";
2
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
3
+ import { wireRegistry } from "../../wire-registry.ts";
4
+
5
+ /**
6
+ * What remote MCP may ask an owner instance to do for it (INTERFACES §18.8, D165 item 5): the
7
+ * authoring methods of the host protocol, and the owner's workspace (`McpWorkspace`, its root and
8
+ * its artifacts' files) and verify's screenshots, which only that machine holds.
9
+ */
10
+ export const RELAY_AUTHOR_METHODS = [
11
+ "artifact/create",
12
+ "artifact/verify",
13
+ "artifact/publish",
14
+ "artifact/get",
15
+ "workspace/root",
16
+ "workspace/allocate",
17
+ "workspace/read",
18
+ "workspace/apply",
19
+ "verify/screenshot",
20
+ ] as const;
21
+
22
+ /** One of {@link RELAY_AUTHOR_METHODS}. */
23
+ export type RelayAuthorMethod = (typeof RELAY_AUTHOR_METHODS)[number];
24
+
25
+ /** The params of `port/relay.author` (INTERFACES §18.3). */
26
+ export interface PortRelayAuthorParams {
27
+ /** What to do on the owner instance. */
28
+ readonly method: RelayAuthorMethod;
29
+ /** Its params: the host protocol method's, or the workspace operation's. */
30
+ readonly params: unknown;
31
+ }
32
+
33
+ /** The result of `port/relay.author`: the method's own result. */
34
+ export type PortRelayAuthorResult = unknown;
35
+
36
+ const params: z.ZodType<PortRelayAuthorParams> = z
37
+ .object({ method: z.enum(RELAY_AUTHOR_METHODS), params: z.unknown() })
38
+ .register(wireRegistry, { id: "PortRelayAuthorParams" });
39
+
40
+ const result: z.ZodType<PortRelayAuthorResult> = z
41
+ .unknown()
42
+ .register(wireRegistry, { id: "PortRelayAuthorResult" });
43
+
44
+ /**
45
+ * `port/relay.author`: the remote MCP server relays an authoring step to the account's default
46
+ * owner instance (D165 item 5), which runs it in its own workspace, builder and `verify`, and
47
+ * answers its result or its diagnostic. A publish through it also hosts the version on the server
48
+ * that asked and answers the hosted link. Workspace paths stay inside the owner's workspace.
49
+ */
50
+ export const portRelayAuthorMethod: MethodDefinition<PortRelayAuthorParams, PortRelayAuthorResult> =
51
+ defineMethod({
52
+ method: "port/relay.author",
53
+ direction: "instance-to-host",
54
+ mutating: true,
55
+ params,
56
+ result,
57
+ });
@@ -0,0 +1,65 @@
1
+ import * as z from "zod";
2
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
3
+ import { ServerOrigin } from "../../remote.ts";
4
+ import { wireRegistry } from "../../wire-registry.ts";
5
+
6
+ /** The params of `remote/link` (INTERFACES §18.2). */
7
+ export interface RemoteLinkParams {
8
+ /** The server's API origin. */
9
+ readonly server: ServerOrigin;
10
+ /**
11
+ * A credential the server's operator issued for an account (`accounts.authenticate`, §18.6), in
12
+ * place of a person's sign-in: a program runs an always-on owner instance with it. Kept in the
13
+ * home, owner-only, like a refresh token; never logged.
14
+ */
15
+ readonly key: string;
16
+ /** Makes this instance the account's default: the one chat-host authoring goes to (D165 item 1b). */
17
+ readonly default?: boolean;
18
+ }
19
+
20
+ /** The result of `remote/link`: this home is linked to the server for the key's account. */
21
+ export interface RemoteLinkResult {
22
+ /** The server linked to. */
23
+ readonly server: ServerOrigin;
24
+ /** The account the key is the operator's credential for. */
25
+ readonly account: { readonly id: string; readonly name?: string };
26
+ /** This home's instance link on that server (`lnk_…`), one per key's subject. */
27
+ readonly instanceId: string;
28
+ /** Whether this instance is the account's default. */
29
+ readonly default: boolean;
30
+ }
31
+
32
+ const params: z.ZodType<RemoteLinkParams> = z
33
+ .object({
34
+ server: ServerOrigin,
35
+ key: z.string().min(20).max(512),
36
+ default: z.boolean().exactOptional(),
37
+ })
38
+ .register(wireRegistry, { id: "RemoteLinkParams" });
39
+
40
+ const result: z.ZodType<RemoteLinkResult> = z
41
+ .object({
42
+ server: ServerOrigin,
43
+ account: z.object({ id: z.string(), name: z.string().exactOptional() }),
44
+ instanceId: z.string(),
45
+ default: z.boolean(),
46
+ })
47
+ .register(wireRegistry, {
48
+ id: "RemoteLinkResult",
49
+ description: "A home linked to a remote server with an operator-issued key.",
50
+ });
51
+
52
+ /**
53
+ * `remote/link`: links this home to a remote server with a key its operator issued for an account,
54
+ * in place of `remote/login`'s device grant, so a program can run an always-on owner instance
55
+ * (WP-30, D167). Linking again with a key is idempotent by nature, so it takes no `requestId`: the
56
+ * ledger never records the key's digest. A key the server doesn't admit is
57
+ * `MOSTRA_REMOTE_LOGIN_FAILED`.
58
+ */
59
+ export const remoteLinkMethod: MethodDefinition<RemoteLinkParams, RemoteLinkResult> = defineMethod({
60
+ method: "remote/link",
61
+ direction: "client-to-instance",
62
+ mutating: false,
63
+ params,
64
+ result,
65
+ });
@@ -42,7 +42,8 @@ export const ResultsMarkdown: z.ZodType<ResultsMarkdown> = z
42
42
  description: "A submission's results as Markdown for agents.",
43
43
  });
44
44
 
45
- const result: z.ZodType<ResultsGetResult> = z
45
+ /** The Zod schema of the `ResultsGetResult` type. */
46
+ export const ResultsGetResult: z.ZodType<ResultsGetResult> = z
46
47
  .union([Results, ResultsMarkdown])
47
48
  .register(wireRegistry, { id: "ResultsGetResult" });
48
49
 
@@ -55,5 +56,5 @@ export const resultsGetMethod: MethodDefinition<ResultsGetParams, ResultsGetResu
55
56
  direction: "client-to-instance",
56
57
  mutating: false,
57
58
  params,
58
- result,
59
+ result: ResultsGetResult,
59
60
  });
@@ -0,0 +1,61 @@
1
+ import * as z from "zod";
2
+ import { ArtifactRef } from "../../artifact.ts";
3
+ import { Cursor } from "../../ids.ts";
4
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
5
+ import { wireRegistry } from "../../wire-registry.ts";
6
+ import { type ResultsGetResult, ResultsGetResult as ResultsGetResultSchema } from "./get.ts";
7
+
8
+ /** The most submissions one `results/list` answer carries. */
9
+ export const RESULTS_LIST_MAX = 100;
10
+
11
+ /** The params of `results/list` (INTERFACES §6, §8, D168). */
12
+ export interface ResultsListParams {
13
+ /** The artifact whose submissions to read. */
14
+ readonly artifact: ArtifactRef;
15
+ /** Only submissions made after this cursor; absent: from the first. */
16
+ readonly after?: string;
17
+ /** At most this many, oldest first (1 to 100, default 100). */
18
+ readonly limit?: number;
19
+ /** `json` (the default): the Results structure of each; `md`: each as Markdown. */
20
+ readonly format?: "json" | "md";
21
+ }
22
+
23
+ /** The result of `results/list`. */
24
+ export interface ResultsListResult {
25
+ /** The submissions, oldest first, each as `results/get` gives it. */
26
+ readonly results: readonly ResultsGetResult[];
27
+ /** The cursor to read on from: the last submission's, or `after` when none came. */
28
+ readonly cursor: string;
29
+ /** Whether more submissions follow the cursor. */
30
+ readonly more: boolean;
31
+ }
32
+
33
+ const params: z.ZodType<ResultsListParams> = z
34
+ .object({
35
+ artifact: ArtifactRef,
36
+ after: Cursor.schema.exactOptional(),
37
+ limit: z.int().min(1).max(RESULTS_LIST_MAX).exactOptional(),
38
+ format: z.enum(["json", "md"]).exactOptional(),
39
+ })
40
+ .register(wireRegistry, { id: "ResultsListParams" });
41
+
42
+ const result: z.ZodType<ResultsListResult> = z
43
+ .object({
44
+ results: z.array(ResultsGetResultSchema).readonly(),
45
+ cursor: Cursor.schema,
46
+ more: z.boolean(),
47
+ })
48
+ .register(wireRegistry, { id: "ResultsListResult" });
49
+
50
+ /**
51
+ * `results/list`: every submission of an artifact after a cursor, oldest first, as `results/get`
52
+ * gives each (J14: all five answers once the roster completed). Page on with `cursor` while `more`.
53
+ */
54
+ export const resultsListMethod: MethodDefinition<ResultsListParams, ResultsListResult> =
55
+ defineMethod({
56
+ method: "results/list",
57
+ direction: "client-to-instance",
58
+ mutating: false,
59
+ params,
60
+ result,
61
+ });
@@ -0,0 +1,77 @@
1
+ import * as z from "zod";
2
+ import { ArtifactRef } from "../../artifact.ts";
3
+ import { CapabilityScope } from "../../capability.ts";
4
+ import { Duration } from "../../duration.ts";
5
+ import { VersionId } from "../../ids.ts";
6
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
7
+ import { RespondentSpec, ROSTER_MAX, Roster } from "../../team.ts";
8
+ import { wireRegistry } from "../../wire-registry.ts";
9
+ import { CapabilityLink } from "../view/url.ts";
10
+
11
+ /** The params of `roster/add` (INTERFACES §6, D121, D168). */
12
+ export interface RosterAddParams {
13
+ /** The artifact the people are expected to answer. */
14
+ readonly artifact: ArtifactRef;
15
+ /** The people expected to answer, by the host's stable key (D104); one already there is kept. */
16
+ readonly respondents: readonly RespondentSpec[];
17
+ /** What a new personal link allows (D97). Default: every scope. */
18
+ readonly scopes?: readonly CapabilityScope[];
19
+ /** How long a new personal link works. Default: until it is revoked (D63). */
20
+ readonly ttl?: Duration;
21
+ /** The version a new personal link opens, by number or ID; absent: the latest, always. */
22
+ readonly version?: number | string;
23
+ /** Makes retries idempotent (H-03). */
24
+ readonly requestId?: string;
25
+ }
26
+
27
+ /** A respondent's personal link (CO-01). */
28
+ export interface RespondentLink {
29
+ /** The respondent it is for. */
30
+ readonly ref: string;
31
+ /** Their link: it acts as their viewer (D104). Holding it is the authorization (D06). */
32
+ readonly link: CapabilityLink;
33
+ }
34
+
35
+ /** The Zod schema of the `RespondentLink` type. */
36
+ export const RespondentLink: z.ZodType<RespondentLink> = z
37
+ .object({ ref: z.string(), link: CapabilityLink })
38
+ .register(wireRegistry, {
39
+ id: "RespondentLink",
40
+ description: "An expected respondent's personal link, acting as their viewer.",
41
+ });
42
+
43
+ /** The result of `roster/add`. */
44
+ export interface RosterAddResult {
45
+ /** The roster after the change. */
46
+ readonly roster: Roster;
47
+ /** The personal link of every respondent named, in the order given. */
48
+ readonly links: readonly RespondentLink[];
49
+ }
50
+
51
+ const params: z.ZodType<RosterAddParams> = z
52
+ .object({
53
+ artifact: ArtifactRef,
54
+ respondents: z.array(RespondentSpec).min(1).max(ROSTER_MAX).readonly(),
55
+ scopes: z.array(CapabilityScope).min(1).readonly().exactOptional(),
56
+ ttl: Duration.exactOptional(),
57
+ version: z.union([z.int().min(1), VersionId.schema]).exactOptional(),
58
+ requestId: z.string().min(1).exactOptional(),
59
+ })
60
+ .register(wireRegistry, { id: "RosterAddParams" });
61
+
62
+ const result: z.ZodType<RosterAddResult> = z
63
+ .object({ roster: Roster, links: z.array(RespondentLink).readonly() })
64
+ .register(wireRegistry, { id: "RosterAddResult" });
65
+
66
+ /**
67
+ * `roster/add`: names people an artifact expects answers from and gives each a personal link that
68
+ * acts as their viewer (CO-01). Idempotent by `ref`: a respondent already there keeps their link
69
+ * (a revoked one is replaced), and a name given again replaces theirs. Appends `roster.changed`.
70
+ */
71
+ export const rosterAddMethod: MethodDefinition<RosterAddParams, RosterAddResult> = defineMethod({
72
+ method: "roster/add",
73
+ direction: "client-to-instance",
74
+ mutating: true,
75
+ params,
76
+ result,
77
+ });
@@ -0,0 +1,30 @@
1
+ import * as z from "zod";
2
+ import { ArtifactRef } from "../../artifact.ts";
3
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
4
+ import { Roster } from "../../team.ts";
5
+ import { wireRegistry } from "../../wire-registry.ts";
6
+
7
+ /** The params of `roster/get` (INTERFACES §6, D168). */
8
+ export interface RosterGetParams {
9
+ /** The artifact. */
10
+ readonly artifact: ArtifactRef;
11
+ }
12
+
13
+ /** The result of `roster/get`: the whole roster, whatever the visibility policy (CO-07). */
14
+ export type RosterGetResult = Roster;
15
+
16
+ const params: z.ZodType<RosterGetParams> = z
17
+ .object({ artifact: ArtifactRef })
18
+ .register(wireRegistry, { id: "RosterGetParams" });
19
+
20
+ /**
21
+ * `roster/get`: every expected respondent with their status in the current round (CO-03), the
22
+ * round, whether it is complete and its counts. Agents and hosts always read all of it (CO-07).
23
+ */
24
+ export const rosterGetMethod: MethodDefinition<RosterGetParams, RosterGetResult> = defineMethod({
25
+ method: "roster/get",
26
+ direction: "client-to-instance",
27
+ mutating: false,
28
+ params,
29
+ result: Roster,
30
+ });
@@ -0,0 +1,49 @@
1
+ import * as z from "zod";
2
+ import { ArtifactRef } from "../../artifact.ts";
3
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
4
+ import { ROSTER_MAX, Roster } from "../../team.ts";
5
+ import { wireRegistry } from "../../wire-registry.ts";
6
+
7
+ /** The params of `roster/remove` (INTERFACES §6, D168). */
8
+ export interface RosterRemoveParams {
9
+ /** The artifact. */
10
+ readonly artifact: ArtifactRef;
11
+ /** The respondents no longer expected, by `ref`; unknown ones are ignored. */
12
+ readonly refs: readonly string[];
13
+ /** Makes retries idempotent (H-03). */
14
+ readonly requestId?: string;
15
+ }
16
+
17
+ /** The result of `roster/remove`. */
18
+ export interface RosterRemoveResult {
19
+ /** The roster after the change. */
20
+ readonly roster: Roster;
21
+ /** The refs that were on the roster and left it. */
22
+ readonly removed: readonly string[];
23
+ }
24
+
25
+ const params: z.ZodType<RosterRemoveParams> = z
26
+ .object({
27
+ artifact: ArtifactRef,
28
+ refs: z.array(z.string().min(1).max(256)).min(1).max(ROSTER_MAX).readonly(),
29
+ requestId: z.string().min(1).exactOptional(),
30
+ })
31
+ .register(wireRegistry, { id: "RosterRemoveParams" });
32
+
33
+ const result: z.ZodType<RosterRemoveResult> = z
34
+ .object({ roster: Roster, removed: z.array(z.string()).readonly() })
35
+ .register(wireRegistry, { id: "RosterRemoveResult" });
36
+
37
+ /**
38
+ * `roster/remove`: stops expecting answers from people (D168). Their personal links keep working
39
+ * until revoked (`view/revoke`), and their drafts and submissions stay. Appends `roster.changed`,
40
+ * and `roster.completed` when everyone still expected has answered.
41
+ */
42
+ export const rosterRemoveMethod: MethodDefinition<RosterRemoveParams, RosterRemoveResult> =
43
+ defineMethod({
44
+ method: "roster/remove",
45
+ direction: "client-to-instance",
46
+ mutating: true,
47
+ params,
48
+ result,
49
+ });
@@ -5,7 +5,9 @@ import { Duration } from "../../duration.ts";
5
5
  import { ArtifactId, ShareId, TokenId } from "../../ids.ts";
6
6
  import { ViewerSpec } from "../../interaction.ts";
7
7
  import { defineMethod, type MethodDefinition } from "../../method.ts";
8
+ import { RespondentSpec, ROSTER_MAX } from "../../team.ts";
8
9
  import { wireRegistry } from "../../wire-registry.ts";
10
+ import { RespondentLink } from "../roster/add.ts";
9
11
 
10
12
  /**
11
13
  * How a share reaches its viewers (D158): `tailnet` through Tailscale Serve, to the people of the
@@ -49,6 +51,13 @@ export interface ShareStartParams {
49
51
  * port names, else the link's own viewer, never the home's local user (D158).
50
52
  */
51
53
  readonly viewer?: ViewerSpec;
54
+ /**
55
+ * People the artifact expects answers from through this share (D121, D168): they join the
56
+ * roster of the home that holds the artifact's viewers (a remote share's hosted home), and each
57
+ * gets a personal link at the share's address. On a remote server, `email` reaches the operator's
58
+ * `invitations` port. Not with `viewer`.
59
+ */
60
+ readonly respondents?: readonly RespondentSpec[];
52
61
  /** Makes retries idempotent: a repeated `requestId` returns the same share (H-03). */
53
62
  readonly requestId?: string;
54
63
  }
@@ -118,8 +127,14 @@ export const Share: z.ZodType<Share> = z.object(shareShape).register(wireRegistr
118
127
  description: "A share: its tunnel, link, address, frame mode and lifetime.",
119
128
  });
120
129
 
121
- /** The result of `share/start`: the share, with its link. */
122
- export type ShareStartResult = Share & { readonly url: string };
130
+ /**
131
+ * The result of `share/start`: the share, with its link, and the personal link of every respondent
132
+ * it named (D168).
133
+ */
134
+ export type ShareStartResult = Share & {
135
+ readonly url: string;
136
+ readonly respondents?: readonly RespondentLink[];
137
+ };
123
138
 
124
139
  const params: z.ZodType<ShareStartParams> = z
125
140
  .object({
@@ -132,12 +147,17 @@ const params: z.ZodType<ShareStartParams> = z
132
147
  ttl: Duration.exactOptional(),
133
148
  scopes: z.array(CapabilityScope).min(1).readonly().exactOptional(),
134
149
  viewer: ViewerSpec.exactOptional(),
150
+ respondents: z.array(RespondentSpec).min(1).max(ROSTER_MAX).readonly().exactOptional(),
135
151
  requestId: z.string().min(1).exactOptional(),
136
152
  })
137
153
  .register(wireRegistry, { id: "ShareStartParams" });
138
154
 
139
155
  const result: z.ZodType<ShareStartResult> = z
140
- .object({ ...shareShape, url: z.string().min(1) })
156
+ .object({
157
+ ...shareShape,
158
+ url: z.string().min(1),
159
+ respondents: z.array(RespondentLink).readonly().exactOptional(),
160
+ })
141
161
  .register(wireRegistry, {
142
162
  id: "ShareStartResult",
143
163
  description: "The share that started, with its capability URL.",