@atcx/contract 7.5.1 → 7.7.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.
package/README.md CHANGED
@@ -3,12 +3,12 @@
3
3
 
4
4
  <p>
5
5
  <a href="https://www.npmjs.com/package/@atcx/contract"><img src="https://img.shields.io/npm/v/@atcx/contract" alt="npm version"></a>
6
- <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.5.1/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
6
+ <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.0/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
7
7
  </p>
8
8
 
9
9
  <p>
10
- <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.5.1/docs/architecture/protocol/contract.md">The published contract</a> •
11
- <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.5.1/docs/architecture/protocol/protocol.md">The client protocol</a>
10
+ <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.0/docs/architecture/protocol/contract.md">The published contract</a> •
11
+ <a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.0/docs/architecture/protocol/protocol.md">The client protocol</a>
12
12
  </p>
13
13
  </div>
14
14
 
@@ -46,15 +46,17 @@ bun add -d @opentelemetry/api
46
46
  for the session record a session's helpers read.
47
47
  - **Checking a daemon.** `checkDaemon` compares the major version in the hello answer with the
48
48
  contract's, and lists the features that differ.
49
+ - **The gateway.** `GATEWAY_PATHS`, the routes atc-gateway serves grouped as browser, machine and
50
+ probe paths, and `GATEWAY_REGISTRY_SCHEMA`, the rules of the gateway's registry file.
49
51
  - **The light entry.** `@atcx/contract/light` holds the session environment names, the state paths
50
52
  and the error codes without the request contract, for a process that starts once per event.
51
53
 
52
54
  ## Configuration
53
55
 
54
56
  `CONFIG_FILE_SCHEMA` parses the top-level keys of atc's `config.json`, and the
55
- [configuration guide](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.5.1/docs/guides/configuration.md) describes each key.
57
+ [configuration guide](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.0/docs/guides/configuration.md) describes each key.
56
58
 
57
59
  ## Documentation
58
60
 
59
- [The published contract](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.5.1/docs/architecture/protocol/contract.md) covers what the package holds
61
+ [The published contract](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.0/docs/architecture/protocol/contract.md) covers what the package holds
60
62
  and how its version moves with atc's.
