@aisac/cli 0.4.0-beta.1 → 0.4.0-beta.10

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.
@@ -0,0 +1,165 @@
1
+ // @ts-check
2
+
3
+ /**
4
+ * AISAC Engineering for Codex (ADR-0047 wave E4c, spec FR4).
5
+ *
6
+ * Codex has no session plugin directory, so the method reaches only the
7
+ * app-server this launch owns, and nothing is written to `~/.codex`,
8
+ * `~/.agents` or the project:
9
+ * - skills: the adapter sends `skills/extraRoots/set` with the pack's
10
+ * `skills/` directory right after the client's initialize (in-memory in that
11
+ * process);
12
+ * - agents: one role file per pack agent, declared with `-c agents.<name>.*`
13
+ * overrides on the owned app-server (the session-flags config layer).
14
+ * The launcher hands the monitor one JSON value; the monitor validates it
15
+ * again before turning it into arguments.
16
+ */
17
+
18
+ import { basename, dirname, join, resolve } from 'node:path';
19
+
20
+ export const CODEX_ENGINEERING_ENV = 'AISAC_ENGINEERING_CODEX';
21
+ export const CODEX_ENGINEERING_SKILLS_ROOT_ENV = 'AISAC_ENGINEERING_SKILLS_ROOT';
22
+ export const CODEX_AGENTS_DIRECTORY = 'codex-agents';
23
+ const SKILLS_DIRECTORY = 'skills';
24
+ const PACK_DIRECTORY = 'engineering';
25
+ const RUNTIME_DIRECTORY = 'runtime';
26
+ const CODEX_LAUNCH_DIRECTORY = /^codex-[A-Za-z0-9]{6}$/u;
27
+ const SCHEMA_VERSION = 1;
28
+ const MAX_SPEC_BYTES = 16 * 1024;
29
+ const MAX_AGENTS = 16;
30
+ const MAX_PATH_LENGTH = 4096;
31
+ export const MAX_AGENT_DESCRIPTION_LENGTH = 1024;
32
+ export const AGENT_NAME = /^[a-z][a-z0-9-]{0,63}$/u;
33
+ const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
34
+ /** First Codex release whose session mechanism was verified (spike Q4, 2026-11-03). */
35
+ const MIN_CODEX_VERSION = /** @type {const} */ ([0, 164, 0]);
36
+
37
+ /** @typedef {{ name: string, description: string, configFile: string }} CodexAgentRole */
38
+ /** @typedef {{ schemaVersion: 1, skillsRoot: string, agents: CodexAgentRole[] }} CodexEngineering */
39
+
40
+ /** @param {string} code @returns {never} */
41
+ function fail(code) {
42
+ throw new Error(`codex_engineering_${code}`);
43
+ }
44
+
45
+ /** @param {unknown} value @returns {value is Record<string, unknown>} */
46
+ function isRecord(value) {
47
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
48
+ }
49
+
50
+ /**
51
+ * Whether this Codex version receives the pack. A null or malformed version
52
+ * never does.
53
+ * @param {string | null | undefined} version
54
+ */
55
+ export function supportsCodexEngineering(version) {
56
+ const match = /^(\d+)\.(\d+)\.(\d+)$/u.exec(version ?? '');
57
+ if (match === null) return false;
58
+ const parts = match.slice(1).map(Number);
59
+ for (let index = 0; index < MIN_CODEX_VERSION.length; index += 1) {
60
+ const part = /** @type {number} */ (parts[index]);
61
+ const minimum = MIN_CODEX_VERSION[index] ?? 0;
62
+ if (part !== minimum) return part > minimum;
63
+ }
64
+ return true;
65
+ }
66
+
67
+ /** @param {unknown} value */
68
+ function isCleanAbsolutePath(value) {
69
+ return (
70
+ typeof value === 'string' &&
71
+ value.length > 0 &&
72
+ value.length <= MAX_PATH_LENGTH &&
73
+ !CONTROL_CHARACTERS.test(value) &&
74
+ value.startsWith('/') &&
75
+ resolve(value) === value
76
+ );
77
+ }
78
+
79
+ /**
80
+ * @param {unknown} value
81
+ * @param {{ stateDir?: string }} [options] when given, the pack must sit in a
82
+ * Codex launch directory of that state directory
83
+ * @returns {CodexEngineering}
84
+ */
85
+ export function validateCodexEngineering(value, options = {}) {
86
+ if (!isRecord(value)) fail('invalid');
87
+ const keys = Object.keys(value).sort().join(',');
88
+ if (keys !== 'agents,schemaVersion,skillsRoot') fail('invalid');
89
+ if (value.schemaVersion !== SCHEMA_VERSION) fail('schema');
90
+ const skillsRoot = value.skillsRoot;
91
+ if (!isCleanAbsolutePath(skillsRoot)) fail('path');
92
+ const skills = /** @type {string} */ (skillsRoot);
93
+ if (basename(skills) !== SKILLS_DIRECTORY) fail('path');
94
+ const base = dirname(skills);
95
+ if (basename(base) !== PACK_DIRECTORY) fail('path');
96
+ if (options.stateDir !== undefined) {
97
+ const launch = dirname(base);
98
+ if (
99
+ !CODEX_LAUNCH_DIRECTORY.test(basename(launch)) ||
100
+ dirname(launch) !== join(resolve(options.stateDir), RUNTIME_DIRECTORY)
101
+ )
102
+ fail('path');
103
+ }
104
+ if (!Array.isArray(value.agents) || value.agents.length > MAX_AGENTS) fail('agents');
105
+ const seen = new Set();
106
+ /** @type {CodexAgentRole[]} */
107
+ const agents = [];
108
+ for (const agent of value.agents) {
109
+ if (!isRecord(agent) || Object.keys(agent).sort().join(',') !== 'configFile,description,name')
110
+ fail('agents');
111
+ const { name, description, configFile } = agent;
112
+ if (typeof name !== 'string' || !AGENT_NAME.test(name) || seen.has(name)) fail('agents');
113
+ if (
114
+ typeof description !== 'string' ||
115
+ description.trim().length === 0 ||
116
+ description.length > MAX_AGENT_DESCRIPTION_LENGTH ||
117
+ CONTROL_CHARACTERS.test(description)
118
+ )
119
+ fail('agents');
120
+ if (configFile !== join(base, CODEX_AGENTS_DIRECTORY, `${name}.toml`)) fail('agents');
121
+ seen.add(name);
122
+ agents.push({ name, description, configFile });
123
+ }
124
+ return { schemaVersion: SCHEMA_VERSION, skillsRoot: skills, agents };
125
+ }
126
+
127
+ /**
128
+ * Parse the monitor's environment value; null when absent.
129
+ * @param {string | undefined} raw
130
+ * @param {{ stateDir?: string }} [options]
131
+ * @returns {CodexEngineering | null}
132
+ */
133
+ export function parseCodexEngineering(raw, options = {}) {
134
+ if (raw === undefined || raw === '') return null;
135
+ if (Buffer.byteLength(raw, 'utf8') > MAX_SPEC_BYTES) fail('too_large');
136
+ let value;
137
+ try {
138
+ value = JSON.parse(raw);
139
+ } catch {
140
+ fail('invalid');
141
+ }
142
+ return validateCodexEngineering(value, options);
143
+ }
144
+
145
+ /**
146
+ * A TOML basic string. JSON escapes are TOML escapes; DEL is escaped too.
147
+ * @param {string} value
148
+ */
149
+ export function tomlBasicString(value) {
150
+ return JSON.stringify(value).replace(/\u007f/gu, '\\u007F');
151
+ }
152
+
153
+ /**
154
+ * Session-only `-c` overrides for the owned app-server, one role per agent.
155
+ * @param {CodexEngineering} engineering
156
+ * @returns {string[]}
157
+ */
158
+ export function codexEngineeringConfigArgs(engineering) {
159
+ return engineering.agents.flatMap((agent) => [
160
+ '-c',
161
+ `agents.${agent.name}.description=${tomlBasicString(agent.description)}`,
162
+ '-c',
163
+ `agents.${agent.name}.config_file=${tomlBasicString(agent.configFile)}`,
164
+ ]);
165
+ }
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "version": 3,
3
- "native": "0.164.0",
3
+ "native": "0.166.0",
4
4
  "consumed_pagination": {
5
5
  "method": "thread/turns/list",
6
6
  "request_schema": "v2/ThreadTurnsListParams.json",
7
7
  "response_schema": "v2/ThreadTurnsListResponse.json",
8
8
  "request_schema_sha256": "29717980579b77eb4c7cbd1118dd238fcb3e010f3ef5236d74bd4e4f6e02c005",
9
- "response_schema_sha256": "f46dddf14b7b6e8e484cb998a7d0b2efa3250167b9f2c366b83b22fe494c250f",
10
- "graph_sha256": "20ba733654372954440b0cbee2964230934d064b9c2c3ee3c4ed850b08f7e370",
9
+ "response_schema_sha256": "53d96dae44edcecee02d8dcce5645800a52a62444f288ff48376e99e506561c6",
10
+ "graph_sha256": "a9008170cbf190054a75f4a539db7fe271e30cf85a157ad27e2dc2192785f311",
11
11
  "ordering": "asc",
12
12
  "items_view": "full"
13
13
  },
