@aiwg/cli 2026.11.3 → 2026.11.5

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 (169) hide show
  1. package/agentic/code/addons/aiwg-hooks/canonical/aiwg-prompt-discovery.yaml +3 -2
  2. package/agentic/code/addons/aiwg-hooks/hooks/aiwg-prompt-discovery.cjs +12 -9
  3. package/agentic/code/addons/aiwg-utils/rules/anti-laziness.md +2 -0
  4. package/agentic/code/addons/composition-engine/lib/runtime.mjs +5 -26
  5. package/agentic/code/addons/composition-engine/schemas/flow-graph.schema.json +22 -0
  6. package/agentic/code/providers/capability-matrix.yaml +85 -18
  7. package/agentic/code/providers/model-capabilities.v1.json +35 -27
  8. package/dist/src/a2a/hitl-authorization.js +46 -0
  9. package/dist/src/a2a/hitl-driver.js +5 -5
  10. package/dist/src/artifacts/browser-export.js +2 -0
  11. package/dist/src/artifacts/framework-source-digest.js +1 -1
  12. package/dist/src/artifacts/index-builder.js +9 -27
  13. package/dist/src/artifacts/index-capability.js +24 -0
  14. package/dist/src/artifacts/query-engine-discover-output.js +8 -3
  15. package/dist/src/artifacts/query-engine-rules.js +29 -11
  16. package/dist/src/artifacts/query-engine-scoring.js +5 -5
  17. package/dist/src/artifacts/query-engine-show-card.js +5 -1
  18. package/dist/src/artifacts/query-engine-show-load.js +1 -1
  19. package/dist/src/artifacts/query-engine-show.js +3 -3
  20. package/dist/src/artifacts/query-engine-templates.js +10 -4
  21. package/dist/src/artifacts/query-engine-verbose.js +18 -4
  22. package/dist/src/artifacts/relations-builder.js +1 -0
  23. package/dist/src/artifacts/types.js +1 -1
  24. package/dist/src/cli/handlers/checkpoint-handoff.js +2 -1
  25. package/dist/src/cli/handlers/guided-setup.js +3 -1
  26. package/dist/src/cli/handlers/refresh-managed-deployment.js +17 -5
  27. package/dist/src/cli/handlers/rules.js +1 -1
  28. package/dist/src/cli/handlers/script-runner.js +7 -4
  29. package/dist/src/cli/handlers/sessions.js +1 -1
  30. package/dist/src/cli/handlers/steward-format.js +12 -0
  31. package/dist/src/cli/handlers/steward.js +1 -1
  32. package/dist/src/cli/handlers/use.js +14 -6
  33. package/dist/src/cli/handlers/utility-doctor.js +9 -2
  34. package/dist/src/cli/handlers/workspace.js +1 -1
  35. package/dist/src/cli/services/deployment-probe-scope.js +40 -0
  36. package/dist/src/cli/services/deployment-verification.js +4 -5
  37. package/dist/src/config/aiwg-config.js +6 -0
  38. package/dist/src/config/authorization-cli.js +61 -3
  39. package/dist/src/config/cli-help.js +1 -1
  40. package/dist/src/config/cli.js +4 -2
  41. package/dist/src/config/host-resource-runtime.mjs +1 -1
  42. package/dist/src/config/user-registry.js +9 -1
  43. package/dist/src/config/worker-owner-lock.js +90 -10
  44. package/dist/src/decision/graph-flow-adapter.js +1 -1
  45. package/dist/src/effects/authorization-grant.js +50 -0
  46. package/dist/src/effects/authorization-store.js +130 -0
  47. package/dist/src/effects/index.js +2 -0
  48. package/dist/src/effects/ledger.js +1 -0
  49. package/dist/src/effects/lifecycle.js +1 -1
  50. package/dist/src/effects/reader.js +4 -0
  51. package/dist/src/effects/records.js +4 -0
  52. package/dist/src/effects/schema.js +2 -0
  53. package/dist/src/extensions/claude-hooks-installer.js +7 -7
  54. package/dist/src/extensions/manifest.js +6 -0
  55. package/dist/src/extensions/muse-managed-hooks.js +11 -0
  56. package/dist/src/extensions/project-local-discovery.js +21 -1
  57. package/dist/src/extensions/project-local-scaffold.js +19 -7
  58. package/dist/src/extensions/user-hook-diagnostics.js +32 -0
  59. package/dist/src/extensions/verified-hook-command.js +32 -0
  60. package/dist/src/lint/rule-conflicts.js +52 -0
  61. package/dist/src/lint/runner.js +3 -0
  62. package/dist/src/mcp/cli.mjs +3 -1
  63. package/dist/src/mcp/elicitation.mjs +30 -0
  64. package/dist/src/mcp/grok-build-config.mjs +1 -1
  65. package/dist/src/mcp/muse-native-config.mjs +1 -0
  66. package/dist/src/mcp/server.mjs +2 -0
  67. package/dist/src/mcp/tools/authorization.mjs +78 -0
  68. package/dist/src/models/factory-models.js +144 -0
  69. package/dist/src/models/model-capabilities.v1.json +35 -27
  70. package/dist/src/models/model-discovery.js +7 -3
  71. package/dist/src/models/worker-installation.d.mts +2 -0
  72. package/dist/src/models/worker-installation.mjs +11 -2
  73. package/dist/src/models/worker-invocation-policy.js +25 -1
  74. package/dist/src/models/wrapper-enforcement.js +1 -1
  75. package/dist/src/policy/authorization-capture.js +64 -0
  76. package/dist/src/policy/authorization-operations.js +108 -0
  77. package/dist/src/policy/hitl-check.js +3 -2
  78. package/dist/src/policy/hitl-consume.js +14 -0
  79. package/dist/src/policy/hitl-durable-store.js +60 -0
  80. package/dist/src/policy/hitl-durable.js +60 -0
  81. package/dist/src/policy/hitl-receipt.js +5 -0
  82. package/dist/src/policy/hitl.js +44 -6
  83. package/dist/src/policy/repo-access.js +3 -1
  84. package/dist/src/process/bounded-child-process.mjs +49 -39
  85. package/dist/src/providers/capability-matrix.yaml +85 -18
  86. package/dist/src/providers/deployment-ownership.d.mts +1 -0
  87. package/dist/src/providers/deployment-ownership.mjs +29 -3
  88. package/dist/src/providers/deployment-preservation.mjs +44 -3
  89. package/dist/src/providers/grok-build-acp.js +13 -5
  90. package/dist/src/providers/grok-build-dispatch.js +35 -2
  91. package/dist/src/providers/grok-build-headless.js +171 -77
  92. package/dist/src/providers/grok-build-inspect.js +1 -0
  93. package/dist/src/providers/grok-build-paths.js +2 -0
  94. package/dist/src/providers/muse-paths.js +4 -2
  95. package/dist/src/providers/provider-context-contracts.js +12 -4
  96. package/dist/src/providers/provider-definition-schema.js +6 -0
  97. package/dist/src/providers/provider-seeds-1.js +3 -3
  98. package/dist/src/providers/provider-seeds-2.js +6 -4
  99. package/dist/src/providers/provider-seeds-3.js +6 -6
  100. package/dist/src/rules/activation.d.mts +2 -0
  101. package/dist/src/rules/activation.mjs +16 -7
  102. package/dist/src/rules/inline-budget.d.mts +2 -1
  103. package/dist/src/rules/inline-budget.mjs +4 -2
  104. package/dist/src/rules/inventory.js +3 -0
  105. package/dist/src/rules/precedence.d.mts +6 -0
  106. package/dist/src/rules/precedence.mjs +49 -0
  107. package/dist/src/rules/project-precedence.js +73 -0
  108. package/dist/src/rules/rule-frontmatter.schema.json +15 -0
  109. package/dist/src/serve/a2a-terminal-observer.js +12 -3
  110. package/dist/src/serve/mission-hitl.js +20 -1
  111. package/dist/src/serve/worker-stdin-frame.mjs +1 -1
  112. package/dist/src/sessions/adapters/grok-build-fallback.js +33 -0
  113. package/dist/src/sessions/adapters/grok-build-native-records.js +134 -0
  114. package/dist/src/sessions/adapters/grok-build-native.js +237 -98
  115. package/dist/src/sessions/adapters/grok-build.js +95 -32
  116. package/dist/src/sessions/grok-build-cli-output.js +113 -0
  117. package/dist/src/sessions/grok-build-cli.js +4 -28
  118. package/dist/src/sessions/normalization.js +1 -1
  119. package/dist/src/smiths/context-pipeline/bridge-ownership.js +4 -3
  120. package/dist/src/smiths/context-pipeline/finalization.js +5 -0
  121. package/dist/src/smiths/context-pipeline/generator.js +1 -1
  122. package/dist/src/smiths/context-pipeline/workspace-bootstrap.js +20 -17
  123. package/dist/src/smiths/context-pipeline/workspace-doctor.js +6 -1
  124. package/dist/src/smiths/context-pipeline/workspace-document.js +6 -0
  125. package/dist/src/smiths/context-pipeline/workspace-migration.js +2 -12
  126. package/dist/src/smiths/hook-bridge/codex-translator.js +11 -14
  127. package/dist/src/smiths/hook-bridge/codex-trust.js +7 -2
  128. package/dist/src/smiths/hook-bridge/copilot-translator.js +2 -1
  129. package/dist/src/smiths/hook-bridge/factory-trust.js +2 -2
  130. package/dist/src/smiths/hook-bridge/grok-build-translator.js +3 -1
  131. package/dist/src/smiths/hook-bridge/hermes-prompt-discovery.js +81 -0
  132. package/dist/src/smiths/hook-bridge/hermes-translator.js +5 -3
  133. package/dist/src/smiths/hook-bridge/hermes-trust.js +65 -0
  134. package/dist/src/smiths/hook-bridge/index.js +3 -1
  135. package/dist/src/smiths/hook-bridge/prompt-discovery-gaps.js +3 -2
  136. package/package.json +7 -1
  137. package/tools/agents/deploy-agents.mjs +9 -8
  138. package/tools/agents/deploy-options.mjs +3 -0
  139. package/tools/agents/providers/base-frontmatter.mjs +3 -2
  140. package/tools/agents/providers/base-inventory.mjs +3 -1
  141. package/tools/agents/providers/base-kernel-skills.mjs +11 -5
  142. package/tools/agents/providers/claude-post-deploy.mjs +1 -1
  143. package/tools/agents/providers/codex-post-deploy.mjs +1 -1
  144. package/tools/agents/providers/generic.mjs +66 -0
  145. package/tools/agents/providers/grok-build.mjs +34 -41
  146. package/tools/agents/providers/model-wrapper.mjs +2 -5
  147. package/tools/agents/providers/muse-hooks.mjs +13 -11
  148. package/tools/agents/providers/muse-prompt-discovery.mjs +5 -1
  149. package/tools/agents/providers/muse.mjs +2 -1
  150. package/tools/agents/providers/openclaw.mjs +2 -1
  151. package/tools/agents/providers/rule-deployment-commit.mjs +3 -0
  152. package/tools/agents/providers/rule-deployment-prepare.mjs +7 -5
  153. package/tools/agents/providers/rule-deployment-state.mjs +14 -6
  154. package/tools/agents/providers/rule-projection.mjs +39 -4
  155. package/tools/agents/providers/rule-startup.mjs +11 -10
  156. package/tools/agents/providers/skill-copy-prune.mjs +12 -0
  157. package/tools/agents/providers/staged-directory-reference.mjs +14 -0
  158. package/tools/agents/providers/stale-artifact-prune.mjs +24 -10
  159. package/tools/agents/providers/user-hooks.mjs +26 -0
  160. package/tools/cli/authorization-health.mjs +20 -0
  161. package/tools/cli/workspace-status.mjs +7 -0
  162. package/tools/commands/deploy-prompts-codex.mjs +15 -1
  163. package/tools/ralph-external/lib/claude-adapter.mjs +2 -0
  164. package/tools/ralph-external/lib/factory-adapter.mjs +6 -2
  165. package/tools/ralph-external/lib/worker-inputs.mjs +20 -1
  166. package/tools/ralph-external/lib/worker-isolation.mjs +1 -0
  167. package/tools/ralph-external/lib/worker-termination.mjs +21 -12
  168. package/tools/ralph-external/session-launcher.mjs +22 -17
  169. package/vscode-extension/schemas/aiwg.config.v1.json +20 -0