@@ -5,6 +5,7 @@ export declare const DAEMON_CONTRACT: {
5
5
  client: z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>;
6
6
  protocol: z.ZodOptional<z.ZodNumber>;
7
7
  principal: z.ZodOptional<z.ZodString>;
8
+ viewer: z.ZodOptional<z.ZodString>;
8
9
  session: z.ZodPreprocess<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./session-id.js").SessionID, string>>>, unknown>;
9
10
  }, z.core.$strip>, z.ZodObject<{
10
11
  daemon: z.ZodString;
@@ -468,6 +469,12 @@ export declare const DAEMON_CONTRACT: {
468
469
  trustClonedWorkspace: z.ZodOptional<z.ZodBoolean>;
469
470
  scope: z.ZodOptional<z.ZodUnknown>;
470
471
  parent: z.ZodPreprocess<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./session-id.js").SessionID, string>>>, unknown>;
472
+ atcAccess: z.ZodOptional<z.ZodArray<z.ZodEnum<{
473
+ kill: "kill";
474
+ message: "message";
475
+ read: "read";
476
+ spawn: "spawn";
477
+ }>>>;
471
478
  }, z.core.$strip>, z.ZodObject<{
472
479
  session: z.ZodObject<{
473
480
  id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./session-id.js").SessionID, string>>;
@@ -1,2 +1,2 @@
1
- export declare const DAEMON_FEATURES: readonly ['events.read.from-start'];
1
+ export declare const DAEMON_FEATURES: readonly ['events.read.from-start', 'daemon.hello.viewer'];
2
2
  export type DaemonFeature = (typeof DAEMON_FEATURES)[number];
@@ -0,0 +1,22 @@
1
+ export declare const GATEWAY_PATHS: {
2
+ readonly browser: {
3
+ readonly authorize: '/oauth2/authorize';
4
+ readonly login: '/login';
5
+ readonly enroll: '/enroll';
6
+ readonly consent: '/consent';
7
+ readonly error: '/error';
8
+ };
9
+ readonly machine: {
10
+ readonly mcp: '/mcp';
11
+ readonly root: '/';
12
+ readonly token: '/oauth2/token';
13
+ readonly revoke: '/oauth2/revoke';
14
+ readonly authorizationServerMetadata: '/.well-known/oauth-authorization-server';
15
+ readonly resourceMetadata: '/.well-known/oauth-protected-resource';
16
+ readonly mcpResourceMetadata: '/.well-known/oauth-protected-resource/mcp';
17
+ };
18
+ readonly probes: {
19
+ readonly health: '/healthz';
20
+ readonly ready: '/readyz';
21
+ };
22
+ };
@@ -0,0 +1,11 @@
1
+ import { z } from 'zod';
2
+ export declare const GATEWAY_REGISTRY_SCHEMA: z.ZodObject<{
3
+ daemons: z.ZodRecord<z.ZodString, z.ZodObject<{
4
+ address: z.ZodPipe<z.ZodString, z.ZodTransform<{
5
+ host: string;
6
+ port: number;
7
+ }, string>>;
8
+ daemonID: z.ZodString;
9
+ }, z.core.$strip>>;
10
+ defaultDaemon: z.ZodString;
11
+ }, z.core.$strip>;
@@ -0,0 +1,2 @@
1
+ export declare const GRANT_SCOPES: readonly ['read', 'message', 'spawn', 'kill'];
2
+ export type GrantScope = (typeof GRANT_SCOPES)[number];
package/dist/index.d.ts CHANGED
@@ -13,10 +13,15 @@ export * from './events-page.js';
13
13
  export type * from './daemon-id.js';
14
14
  export * from './fleet-entry-view.js';
15
15
  export * from './fleet-event.js';
16
+ export * from './gateway-paths.js';
17
+ export * from './gateway-registry-schema.js';
16
18
  export * from './git-probe-result.js';
17
19
  export * from './git-ref.js';
20
+ export * from './grant-scope.js';
18
21
  export * from './hello-result.js';
19
22
  export * from './light/index.js';
23
+ export * from './max-events-cursor-bytes.js';
24
+ export * from './max-registry-daemons.js';
20
25
  export * from './menu-view.js';
21
26
  export * from './message-answer.js';
22
27
  export type * from './message-id.js';
package/dist/index.js CHANGED
@@ -110,10 +110,10 @@ var ANSWER_VIEW_SCHEMA = z4.object({
110
110
  complete: z4.boolean()
111
111
  });
112
112
  // packages/contract/src/contract-version.ts
113
- var CONTRACT_VERSION = "7.5.1";
113
+ var CONTRACT_VERSION = "7.7.0";
114
114
 
115
115
  // packages/contract/src/daemon-features.ts
116
- var DAEMON_FEATURES = ["events.read.from-start"];
116
+ var DAEMON_FEATURES = ["events.read.from-start", "daemon.hello.viewer"];
117
117
 
118
118
  // packages/contract/src/check-daemon.ts
119
119
  function checkDaemon(hello, contractVersion = CONTRACT_VERSION) {
@@ -644,6 +644,9 @@ var PUBLISHED_RECORD_SCHEMA = z29.object({
644
644
  // packages/contract/src/request-param-schemas.ts
645
645
  import { z as z31 } from "zod";
646
646
 
647
+ // packages/contract/src/grant-scope.ts
648
+ var GRANT_SCOPES = ["read", "message", "spawn", "kill"];
649
+
647
650
  // packages/contract/src/to-message-id.ts
648
651
  import { z as z30 } from "zod";
649
652
  var MESSAGE_ID_SCHEMA = z30.string().brand();
@@ -691,6 +694,7 @@ var REQUEST_PARAM_SCHEMAS = {
691
694
  client: buildDefaultedString("unknown client"),
692
695
  protocol: z31.number({ error: "daemon.hello protocol must be a number" }).optional(),
693
696
  principal: z31.string({ error: "daemon.hello principal must be a non-empty string" }).min(1, "daemon.hello principal must be a non-empty string").optional(),
697
+ viewer: z31.string({ error: "daemon.hello viewer must be a non-empty string" }).min(1, "daemon.hello viewer must be a non-empty string").optional(),
694
698
  session: z31.preprocess((input) => typeof input === "string" && input !== "" ? input : undefined, z31.string().transform(toSessionID).optional())
695
699
  }),
696
700
  "daemon.ping": z31.object({}),
@@ -753,7 +757,12 @@ var REQUEST_PARAM_SCHEMAS = {
753
757
  workspace: WORKSPACE_SOURCE.optional(),
754
758
  trustClonedWorkspace: z31.boolean({ error: "session.spawn trustClonedWorkspace must be a boolean" }).optional(),
755
759
  scope: z31.unknown().optional(),
756
- parent: z31.preprocess((input) => typeof input === "string" && input !== "" ? input : undefined, z31.string().transform(toSessionID).optional())
760
+ parent: z31.preprocess((input) => typeof input === "string" && input !== "" ? input : undefined, z31.string().transform(toSessionID).optional()),
761
+ atcAccess: z31.array(z31.enum(GRANT_SCOPES, {
762
+ error: "session.spawn atcAccess takes read, message, spawn and kill"
763
+ }), {
764
+ error: "session.spawn atcAccess must be an array of scopes"
765
+ }).max(GRANT_SCOPES.length, "session.spawn atcAccess names each scope once").refine((scopes) => new Set(scopes).size === scopes.length, "session.spawn atcAccess names each scope once").optional()
757
766
  }),
758
767
  "session.kill": SESSION_DEFAULTED.extend({
759
768
  stopOnly: z31.boolean({ error: "session.kill stopOnly must be a boolean" }).optional()
@@ -1026,6 +1035,82 @@ var DAEMON_CONTRACT = {
1026
1035
  get: base.meta(READ).input(PARAMS["answer.get"]).output(ANSWER_VIEW_SCHEMA)
1027
1036
  }
1028
1037
  };
1038
+ // packages/contract/src/gateway-paths.ts
1039
+ var GATEWAY_PATHS = {
1040
+ browser: {
1041
+ authorize: "/oauth2/authorize",
1042
+ login: "/login",
1043
+ enroll: "/enroll",
1044
+ consent: "/consent",
1045
+ error: "/error"
1046
+ },
1047
+ machine: {
1048
+ mcp: "/mcp",
1049
+ root: "/",
1050
+ token: "/oauth2/token",
1051
+ revoke: "/oauth2/revoke",
1052
+ authorizationServerMetadata: "/.well-known/oauth-authorization-server",
1053
+ resourceMetadata: "/.well-known/oauth-protected-resource",
1054
+ mcpResourceMetadata: "/.well-known/oauth-protected-resource/mcp"
1055
+ },
1056
+ probes: {
1057
+ health: "/healthz",
1058
+ ready: "/readyz"
1059
+ }
1060
+ };
1061
+ // packages/contract/src/gateway-registry-schema.ts
1062
+ import { z as z38 } from "zod";
1063
+
1064
+ // packages/contract/src/max-events-cursor-bytes.ts
1065
+ var MAX_EVENTS_CURSOR_BYTES = 4096;
1066
+
1067
+ // packages/contract/src/max-registry-daemons.ts
1068
+ var MAX_REGISTRY_DAEMONS = 36;
1069
+
1070
+ // packages/contract/src/gateway-registry-schema.ts
1071
+ var DAEMON_NAME_PATTERN = /^[a-z][a-z0-9-]{0,30}$/u;
1072
+ var ADDRESS_PATTERN = /^(?:\[(?<v6>[^\]]+)\]|(?<host>[^:[\]]+)):(?<port>\d{1,5})$/u;
1073
+ var ADDRESS_MESSAGE = "needs an address of <host>:<port> with a port from 1 to 65535";
1074
+ var ADDRESS_SCHEMA = z38.string({ error: ADDRESS_MESSAGE }).transform((raw, ctx) => {
1075
+ const groups = ADDRESS_PATTERN.exec(raw)?.groups;
1076
+ const host = groups?.["v6"] ?? groups?.["host"];
1077
+ const port = Number(groups?.["port"]);
1078
+ if (host === undefined || !Number.isInteger(port) || port < 1 || port > 65535) {
1079
+ ctx.issues.push({ code: "custom", message: ADDRESS_MESSAGE, input: raw });
1080
+ return z38.NEVER;
1081
+ }
1082
+ return { host, port };
1083
+ });
1084
+ var DAEMON_ID_MESSAGE = "needs the daemonID that atc daemon id prints on its host";
1085
+ var DAEMON_ID_SCHEMA2 = z38.string({ error: DAEMON_ID_MESSAGE }).regex(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/u, DAEMON_ID_MESSAGE);
1086
+ var DAEMON_SCHEMA = z38.object({ address: ADDRESS_SCHEMA, daemonID: DAEMON_ID_SCHEMA2 }, { error: "must be an object with address and daemonID" });
1087
+ var GATEWAY_REGISTRY_SCHEMA = z38.object({
1088
+ daemons: z38.record(z38.string().regex(DAEMON_NAME_PATTERN), DAEMON_SCHEMA, {
1089
+ error: (issue) => issue.code === "invalid_key" ? `must match ${DAEMON_NAME_PATTERN.source}` : "the registry must be an object whose daemons is an object"
1090
+ }),
1091
+ defaultDaemon: z38.string({
1092
+ error: "defaultDaemon is required and must name a daemon in the registry"
1093
+ })
1094
+ }, { error: "the registry must be an object whose daemons is an object" }).superRefine((registry, ctx) => {
1095
+ const count = Object.keys(registry.daemons).length;
1096
+ if (count === 0) {
1097
+ ctx.addIssue({ code: "custom", path: ["daemons"], message: "the registry lists no daemon" });
1098
+ }
1099
+ if (count > MAX_REGISTRY_DAEMONS) {
1100
+ ctx.addIssue({
1101
+ code: "custom",
1102
+ path: ["daemons"],
1103
+ message: `the registry lists ${count} daemons, over the limit of ${MAX_REGISTRY_DAEMONS}, the most whose events cursor fits ${MAX_EVENTS_CURSOR_BYTES} bytes`
1104
+ });
1105
+ }
1106
+ if (!Object.hasOwn(registry.daemons, registry.defaultDaemon)) {
1107
+ ctx.addIssue({
1108
+ code: "custom",
1109
+ path: ["defaultDaemon"],
1110
+ message: `defaultDaemon '${registry.defaultDaemon}' is not a daemon in the registry`
1111
+ });
1112
+ }
1113
+ });
1029
1114
  // packages/contract/src/light/resolve-atc-paths.ts
1030
1115
  import { join as join2 } from "node:path";
1031
1116
 
@@ -1068,11 +1153,11 @@ var SESSION_ENV_NAMES = {
1068
1153
  scopeFile: "AUTO_MODE_SCOPE_FILE"
1069
1154
  };
1070
1155
  // packages/contract/src/procedure-meta.ts
1071
- import { z as z38 } from "zod";
1072
- var PROCEDURE_META_SCHEMA = z38.object({
1073
- access: z38.enum(["owner", "principal"]),
1074
- readOnly: z38.boolean(),
1075
- keyed: z38.boolean()
1156
+ import { z as z39 } from "zod";
1157
+ var PROCEDURE_META_SCHEMA = z39.object({
1158
+ access: z39.enum(["owner", "principal"]),
1159
+ readOnly: z39.boolean(),
1160
+ keyed: z39.boolean()
1076
1161
  });
1077
1162
  export {
1078
1163
  AGENT_ENTRY_SCHEMA,
@@ -1089,9 +1174,14 @@ export {
1089
1174
  EVENTS_PAGE_SCHEMA,
1090
1175
  FLEET_ENTRY_VIEW_SCHEMA,
1091
1176
  FLEET_EVENT_SCHEMA,
1177
+ GATEWAY_PATHS,
1178
+ GATEWAY_REGISTRY_SCHEMA,
1092
1179
  GIT_PROBE_RESULT_SCHEMA,
1093
1180
  GIT_REF_SCHEMA,
1181
+ GRANT_SCOPES,
1094
1182
  HELLO_RESULT_SCHEMA,
1183
+ MAX_EVENTS_CURSOR_BYTES,
1184
+ MAX_REGISTRY_DAEMONS,
1095
1185
  MENU_VIEW_SCHEMA,
1096
1186
  MESSAGE_ANSWER_SCHEMA,
1097
1187
  MESSAGE_SENDER_SCHEMA,
@@ -0,0 +1 @@
1
+ export declare const MAX_EVENTS_CURSOR_BYTES = 4096;
@@ -0,0 +1 @@
1
+ export declare const MAX_REGISTRY_DAEMONS = 36;
@@ -22,6 +22,7 @@ export declare const REQUEST_PARAM_SCHEMAS: {
22
22
  client: z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>;
23
23
  protocol: z.ZodOptional<z.ZodNumber>;
24
24
  principal: z.ZodOptional<z.ZodString>;
25
+ viewer: z.ZodOptional<z.ZodString>;
25
26
  session: z.ZodPreprocess<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./session-id.js").SessionID, string>>>, unknown>;
26
27
  }, z.core.$strip>;
27
28
  readonly 'daemon.ping': z.ZodObject<{}, z.core.$strip>;
@@ -120,6 +121,12 @@ export declare const REQUEST_PARAM_SCHEMAS: {
120
121
  trustClonedWorkspace: z.ZodOptional<z.ZodBoolean>;
121
122
  scope: z.ZodOptional<z.ZodUnknown>;
122
123
  parent: z.ZodPreprocess<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./session-id.js").SessionID, string>>>, unknown>;
124
+ atcAccess: z.ZodOptional<z.ZodArray<z.ZodEnum<{
125
+ kill: "kill";
126
+ message: "message";
127
+ read: "read";
128
+ spawn: "spawn";
129
+ }>>>;
123
130
  }, z.core.$strip>;
124
131
  readonly 'session.kill': z.ZodObject<{
125
132
  session: z.ZodPipe<z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>, z.ZodTransform<import("./session-id.js").SessionID, string>>;
package/package.json CHANGED
@@ -18,8 +18,8 @@
18
18
  "zod": "4.6.6"
19
19
  },
20
20
  "name": "@atcx/contract",
21
- "version": "7.5.1",
22
- "description": "atc's public contract: the daemon's request contract, the event, session record, hello and config schemas, the error codes, the session env names, and the state paths",
21
+ "version": "7.7.0",
22
+ "description": "atc's public contract: the daemon's request contract, the event, session record, hello and config schemas, the error codes, the session env names, the state paths, and the gateway's routes and registry schema",
23
23
  "homepage": "https://github.com/zgeoff/atc/tree/main/packages/contract#readme",
24
24
  "bugs": "https://github.com/zgeoff/atc/issues",
25
25
  "license": "MIT",