@@ -18,7 +18,7 @@
18
18
  },
19
19
  "v2/ThreadTurnsListResponse.json": {
20
20
  "methods": null,
21
- "sha256": "f46dddf14b7b6e8e484cb998a7d0b2efa3250167b9f2c366b83b22fe494c250f"
21
+ "sha256": "53d96dae44edcecee02d8dcce5645800a52a62444f288ff48376e99e506561c6"
22
22
  },
23
23
  "ClientRequest.json": {
24
24
  "methods": [
@@ -39,7 +39,7 @@
39
39
  "config/read",
40
40
  "account/read"
41
41
  ],
42
- "sha256": "415beba5414aeb1af34954de5c3d76c0f5a1c78f30f0a51cb291c471e920b365"
42
+ "sha256": "950bcefcb938bdf04b84305fdcf6767b05db782a0853ef1356fe05d607b0f5b3"
43
43
  },
44
44
  "ClientNotification.json": {
45
45
  "methods": ["initialized"],
@@ -78,7 +78,7 @@
78
78
  "thread/compacted",
79
79
  "warning"
80
80
  ],
81
- "sha256": "590a474f19639e9c1b57238354c89ab0ef5f9d4022561ba2ed5f286cdf254181"
81
+ "sha256": "7f739a3a39a248692147f1a5b2212f440d36350bf2bcca0a5393abd32c188bdf"
82
82
  },
