@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 +7 -5
- package/dist/daemon-contract.d.ts +7 -0
- package/dist/daemon-features.d.ts +1 -1
- package/dist/gateway-paths.d.ts +22 -0
- package/dist/gateway-registry-schema.d.ts +11 -0
- package/dist/grant-scope.d.ts +2 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +98 -8
- package/dist/max-events-cursor-bytes.d.ts +1 -0
- package/dist/max-registry-daemons.d.ts +1 -0
- package/dist/request-param-schemas.d.ts +7 -0
- package/package.json +2 -2
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.
|
|
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.
|
|
11
|
-
<a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.
|
|
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.
|
|
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.
|
|
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>;
|
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.
|
|
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
|
|
1072
|
-
var PROCEDURE_META_SCHEMA =
|
|
1073
|
-
access:
|
|
1074
|
-
readOnly:
|
|
1075
|
-
keyed:
|
|
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.
|
|
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
|
|
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",
|