@@ -1,12 +1,14 @@
1
- // Native Grok Build session-store reader (synthetic schema v1; real stores never inspected).
2
- import { opendir, readFile } from 'node:fs/promises';
3
- import { dirname, resolve } from 'node:path';
1
+ // Bounded native projection pinned to the captured Grok Build 1.0.77 store.
2
+ import { createHash } from 'node:crypto';
3
+ import { lstat, opendir, readFile } from 'node:fs/promises';
4
+ import { basename, dirname, isAbsolute, parse, resolve } from 'node:path';
4
5
  import { z } from 'zod';
5
- import { integer, number } from '../../schema/zod-validation.mjs';
6
+ import { number } from '../../schema/zod-validation.mjs';
6
7
  import { schemaIssueDetail, schemaRejectionDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
7
8
  import { matchSessionWorkspace } from '../workspace-matching.js';
8
9
  import { authorizeSourceFile } from '../policy.js';
9
- import { streamBoundedJsonLines, } from '../readers.js';
10
+ import { streamBoundedJsonLines, readBoundedText, } from '../readers.js';
11
+ import { nativeDrift, parseNativeSummary, parseNativeCompactionCheckpoint, projectNativeLine, nativeProjectionRecord, projectNativeUpdate } from './grok-build-native-records.js';
10
12
  export const GROK_BUILD_NATIVE_SCHEMA_VERSION = '1.0.0';
11
13
  export const GROK_BUILD_NATIVE_SCHEMA_MAJOR = 1;
12
14
  export const GROK_BUILD_NATIVE_LOCATOR_CLASS = 'grok-build-native-chat-history';
@@ -16,18 +18,19 @@ export const GROK_BUILD_ACTIVE_FRESHNESS_MS = 120_000;
16
18
  export const GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES = 10_000;
17
19
  const ACTIVE_SESSIONS_MAX_BYTES = 1024 * 1024;
18
20
  export function grokBuildNativeEnabled() {
19
- return process.env.AIWG_GROK_BUILD_NATIVE_EXPERIMENTAL === '1';
21
+ return process.env.AIWG_GROK_BUILD_NATIVE_EXPERIMENTAL === '1'
22
+ && process.env.AIWG_GROK_BUILD_NATIVE_VERSION === '1.0.77';
20
23
  }
21
24
  /** One availability message for native readers, discovery and CLI capability reports. */
22
25
  export function grokBuildNativeAvailability() {
23
26
  const enabled = grokBuildNativeEnabled();
24
27
  return {
25
28
  reasonCode: enabled ? 'GROK_BUILD_NATIVE_EXPERIMENTAL_ENABLED' : 'GROK_BUILD_NATIVE_EXPERIMENTAL_DISABLED',
26
- remediation: `Grok Build native ingestion is experimental and ${enabled ? 'enabled but' : 'disabled by default because it is'} `
27
- + 'unqualified: no released-binary schema or version range is qualified. '
28
- + 'AIWG_GROK_BUILD_NATIVE_EXPERIMENTAL=1 opts in to synthetic v1 chat_history.jsonl and active_sessions.json only; '
29
- + 'authorize the sessions root separately with --grok-root and the optional registry file with --grok-active-sessions. '
30
- + 'Use `grok export <session-id> <session-id>.md` and import the authorized Markdown file for the documented CLI path.',
29
+ remediation: `Grok Build native ingestion is experimental and ${enabled ? 'enabled for the captured subset; other scenarios remain' : 'disabled and'} unqualified. `
30
+ + 'AIWG_GROK_BUILD_NATIVE_EXPERIMENTAL=1 and AIWG_GROK_BUILD_NATIVE_VERSION=1.0.77 are both required; '
31
+ + 'only exact 1.0.77 text/tool records with chat_format_version 1 are supported. '
32
+ + 'Authorize the sessions root separately with --grok-root. '
33
+ + 'Unknown versions or schemas must fall back to `grok export <session-id> <session-id>.md` and import the authorized Markdown file.',
31
34
  };
32
35
  }
33
36
  export function assertGrokBuildNativeEnabled() {
@@ -36,20 +39,6 @@ export function assertGrokBuildNativeEnabled() {
36
39
  }
37
40
  }
38
41
  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
39
- // Synthetic native record shape (v1): one JSON object per line. Real
40
- // chat_history.jsonl schemas are unqualified (real stores are never read),
41
- // so any record outside this shape fails closed with SCHEMA_DRIFT.
42
- const NativeRecordSchema = z.looseObject({
43
- schemaVersion: z.union([z.string(), z.number()]),
44
- sessionId: z.string().regex(UUID),
45
- seq: integer().nonnegative(),
46
- role: z.enum(['user', 'assistant', 'tool']),
47
- content: z.string(),
48
- timestamp: number().optional(),
49
- toolName: z.string().min(1).optional(),
50
- toolCallId: z.string().optional(),
51
- id: z.string().min(1).optional(),
52
- });
53
42
  const ActiveSessionsSchema = z.looseObject({
54
43
  schemaVersion: z.union([z.string(), z.number()]),
55
44
  sessions: z.array(z.looseObject({
@@ -80,6 +69,7 @@ export function grokBuildNativeSessionId(locator) {
80
69
  /** Enumerate documented `<root>/<url-encoded cwd>/<id>/chat_history.jsonl` paths. */
81
70
  export async function* discoverGrokBuildNativeChatHistories(root, maxFiles = GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES) {
82
71
  assertGrokBuildNativeEnabled();
72
+ await assertSafeNativeRoot(root);
83
73
  const resolved = resolve(root);
84
74
  let workspaces;
85
75
  try {
@@ -147,83 +137,235 @@ export async function grokBuildSourceWorkspaceMatch(locator, workspacePath) {
147
137
  }
148
138
  export async function readGrokBuildNativeChatHistory(source, limits) {
149
139
  assertGrokBuildNativeEnabled();
150
- const sessionId = grokBuildNativeSessionId(source.locator);
151
- if (source.locatorClass !== GROK_BUILD_NATIVE_LOCATOR_CLASS || !sessionId) {
152
- throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build native source must be an explicitly authorized chat_history.jsonl path');
140
+ const { sessionId, cwd } = await authorizeGrokBuildNativeSource(source);
141
+ try {
142
+ await rejectNativeSymlinks(resolve(dirname(source.locator), 'summary.json'));
153
143
  }
154
- await authorizeSourceFile({
155
- selectedPath: source.locator,
156
- allowedRoots: source.authorizedScope.allowedRoots,
157
- });
158
- const input = await streamBoundedJsonLines({
159
- selectedPath: source.locator,
160
- allowedRoots: source.authorizedScope.allowedRoots,
161
- }, { consistency: 'provisional', limits });
144
+ catch (error) {
145
+ if (error.code === 'ENOENT')
146
+ nativeDrift();
147
+ throw error;
148
+ }
149
+ const summary = await readBoundedText({
150
+ selectedPath: resolve(dirname(source.locator), 'summary.json'), allowedRoots: source.authorizedScope.allowedRoots,
151
+ }, limits);
152
+ let metadata;
153
+ try {
154
+ metadata = JSON.parse(summary.value);
155
+ }
156
+ catch {
157
+ nativeDrift();
158
+ }
159
+ const sessionMetadata = parseNativeSummary(metadata, sessionId, cwd);
160
+ const subagents = await readNativeSubagents(source, sessionId, limits);
161
+ if (subagents.length)
162
+ sessionMetadata.lineage = { ...sessionMetadata.lineage, subagents };
163
+ const input = await streamBoundedJsonLines({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'complete', limits });
162
164
  const records = [];
163
- let lastSeq = -1;
165
+ const calls = new Set();
166
+ const results = new Set();
167
+ let promptIndex = -1;
168
+ let compacted = false;
164
169
  for await (const line of input) {
165
- const parsed = NativeRecordSchema.safeParse(line.value);
166
- if (!parsed.success) {
167
- throw new SessionContractError('SCHEMA_DRIFT', 'unrecognized Grok Build native chat_history.jsonl record', schemaRejectionDetail(parsed.error));
170
+ if (line.value?.synthetic_reason === 'compaction_meta')
171
+ compacted = true;
172
+ const projected = projectNativeLine(line, cwd, sessionMetadata);
173
+ const raw = line.value;
174
+ if (raw.prompt_index !== undefined) {
175
+ if (raw.prompt_index <= promptIndex)
176
+ nativeDrift();
177
+ promptIndex = raw.prompt_index;
178
+ }
179
+ for (const entry of projected) {
180
+ const { kind, toolCallId } = entry.record;
181
+ if (kind === 'tool-call' && toolCallId) {
182
+ if (calls.has(toolCallId))
183
+ nativeDrift();
184
+ calls.add(toolCallId);
185
+ }
186
+ if (kind === 'tool-result' && toolCallId) {
187
+ if (!calls.has(toolCallId) || results.has(toolCallId))
188
+ nativeDrift();
189
+ results.add(toolCallId);
190
+ }
191
+ records.push(entry);
192
+ }
193
+ }
194
+ const updates = await readNativeUpdates(source, sessionId, cwd, sessionMetadata, records, compacted, limits);
195
+ if (updates)
196
+ return { records: updates, incompleteTail: false };
197
+ if (records.length === 0)
198
+ throw new SessionContractError('MALFORMED_SOURCE', 'Grok Build native chat history is empty; use `grok export <session-id> <session-id>.md`.');
199
+ return { records, incompleteTail: input.incompleteTail };
200
+ }
201
+ /** Read optional siblings with the same bounded authorization and symlink policy. */
202
+ async function nativeSibling(source, path, limits) {
203
+ try {
204
+ await rejectNativeSymlinks(path);
205
+ }
206
+ catch (error) {
207
+ if (error.code === 'ENOENT')
208
+ return undefined;
209
+ throw error;
210
+ }
211
+ const input = await readBoundedText({ selectedPath: path, allowedRoots: source.authorizedScope.allowedRoots }, limits);
212
+ try {
213
+ return JSON.parse(input.value);
214
+ }
215
+ catch {
216
+ nativeDrift();
217
+ }
218
+ }
219
+ const subagentSchema = z.looseObject({
220
+ subagent_id: z.string().uuid(), parent_session_id: z.string().uuid().optional(),
221
+ child_session_id: z.string().uuid().optional(), status: z.enum(['running', 'completed', 'cancelled', 'failed']).optional(),
222
+ });
223
+ const outputSchema = z.strictObject({ schema_version: z.literal(1), output: z.string() });
224
+ async function readNativeSubagents(source, sessionId, limits) {
225
+ const path = resolve(dirname(source.locator), 'subagents');
226
+ try {
227
+ await rejectNativeSymlinks(path);
228
+ }
229
+ catch (error) {
230
+ if (error.code === 'ENOENT')
231
+ return [];
232
+ throw error;
233
+ }
234
+ const directory = await opendir(path);
235
+ const names = [];
236
+ for await (const entry of directory) {
237
+ if (!UUID.test(entry.name))
238
+ nativeDrift();
239
+ if (entry.isSymbolicLink())
240
+ throw new SessionContractError('SOURCE_SYMLINK', 'Grok Build subagent paths cannot contain symlinks');
241
+ if (!entry.isDirectory())
242
+ nativeDrift();
243
+ if (names.length >= (limits?.maxRecords ?? GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES)) {
244
+ throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Grok Build subagent metadata exceeds maxRecords');
168
245
  }
169
- assertSupportedSchemaMajor(declaredSchema(parsed.data.schemaVersion), GROK_BUILD_NATIVE_SCHEMA_MAJOR);
170
- if (parsed.data.sessionId.toLowerCase() !== sessionId) {
171
- throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build native record session does not match its session directory', schemaIssueDetail('sessionId'));
246
+ names.push(entry.name);
247
+ }
248
+ const subagents = [];
249
+ for (const name of names.sort()) {
250
+ const meta = subagentSchema.safeParse(await nativeSibling(source, resolve(path, name, 'meta.json'), limits));
251
+ if (!meta.success || meta.data.subagent_id.toLowerCase() !== name.toLowerCase()
252
+ || (meta.data.parent_session_id !== undefined && meta.data.parent_session_id.toLowerCase() !== sessionId)
253
+ || meta.data.child_session_id?.toLowerCase() === sessionId)
254
+ nativeDrift();
255
+ const value = await nativeSibling(source, resolve(path, name, 'output.json'), limits);
256
+ const output = value === undefined ? undefined : outputSchema.safeParse(value);
257
+ if (output && !output.success)
258
+ nativeDrift();
259
+ subagents.push({ subagentId: meta.data.subagent_id.toLowerCase(),
260
+ ...(meta.data.parent_session_id ? { parentSessionId: meta.data.parent_session_id.toLowerCase() } : {}),
261
+ ...(meta.data.child_session_id ? { childSessionId: meta.data.child_session_id.toLowerCase() } : {}),
262
+ ...(meta.data.status ? { status: meta.data.status } : {}),
263
+ ...(output?.success ? { output: output.data.output } : {}) });
264
+ }
265
+ return subagents;
266
+ }
267
+ async function readNativeUpdates(source, sessionId, cwd, metadata, history, compacted, limits) {
268
+ const path = resolve(dirname(source.locator), 'updates.jsonl');
269
+ try {
270
+ await rejectNativeSymlinks(path);
271
+ }
272
+ catch (error) {
273
+ if (error.code === 'ENOENT') {
274
+ // A compacted history alone cannot recover the removed turns.
275
+ if (compacted)
276
+ nativeDrift();
277
+ return null;
172
278
  }
173
- if (parsed.data.seq <= lastSeq) {
174
- throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build native chat history sequence is not strictly increasing', schemaIssueDetail('seq'));
279
+ throw error;
280
+ }
281
+ const input = await streamBoundedJsonLines({ selectedPath: path, allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'complete', limits });
282
+ const records = [];
283
+ let hasTools = history.some(entry => entry.record.kind !== 'message');
284
+ let hasCompaction = false;
285
+ let nextPromptIndex = 0;
286
+ let checkpoint;
287
+ const checkpointIds = new Set();
288
+ for await (const line of input) {
289
+ const entry = projectNativeUpdate(line, sessionId, cwd, metadata);
290
+ const update = line.value.params.update;
291
+ const type = update.sessionUpdate;
292
+ if (type === 'compaction_checkpoint') {
293
+ const parsed = parseNativeCompactionCheckpoint(update);
294
+ if (checkpoint || checkpointIds.has(parsed.checkpointId) || parsed.promptIndexAtCompaction !== nextPromptIndex)
295
+ nativeDrift();
296
+ checkpoint = parsed;
297
+ checkpointIds.add(parsed.checkpointId);
175
298
  }
176
- lastSeq = parsed.data.seq;
177
- if (parsed.data.role === 'tool' && !parsed.data.toolName) {
178
- throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build native tool record is missing its tool name', schemaIssueDetail('toolName'));
299
+ if (type === 'user_message_chunk') {
300
+ const meta = line.value.params.update._meta;
301
+ if (!meta?.hostTurn) {
302
+ if (meta?.promptIndex !== nextPromptIndex)
303
+ nativeDrift();
304
+ nextPromptIndex += 1;
305
+ }
306
+ }
307
+ if (type === 'tool_call' || type === 'tool_call_update')
308
+ hasTools = true;
309
+ if (entry) {
310
+ if (entry.record.kind === 'compaction') {
311
+ hasCompaction = true;
312
+ if (checkpoint) {
313
+ if (checkpoint.promptIndexAtCompaction !== nextPromptIndex)
314
+ nativeDrift();
315
+ entry.record.compaction = { ...entry.record.compaction, ...checkpoint };
316
+ checkpoint = undefined;
317
+ }
318
+ }
319
+ records.push(entry);
179
320
  }
180
- records.push({ record: parsed.data, line });
181
321
  }
182
- if (records.length === 0) {
183
- throw new SessionContractError('MALFORMED_SOURCE', 'Grok Build native chat history is empty', schemaIssueDetail('<root>'));
322
+ // Compacted tool histories need a qualified update-tool projection; never drop calls.
323
+ if (checkpoint || (compacted && (!hasCompaction || nextPromptIndex === 0)) || (hasTools && (compacted || hasCompaction)))
324
+ nativeDrift();
325
+ return hasTools || !records.length ? null : records;
326
+ }
327
+ /** Hash only stable source evidence, excluding mutable summary and subagent status. */
328
+ export function nativeRecordPrefixes(records) {
329
+ const hash = createHash('sha256');
330
+ const prefixes = [hash.copy().digest('hex')];
331
+ for (const { record, line } of records) {
332
+ hash.update(JSON.stringify([record.sequence, record.kind, record.acquisition, line.value,
333
+ ...(record.compaction?.checkpointId ? [record.compaction] : [])]) + '\n');
334
+ prefixes.push(hash.copy().digest('hex'));
184
335
  }
185
- return { records, incompleteTail: input.incompleteTail };
336
+ return prefixes;
186
337
  }
187
- export function toGrokBuildNativeRecord(sessionId, entry) {
188
- const { record, line } = entry;
189
- const occurredAt = timestamp(record.timestamp);
190
- const nativeEventId = record.id ?? `${sessionId}:${record.seq}`;
191
- const common = {
192
- lifecycle: 'unknown-at-import',
193
- provenance: {
194
- product: 'grok-build',
195
- acquisition: GROK_BUILD_NATIVE_LOCATOR_CLASS,
196
- sourceSchema: GROK_BUILD_NATIVE_SCHEMA_VERSION,
197
- nativeStoreInspected: true,
198
- },
199
- identity: { nativeSessionIdKnown: true, nativeEventIdKnown: true },
200
- };
201
- if (record.role === 'tool') {
202
- return {
203
- nativeSessionId: sessionId,
204
- nativeEventId,
205
- sequence: line.sequence * 1_000,
206
- kind: 'tool-call',
207
- role: 'tool',
208
- toolName: record.toolName,
209
- toolCallId: record.toolCallId,
210
- occurredAt,
211
- text: record.content,
212
- rawReference: { locatorClass: GROK_BUILD_NATIVE_LOCATOR_CLASS, sequence: line.sequence },
213
- extensions: common,
214
- };
338
+ /** Authorize native identity/path before a caller may use the CLI fallback. */
339
+ export async function authorizeGrokBuildNativeSource(source) {
340
+ const sessionId = grokBuildNativeSessionId(source.locator);
341
+ if (source.locatorClass !== GROK_BUILD_NATIVE_LOCATOR_CLASS || !sessionId
342
+ || basename(source.locator) !== GROK_BUILD_NATIVE_SESSION_FILENAME) {
343
+ throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build native source must be an explicitly authorized chat_history.jsonl path');
344
+ }
345
+ await authorizeSourceFile({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots });
346
+ for (const root of source.authorizedScope.allowedRoots)
347
+ await assertSafeNativeRoot(root);
348
+ await rejectNativeSymlinks(source.locator);
349
+ const cwd = decodeGrokBuildWorkspaceDir(dirname(dirname(source.locator)).split('/').pop() ?? '');
350
+ if (!cwd)
351
+ nativeDrift();
352
+ return { sessionId, cwd };
353
+ }
354
+ export const toGrokBuildNativeRecord = nativeProjectionRecord;
355
+ async function rejectNativeSymlinks(input) {
356
+ let current = resolve(input);
357
+ while (current !== parse(current).root) {
358
+ if ((await lstat(current)).isSymbolicLink())
359
+ throw new SessionContractError('SOURCE_SYMLINK', 'Grok Build native paths cannot contain symlinks');
360
+ current = dirname(current);
215
361
  }
216
- return {
217
- nativeSessionId: sessionId,
218
- nativeEventId,
219
- sequence: line.sequence * 1_000,
220
- kind: 'message',
221
- role: record.role,
222
- occurredAt,
223
- text: record.content,
224
- rawReference: { locatorClass: GROK_BUILD_NATIVE_LOCATOR_CLASS, sequence: line.sequence },
225
- extensions: common,
226
- };
362
+ }
363
+ async function assertSafeNativeRoot(root) {
364
+ if (!isAbsolute(root) || resolve(root) === parse(resolve(root)).root)
365
+ throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build sessions root must be an absolute non-root directory');
366
+ await rejectNativeSymlinks(root);
367
+ if (!(await lstat(root)).isDirectory())
368
+ throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build sessions root must be a directory');
227
369
  }
228
370
  /** Read and validate active_sessions.json (read-only, bounded); throws on misuse. */
229
371
  export async function readGrokBuildActiveRegistry(selectedPath, allowedRoots) {
@@ -276,17 +418,14 @@ export function parseGrokBuildNativeCursor(value) {
276
418
  if (!/^\d+$/.test(value)) {
277
419
  throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Build native cursor', schemaIssueDetail('cursor'));
278
420
  }
279
- return Number(value);
421
+ const cursor = Number(value);
422
+ if (!Number.isSafeInteger(cursor))
423
+ throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Build native cursor', schemaIssueDetail('cursor'));
424
+ return cursor;
280
425
  }
281
426
  function declaredSchema(value) {
282
427
  if (typeof value === 'number')
283
428
  return `${value}.0.0`;
284
429
  return /^\d+$/.test(String(value)) ? `${value}.0.0` : String(value);
285
430
  }
286
- function timestamp(value) {
287
- if (value === undefined || value === null)
288
- return undefined;
289
- const date = new Date(value < 10_000_000_000 ? value * 1_000 : value);
290
- return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
291
- }
292
431
  //# sourceMappingURL=grok-build-native.js.map
@@ -1,8 +1,10 @@
1
+ import { createHash } from 'node:crypto';
1
2
  import { basename, extname } from 'node:path';
3
+ import { canFallbackGrokNative, withGrokCliFallback } from './grok-build-fallback.js';
2
4
  import { SessionContractError, schemaIssueDetail, } from '../contracts.js';
3
5
  import { readBoundedText } from '../readers.js';
4
- import { assertGrokBuildNativeEnabled, discoverGrokBuildNativeChatHistories, GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES, GROK_BUILD_NATIVE_LOCATOR_CLASS, GROK_BUILD_NATIVE_SCHEMA_VERSION, grokBuildNativeSessionId, grokBuildNativeEnabled, parseGrokBuildNativeCursor, readGrokBuildNativeChatHistory, toGrokBuildNativeRecord, } from './grok-build-native.js';
5
- export const GROK_BUILD_ADAPTER_VERSION = '1.0.0';
6
+ import { assertGrokBuildNativeEnabled, discoverGrokBuildNativeChatHistories, GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES, GROK_BUILD_NATIVE_LOCATOR_CLASS, GROK_BUILD_NATIVE_SCHEMA_VERSION, grokBuildNativeSessionId, grokBuildNativeEnabled, parseGrokBuildNativeCursor, nativeRecordPrefixes, readGrokBuildNativeChatHistory, toGrokBuildNativeRecord, } from './grok-build-native.js';
7
+ export const GROK_BUILD_ADAPTER_VERSION = '1.3.0';
6
8
  export const GROK_BUILD_CLI_EXPORT_SCHEMA_VERSION = '1.0.0';
7
9
  export const GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS = 'grok-build-cli-markdown-export';
8
10
  /**
@@ -11,25 +13,29 @@ export const GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS = 'grok-build-cli-markdown-expo
11
13
  * opt-in and an explicitly authorized sessions root (`--grok-root`).
12
14
  *
13
15
  * The public export contract is intentionally lossy. Native reads use the
14
- * synthetic v1 schema in grok-build-native.ts (real stores were never
15
- * inspected); anything outside it fails closed. This adapter never invokes
16
- * `grok export` automatically: CLI export remains operator-selected.
16
+ * captured 1.0.77 projection in grok-build-native.ts; anything outside
17
+ * the observed schema fails closed. Explicit CLI imports supply bounded CLI
18
+ * options to fall back to export; direct API callers may supply the same options.
17
19
  */
18
20
  export class GrokBuildSessionAdapter {
19
21
  limits;
20
22
  maxFiles;
23
+ cliFallback;
21
24
  provider = 'grok-build';
22
25
  adapterVersion = GROK_BUILD_ADAPTER_VERSION;
23
26
  disposition = 'implemented';
27
+ // Compaction rewrites chat history; native cursors validate the retained projection.
28
+ sourceContinuity = 'snapshot';
24
29
  get supportedOperations() {
25
30
  return grokBuildNativeEnabled() ? ['discover', 'inspect', 'stream'] : ['inspect', 'stream'];
26
31
  }
27
32
  get acquisitionModes() {
28
33
  return grokBuildNativeEnabled() ? ['manual-export', 'jsonl'] : ['manual-export'];
29
34
  }
30
- constructor(limits, maxFiles = GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES) {
35
+ constructor(limits, maxFiles = GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES, cliFallback) {
31
36
  this.limits = limits;
32
37
  this.maxFiles = maxFiles;
38
+ this.cliFallback = cliFallback;
33
39
  }
34
40
  async *discover(scope) {
35
41
  assertGrokBuildNativeEnabled();
@@ -42,7 +48,15 @@ export class GrokBuildSessionAdapter {
42
48
  }
43
49
  async inspect(source) {
44
50
  if (source.locatorClass === GROK_BUILD_NATIVE_LOCATOR_CLASS) {
45
- const native = await readGrokBuildNativeChatHistory(source, this.limits);
51
+ let native;
52
+ try {
53
+ native = await readGrokBuildNativeChatHistory(source, this.limits);
54
+ }
55
+ catch (error) {
56
+ if (!canFallbackGrokNative(error, this.cliFallback))
57
+ throw error;
58
+ return withGrokCliFallback(source, this.cliFallback, selected => this.inspect(selected));
59
+ }
46
60
  return {
47
61
  sourceSchemaVersion: GROK_BUILD_NATIVE_SCHEMA_VERSION,
48
62
  consistency: native.incompleteTail ? 'provisional' : 'complete',
@@ -58,14 +72,30 @@ export class GrokBuildSessionAdapter {
58
72
  }
59
73
  async *stream(source, cursor) {
60
74
  if (source.locatorClass === GROK_BUILD_NATIVE_LOCATOR_CLASS) {
61
- // The experimental gate answers first, so a disabled gate never reports a locator error.
62
- assertGrokBuildNativeEnabled();
75
+ if (cursor?.value.startsWith('grok-cli:')) {
76
+ yield* await this.fallbackRecords(source, cursor.value.slice('grok-cli:'.length));
77
+ return;
78
+ }
79
+ let native;
80
+ try {
81
+ native = await readGrokBuildNativeChatHistory(source, this.limits);
82
+ }
83
+ catch (error) {
84
+ if (!canFallbackGrokNative(error, this.cliFallback))
85
+ throw error;
86
+ if (cursor?.value && cursor.value !== '0')
87
+ throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build acquisition changed after a native checkpoint; restart with a separate CLI export source.');
88
+ yield* await this.fallbackRecords(source);
89
+ return;
90
+ }
63
91
  const sessionId = grokBuildNativeSessionId(source.locator);
64
- if (!sessionId) {
65
- throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build native source must be an explicitly authorized chat_history.jsonl path');
92
+ const prefixes = nativeRecordPrefixes(native.records);
93
+ const acquisition = native.records[0]?.record.acquisition === 'grok-build-native-updates' ? 'updates' : 'chat';
94
+ const saved = cursor?.value?.match(/^grok-native:(chat|updates):(\d+):([a-f0-9]{64})$/);
95
+ const start = parseGrokBuildNativeCursor(saved?.[2] ?? cursor?.value);
96
+ if (start > native.records.length || (saved && (saved[1] !== acquisition || saved[3] !== prefixes[start]))) {
97
+ throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build native checkpoint projection changed; use a separate source and `grok export` for review.');
66
98
  }
67
- const native = await readGrokBuildNativeChatHistory(source, this.limits);
68
- const start = parseGrokBuildNativeCursor(cursor?.value);
69
99
  let outputIndex = 0;
70
100
  for (const entry of native.records) {
71
101
  const position = outputIndex;
@@ -73,19 +103,34 @@ export class GrokBuildSessionAdapter {
73
103
  if (position < start)
74
104
  continue;
75
105
  const record = toGrokBuildNativeRecord(sessionId, entry);
76
- record.sourceCursor = String(outputIndex);
106
+ record.sourceCursor = `grok-native:${acquisition}:${outputIndex}:${prefixes[outputIndex]}`;
77
107
  yield record;
78
108
  }
79
109
  return;
80
110
  }
81
- const parsed = await this.readSource(source);
82
- const start = parseCursor(cursor?.value);
111
+ const saved = cursor?.value?.match(/^grok-export:(\d+):([a-f0-9]{64})$/);
112
+ const start = parseCursor(saved?.[1] ?? cursor?.value);
113
+ const hash = createHash('sha256');
83
114
  let outputIndex = 0;
115
+ for await (const record of this.exportRecords(source)) {
116
+ hash.update(JSON.stringify(record) + '\n');
117
+ outputIndex += 1;
118
+ const digest = hash.copy().digest('hex');
119
+ if (outputIndex === start && saved && digest !== saved[2]) {
120
+ throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build export checkpoint prefix changed; review and import a separate export source.');
121
+ }
122
+ if (outputIndex <= start)
123
+ continue;
124
+ yield { ...record, sourceCursor: `grok-export:${outputIndex}:${digest}` };
125
+ }
126
+ if (start > outputIndex)
127
+ throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build export checkpoint is beyond the retained transcript; use a separate export source.');
128
+ }
129
+ async *exportRecords(source) {
130
+ const parsed = await this.readSource(source);
84
131
  for (const [sequence, block] of parsed.blocks.entries()) {
85
132
  if (block.heading === 'Tools') {
86
133
  for (const tool of parseTools(block.text, sequence)) {
87
- if (outputIndex++ < start)
88
- continue;
89
134
  yield {
90
135
  nativeSessionId: parsed.sessionId,
91
136
  nativeEventId: undefined,
@@ -101,8 +146,6 @@ export class GrokBuildSessionAdapter {
101
146
  }
102
147
  continue;
103
148
  }
104
- if (outputIndex++ < start)
105
- continue;
106
149
  yield {
107
150
  nativeSessionId: parsed.sessionId,
108
151
  nativeEventId: undefined,
@@ -116,6 +159,22 @@ export class GrokBuildSessionAdapter {
116
159
  };
117
160
  }
118
161
  }
162
+ async fallbackRecords(source, cursor) {
163
+ const saved = cursor?.match(/^(\d+):([a-f0-9]{64})$/);
164
+ const start = parseCursor(saved?.[1] ?? cursor);
165
+ if (!this.cliFallback)
166
+ throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build CLI fallback is unavailable; use an explicit `grok export`.');
167
+ return withGrokCliFallback(source, this.cliFallback, async (selected) => {
168
+ const records = [];
169
+ for await (const record of this.stream(selected, { value: saved ? `grok-export:${cursor}` : String(start) })) {
170
+ const extensions = record.extensions ?? {};
171
+ records.push({ ...record, sourceCursor: record.sourceCursor.replace('grok-export:', 'grok-cli:'), extensions: { ...extensions,
172
+ provenance: { ...extensions.provenance, nativeFallback: true },
173
+ } });
174
+ }
175
+ return records;
176
+ });
177
+ }
119
178
  async readSource(source) {
120
179
  if (source.locatorClass !== GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS) {
121
180
  throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build accepts only a documented `grok export` Markdown transcript or an '
@@ -166,7 +225,7 @@ function parseBlocks(value) {
166
225
  current = { heading: match[1], lines: [] };
167
226
  }
168
227
  else if (/^##\s+/.test(line)) {
169
- throw new SessionContractError('SCHEMA_DRIFT', `unknown Grok Build CLI export heading: ${line}`, schemaIssueDetail('headings'));
228
+ throw new SessionContractError('SCHEMA_DRIFT', 'unknown Grok Build CLI export heading; check the source CLI version', schemaIssueDetail('headings'));
170
229
  }
171
230
  else if (current) {
172
231
  current.lines.push(line);
@@ -179,21 +238,24 @@ function parseBlocks(value) {
179
238
  return blocks;
180
239
  }
181
240
  function parseTools(text, blockSequence) {
182
- const lines = text.split('\n').filter((line) => line.trim());
183
- if (lines.length === 0 || lines.length > 1_000) {
241
+ const summaries = [];
242
+ for (const line of text.split('\n')) {
243
+ if (/^- .+/.test(line))
244
+ summaries.push(line.slice(2));
245
+ else if (summaries.length)
246
+ summaries[summaries.length - 1] += `\n${line}`;
247
+ else if (line.trim()) {
248
+ throw new SessionContractError('SCHEMA_DRIFT', 'unrecognized Grok Build tool summary', schemaIssueDetail('tools'));
249
+ }
250
+ }
251
+ if (!summaries.length || summaries.length > 1_000) {
184
252
  throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build tools block has no summaries or exceeds 1,000 summaries', schemaIssueDetail('tools'));
185
253
  }
186
- return lines.map((line, index) => {
187
- const match = /^- (.+)$/.exec(line);
188
- if (!match) {
189
- throw new SessionContractError('SCHEMA_DRIFT', `unrecognized Grok Build tool summary: ${line}`, schemaIssueDetail('tools'));
190
- }
191
- const summary = match[1];
254
+ return summaries.map((summary, index) => {
192
255
  const name = summary.split(/:| \(/, 1)[0]?.trim();
193
- if (!name) {
256
+ if (!name)
194
257
  throw new SessionContractError('SCHEMA_DRIFT', 'empty Grok Build tool summary', schemaIssueDetail('tools'));
195
- }
196
- return { sequence: blockSequence * 1_000 + index, name, text: summary };
258
+ return { sequence: blockSequence * 1_000 + index, name, text: summary.trimEnd() };
197
259
  });
198
260
  }
199
261
  function provenance(source, sessionId, heading) {
@@ -206,6 +268,7 @@ function provenance(source, sessionId, heading) {
206
268
  sourceSchema: GROK_BUILD_CLI_EXPORT_SCHEMA_VERSION,
207
269
  heading,
208
270
  nativeStoreInspected: false,
271
+ toolOutputAvailable: false,
209
272
  originalFilename: basename(source.locator),
210
273
  },
211
274
  identity: {