83
83
  "JSONRPCResponse.json": {
84
84
  "methods": null,
@@ -106,7 +106,7 @@
106
106
  },
107
107
  "v2/ThreadForkResponse.json": {
108
108
  "methods": null,
109
- "sha256": "b1e26ab55f9fcbe108d325491d29678040d0776953093626fbcd9608593df31c"
109
+ "sha256": "36af2650a2f2fddd081dd6cb92a91632d0fc12e819fb47ceadcaf238990bec1e"
110
110
  },
111
111
  "v2/ThreadInjectItemsResponse.json": {
112
112
  "methods": null,
@@ -114,15 +114,15 @@
114
114
  },
115
115
  "v2/ThreadReadResponse.json": {
116
116
  "methods": null,
117
- "sha256": "2de20539e09dd7110bd5b705f519288329bacc162d1c14c0c4af33ff27085e24"
117
+ "sha256": "136c873857d2ba0e1aa0836d96ec8d81bfc30a9209e058226e910e0179563e6b"
118
118
  },
119
119
  "v2/ThreadResumeResponse.json": {
120
120
  "methods": null,
121
- "sha256": "bf6130a2dd9494a878e406f2d13535930ebc56f1a66cc1f597528537652a6a65"
121
+ "sha256": "ea37ce77b7a1b2fff78191dac117013ef817cfe1f0ab04f95d1bdc847ceacbb9"
122
122
  },
123
123
  "v2/ThreadStartResponse.json": {
124
124
  "methods": null,
125
- "sha256": "b1e26ab55f9fcbe108d325491d29678040d0776953093626fbcd9608593df31c"
125
+ "sha256": "36af2650a2f2fddd081dd6cb92a91632d0fc12e819fb47ceadcaf238990bec1e"
126
126
  }
127
127
  },
128
128
  "requiredClientFlags": ["app-server", "--listen", "stdio://"],
@@ -0,0 +1,10 @@
1
+ {
2
+ "schema_version": 1,
3
+ "keys": [
4
+ {
5
+ "key_id": "c197814f9e4884ac",
6
+ "x": "Oict0CKYWwgmFovl3TDPJUJ3C4do9Nu6xXU6m4PPOQc",
7
+ "created": "2026-11-02"
8
+ }
9
+ ]
10
+ }