ai4ai 0.0.3 → 0.0.6

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 (184) hide show
  1. package/README.md +6 -0
  2. package/README.zh-CN.md +6 -0
  3. package/claude-plugin/.claude-plugin/plugin.json +1 -1
  4. package/claude-plugin/dist/adapters/claude/adapter.d.ts +10 -1
  5. package/claude-plugin/dist/adapters/claude/adapter.js +35 -10
  6. package/claude-plugin/dist/adapters/claude/journal.d.ts +8 -0
  7. package/claude-plugin/dist/adapters/claude/journal.js +4 -1
  8. package/claude-plugin/dist/adapters/claude/plugin.js +254 -107
  9. package/claude-plugin/dist/adapters/claude/worker.js +30 -8
  10. package/claude-plugin/dist/adapters/codex/adapter.d.ts +26 -19
  11. package/claude-plugin/dist/adapters/codex/adapter.js +283 -187
  12. package/claude-plugin/dist/adapters/codex/app-server.js +1 -1
  13. package/claude-plugin/dist/adapters/codex/control.d.ts +36 -1
  14. package/claude-plugin/dist/adapters/codex/control.js +74 -4
  15. package/claude-plugin/dist/adapters/codex/native-handoff.d.ts +60 -0
  16. package/claude-plugin/dist/adapters/codex/native-handoff.js +138 -0
  17. package/claude-plugin/dist/adapters/codex/runner.js +35 -32
  18. package/claude-plugin/dist/adapters/codex/tui-daemon-watch.js +60 -49
  19. package/claude-plugin/dist/adapters/declarations.d.ts +0 -1
  20. package/claude-plugin/dist/adapters/declarations.js +0 -1
  21. package/claude-plugin/dist/adapters/dsh/adapter.d.ts +39 -2
  22. package/claude-plugin/dist/adapters/dsh/adapter.js +164 -37
  23. package/claude-plugin/dist/adapters/dsh/plugin.d.ts +3 -1
  24. package/claude-plugin/dist/adapters/dsh/plugin.js +33 -22
  25. package/claude-plugin/dist/adapters/executors.d.ts +25 -2
  26. package/claude-plugin/dist/adapters/executors.js +58 -4
  27. package/claude-plugin/dist/adapters/external.d.ts +21 -0
  28. package/claude-plugin/dist/adapters/external.js +128 -18
  29. package/claude-plugin/dist/adapters/opencode/adapter.d.ts +13 -2
  30. package/claude-plugin/dist/adapters/opencode/adapter.js +53 -10
  31. package/claude-plugin/dist/adapters/opencode/journal.d.ts +2 -0
  32. package/claude-plugin/dist/adapters/opencode/journal.js +12 -4
  33. package/claude-plugin/dist/adapters/opencode/plugin.d.ts +3 -5
  34. package/claude-plugin/dist/adapters/opencode/plugin.js +3 -292
  35. package/claude-plugin/dist/adapters/opencode/setup.d.ts +9 -0
  36. package/claude-plugin/dist/adapters/opencode/setup.js +350 -0
  37. package/claude-plugin/dist/adapters/supervisor.js +64 -20
  38. package/claude-plugin/dist/adapters/types.d.ts +7 -0
  39. package/claude-plugin/dist/contract/schema.d.ts +8 -17
  40. package/claude-plugin/dist/contract/schema.js +3 -4
  41. package/claude-plugin/dist/contract/states.d.ts +11 -0
  42. package/claude-plugin/dist/contract/states.js +9 -0
  43. package/claude-plugin/dist/contract/types.d.ts +3 -3
  44. package/claude-plugin/dist/contract/validate.js +24 -14
  45. package/claude-plugin/dist/contract/version.d.ts +1 -1
  46. package/claude-plugin/dist/contract/version.js +1 -1
  47. package/claude-plugin/dist/core/dsh-selection.d.ts +43 -0
  48. package/claude-plugin/dist/core/dsh-selection.js +78 -0
  49. package/claude-plugin/dist/core/handoff.d.ts +42 -0
  50. package/claude-plugin/dist/core/handoff.js +63 -0
  51. package/claude-plugin/dist/core/index.d.ts +2 -0
  52. package/claude-plugin/dist/core/index.js +1 -0
  53. package/claude-plugin/dist/core/operations.js +33 -1
  54. package/claude-plugin/dist/core/retained-input.d.ts +24 -0
  55. package/claude-plugin/dist/core/retained-input.js +50 -0
  56. package/claude-plugin/dist/core/session-probe.js +11 -22
  57. package/claude-plugin/dist/core/store.d.ts +8 -3
  58. package/claude-plugin/dist/core/store.js +17 -3
  59. package/claude-plugin/request-schema.json +1 -2
  60. package/dist/adapters/claude/adapter.d.ts +10 -1
  61. package/dist/adapters/claude/adapter.js +35 -10
  62. package/dist/adapters/claude/journal.d.ts +8 -0
  63. package/dist/adapters/claude/journal.js +4 -1
  64. package/dist/adapters/claude/plugin.js +254 -107
  65. package/dist/adapters/claude/worker.js +30 -8
  66. package/dist/adapters/codex/adapter.d.ts +26 -19
  67. package/dist/adapters/codex/adapter.js +283 -187
  68. package/dist/adapters/codex/app-server.js +1 -1
  69. package/dist/adapters/codex/control.d.ts +36 -1
  70. package/dist/adapters/codex/control.js +74 -4
  71. package/dist/adapters/codex/native-handoff.d.ts +60 -0
  72. package/dist/adapters/codex/native-handoff.js +138 -0
  73. package/dist/adapters/codex/runner.js +35 -32
  74. package/dist/adapters/codex/tui-daemon-watch.js +60 -49
  75. package/dist/adapters/declarations.d.ts +0 -1
  76. package/dist/adapters/declarations.js +0 -1
  77. package/dist/adapters/dsh/adapter.d.ts +39 -2
  78. package/dist/adapters/dsh/adapter.js +164 -37
  79. package/dist/adapters/dsh/plugin.d.ts +3 -1
  80. package/dist/adapters/dsh/plugin.js +33 -22
  81. package/dist/adapters/executors.d.ts +25 -2
  82. package/dist/adapters/executors.js +58 -4
  83. package/dist/adapters/external.d.ts +21 -0
  84. package/dist/adapters/external.js +128 -18
  85. package/dist/adapters/opencode/adapter.d.ts +13 -2
  86. package/dist/adapters/opencode/adapter.js +53 -10
  87. package/dist/adapters/opencode/journal.d.ts +2 -0
  88. package/dist/adapters/opencode/journal.js +12 -4
  89. package/dist/adapters/opencode/plugin.d.ts +3 -5
  90. package/dist/adapters/opencode/plugin.js +3 -292
  91. package/dist/adapters/opencode/setup.d.ts +9 -0
  92. package/dist/adapters/opencode/setup.js +350 -0
  93. package/dist/adapters/supervisor.js +64 -20
  94. package/dist/adapters/types.d.ts +7 -0
  95. package/dist/contract/schema.d.ts +8 -17
  96. package/dist/contract/schema.js +3 -4
  97. package/dist/contract/states.d.ts +11 -0
  98. package/dist/contract/states.js +9 -0
  99. package/dist/contract/types.d.ts +3 -3
  100. package/dist/contract/validate.js +24 -14
  101. package/dist/contract/version.d.ts +1 -1
  102. package/dist/contract/version.js +1 -1
  103. package/dist/core/dsh-selection.d.ts +43 -0
  104. package/dist/core/dsh-selection.js +78 -0
  105. package/dist/core/handoff.d.ts +42 -0
  106. package/dist/core/handoff.js +63 -0
  107. package/dist/core/index.d.ts +2 -0
  108. package/dist/core/index.js +1 -0
  109. package/dist/core/operations.js +33 -1
  110. package/dist/core/retained-input.d.ts +24 -0
  111. package/dist/core/retained-input.js +50 -0
  112. package/dist/core/session-probe.js +11 -22
  113. package/dist/core/store.d.ts +8 -3
  114. package/dist/core/store.js +17 -3
  115. package/docs/contract.md +31 -15
  116. package/opencode-plugin/dist/adapters/claude/adapter.d.ts +10 -1
  117. package/opencode-plugin/dist/adapters/claude/adapter.js +35 -10
  118. package/opencode-plugin/dist/adapters/claude/journal.d.ts +8 -0
  119. package/opencode-plugin/dist/adapters/claude/journal.js +4 -1
  120. package/opencode-plugin/dist/adapters/claude/plugin.js +254 -107
  121. package/opencode-plugin/dist/adapters/claude/worker.js +30 -8
  122. package/opencode-plugin/dist/adapters/codex/adapter.d.ts +26 -19
  123. package/opencode-plugin/dist/adapters/codex/adapter.js +283 -187
  124. package/opencode-plugin/dist/adapters/codex/app-server.js +1 -1
  125. package/opencode-plugin/dist/adapters/codex/control.d.ts +36 -1
  126. package/opencode-plugin/dist/adapters/codex/control.js +74 -4
  127. package/opencode-plugin/dist/adapters/codex/native-handoff.d.ts +60 -0
  128. package/opencode-plugin/dist/adapters/codex/native-handoff.js +138 -0
  129. package/opencode-plugin/dist/adapters/codex/runner.js +35 -32
  130. package/opencode-plugin/dist/adapters/codex/tui-daemon-watch.js +60 -49
  131. package/opencode-plugin/dist/adapters/declarations.d.ts +0 -1
  132. package/opencode-plugin/dist/adapters/declarations.js +0 -1
  133. package/opencode-plugin/dist/adapters/dsh/adapter.d.ts +39 -2
  134. package/opencode-plugin/dist/adapters/dsh/adapter.js +164 -37
  135. package/opencode-plugin/dist/adapters/dsh/plugin.d.ts +3 -1
  136. package/opencode-plugin/dist/adapters/dsh/plugin.js +33 -22
  137. package/opencode-plugin/dist/adapters/executors.d.ts +25 -2
  138. package/opencode-plugin/dist/adapters/executors.js +58 -4
  139. package/opencode-plugin/dist/adapters/external.d.ts +21 -0
  140. package/opencode-plugin/dist/adapters/external.js +128 -18
  141. package/opencode-plugin/dist/adapters/opencode/adapter.d.ts +13 -2
  142. package/opencode-plugin/dist/adapters/opencode/adapter.js +53 -10
  143. package/opencode-plugin/dist/adapters/opencode/journal.d.ts +2 -0
  144. package/opencode-plugin/dist/adapters/opencode/journal.js +12 -4
  145. package/opencode-plugin/dist/adapters/opencode/plugin.d.ts +3 -5
  146. package/opencode-plugin/dist/adapters/opencode/plugin.js +3 -292
  147. package/opencode-plugin/dist/adapters/opencode/setup.d.ts +9 -0
  148. package/opencode-plugin/dist/adapters/opencode/setup.js +350 -0
  149. package/opencode-plugin/dist/adapters/supervisor.js +64 -20
  150. package/opencode-plugin/dist/adapters/types.d.ts +7 -0
  151. package/opencode-plugin/dist/contract/schema.d.ts +8 -17
  152. package/opencode-plugin/dist/contract/schema.js +3 -4
  153. package/opencode-plugin/dist/contract/states.d.ts +11 -0
  154. package/opencode-plugin/dist/contract/states.js +9 -0
  155. package/opencode-plugin/dist/contract/types.d.ts +3 -3
  156. package/opencode-plugin/dist/contract/validate.js +24 -14
  157. package/opencode-plugin/dist/contract/version.d.ts +1 -1
  158. package/opencode-plugin/dist/contract/version.js +1 -1
  159. package/opencode-plugin/dist/core/dsh-selection.d.ts +43 -0
  160. package/opencode-plugin/dist/core/dsh-selection.js +78 -0
  161. package/opencode-plugin/dist/core/handoff.d.ts +42 -0
  162. package/opencode-plugin/dist/core/handoff.js +63 -0
  163. package/opencode-plugin/dist/core/index.d.ts +2 -0
  164. package/opencode-plugin/dist/core/index.js +1 -0
  165. package/opencode-plugin/dist/core/operations.js +33 -1
  166. package/opencode-plugin/dist/core/retained-input.d.ts +24 -0
  167. package/opencode-plugin/dist/core/retained-input.js +50 -0
  168. package/opencode-plugin/dist/core/session-probe.js +11 -22
  169. package/opencode-plugin/dist/core/store.d.ts +8 -3
  170. package/opencode-plugin/dist/core/store.js +17 -3
  171. package/opencode-plugin/package.json +1 -1
  172. package/package.json +1 -1
  173. package/claude-plugin/dist/adapters/codex/tui-restart-watch.d.ts +0 -2
  174. package/claude-plugin/dist/adapters/codex/tui-restart-watch.js +0 -330
  175. package/claude-plugin/dist/tmux/backend.d.ts +0 -55
  176. package/claude-plugin/dist/tmux/backend.js +0 -161
  177. package/dist/adapters/codex/tui-restart-watch.d.ts +0 -2
  178. package/dist/adapters/codex/tui-restart-watch.js +0 -330
  179. package/dist/tmux/backend.d.ts +0 -55
  180. package/dist/tmux/backend.js +0 -161
  181. package/opencode-plugin/dist/adapters/codex/tui-restart-watch.d.ts +0 -2
  182. package/opencode-plugin/dist/adapters/codex/tui-restart-watch.js +0 -330
  183. package/opencode-plugin/dist/tmux/backend.d.ts +0 -55
  184. package/opencode-plugin/dist/tmux/backend.js +0 -161
@@ -1,6 +1,6 @@
1
1
  import type { AdapterContext, CarrierCommand, StatusDetails } from '../external.js';
2
2
  import { ExternalExecutorAdapter } from '../external.js';
3
- import type { CapabilityDeclaration } from '../../contract/types.js';
3
+ import type { CapabilityDeclaration, Request } from '../../contract/types.js';
4
4
  import type { HarnessId, Os } from '../../contract/states.js';
5
5
  import type { ExecutorRecord } from '../../core/store.js';
6
6
  import type { LogLine, ExecutorStatus } from '../executors.js';
@@ -15,6 +15,15 @@ export declare function claudePluginDir(home: string): string | undefined;
15
15
  export declare class ClaudeAdapter extends ExternalExecutorAdapter {
16
16
  readonly harness: HarnessId;
17
17
  capabilities(os: Os): CapabilityDeclaration[];
18
+ /**
19
+ * Persist the model a resumed turn must keep. The carrier passes `--model`
20
+ * only when the request has one, so the effective value can come from the
21
+ * settings `env` block (which overrides the inherited process environment)
22
+ * or the process environment.
23
+ */
24
+ protected persistedModel(request: Request, ctx: AdapterContext): Promise<string | undefined>;
25
+ /** `CLAUDE_CODE_EFFORT_LEVEL` overrides the settings `effortLevel`. */
26
+ protected persistedReasoningEffort(request: Request, ctx: AdapterContext): Promise<string | undefined>;
18
27
  protected carrier(request: Parameters<ExternalExecutorAdapter['spawn']>[0], ctx: AdapterContext, _executorId: string, resumeSessionId?: string): Promise<CarrierCommand>;
19
28
  protected statusDetails(_record: ExecutorRecord, status: ExecutorStatus, log: LogLine[], ctx: AdapterContext): Promise<StatusDetails>;
20
29
  }
@@ -4,6 +4,7 @@ import { randomUUID } from 'node:crypto';
4
4
  import { ExternalExecutorAdapter, lastJson } from '../external.js';
5
5
  import { resolveClaudeStatus } from './status.js';
6
6
  import { verifiedText, verifiedTokens, verifiedWindow } from '../../core/ladder.js';
7
+ import { envValue, probeClaudeSettings } from '../../core/config-probe.js';
7
8
  import { declaration } from '../declarations.js';
8
9
  /**
9
10
  * Claude Code adapter.
@@ -31,24 +32,48 @@ export function claudePluginDir(home) {
31
32
  export class ClaudeAdapter extends ExternalExecutorAdapter {
32
33
  harness = 'claude-code';
33
34
  capabilities(os) {
34
- const verified = os === 'linux' || os === 'darwin';
35
- const reason = os === 'linux'
36
- ? 'The mods plugin loads and both native handoff modes completed in place: restart via the built-in /clear (new session, same process) and compact via the native safe point; detached carriers spawn, report status and survive the parent. Exercised on Linux.'
37
- : os === 'darwin'
38
- ? 'The mods plugin loads and the native in-place handoff completed on macOS; detached carriers spawn and report status with model and context. Exercised on macOS.'
35
+ const linux = os === 'linux';
36
+ const mac = os === 'darwin';
37
+ // macOS proves both the handoff and the detached carrier in this release.
38
+ const reason = linux
39
+ ? 'The mods plugin loads and the zero-summary restart replaces the context in place through the native compact hook while keeping the session id; a disabled-compaction session is reported unsupported. Detached carriers spawn, report status and survive the parent. Exercised on Linux.'
40
+ : mac
41
+ ? 'The mods plugin loads and the zero-summary in-place restart completed on macOS with the session id preserved (handoff verified). The detached carrier was exercised on macOS with a real two-turn executor: spawn, status, message queued into the same session (both turn markers in the executor log), stop, and the error paths (unauthorized target, message to a completed executor) all completed.'
39
42
  : 'The mods plugin and the detached carrier are implemented; native Windows is out of scope (WSL counts as Linux) and was not exercised.';
40
- const level = verified ? 'supported' : 'not-tested';
43
+ const carrier = linux || mac ? 'supported' : 'not-tested';
41
44
  const common = {
42
- handoff: { availability: level, modes: ['compact', 'restart'], tmuxFallback: 'off' },
43
- spawn: { availability: level, maxConcurrent: 4 },
44
- status: { availability: level, model: level, reasoningEffort: 'unsupported', context: level, percentSource: 'derived' },
45
- ...(verified ? { evidence: `matrix:claude-code/${os}/2026-11-18` } : {}),
45
+ handoff: { availability: linux || mac ? 'supported' : 'not-tested', modes: ['restart'] },
46
+ spawn: { availability: carrier, maxConcurrent: 4 },
47
+ status: { availability: carrier, model: carrier, reasoningEffort: 'unsupported', context: carrier, percentSource: 'derived' },
48
+ ...(linux || mac ? { evidence: `matrix:claude-code/${os}/2026-11-21` } : {}),
46
49
  };
47
50
  return [
48
51
  declaration({ harness: 'claude-code', os, interface: 'tui', reason, ...common }),
49
52
  declaration({ harness: 'claude-code', os, interface: 'headless', reason, ...common }),
50
53
  ];
51
54
  }
55
+ /**
56
+ * Persist the model a resumed turn must keep. The carrier passes `--model`
57
+ * only when the request has one, so the effective value can come from the
58
+ * settings `env` block (which overrides the inherited process environment)
59
+ * or the process environment.
60
+ */
61
+ async persistedModel(request, ctx) {
62
+ if (request.model)
63
+ return request.model;
64
+ const settings = await probeClaudeSettings(ctx.identity.workspace, undefined, ['ANTHROPIC_MODEL']).catch(() => null);
65
+ return settings?.env[0]?.value ?? envValue('ANTHROPIC_MODEL') ?? undefined;
66
+ }
67
+ /** `CLAUDE_CODE_EFFORT_LEVEL` overrides the settings `effortLevel`. */
68
+ async persistedReasoningEffort(request, ctx) {
69
+ if (request.reasoningEffort)
70
+ return request.reasoningEffort;
71
+ const env = envValue('CLAUDE_CODE_EFFORT_LEVEL');
72
+ if (env)
73
+ return env;
74
+ const settings = await probeClaudeSettings(ctx.identity.workspace, undefined, []).catch(() => null);
75
+ return settings?.effortLevel?.value ?? undefined;
76
+ }
52
77
  async carrier(request, ctx, _executorId, resumeSessionId) {
53
78
  // A detached executor has no one to answer permission prompts: run it in the
54
79
  // harness's non-interactive bypass mode, consistent with the spawn contract.
@@ -1,4 +1,5 @@
1
1
  import type { Identity, Request, Result } from '../../contract/types.js';
2
+ import type { StoredProofMechanism } from '../../contract/states.js';
2
3
  export type ClaudePhase = 'pending' | 'scheduled' | 'applied' | 'completed' | 'cancelled' | 'failed' | 'unknown';
3
4
  export interface ClaudeRecord {
4
5
  format: 2;
@@ -11,6 +12,12 @@ export interface ClaudeRecord {
11
12
  reason: string;
12
13
  /** Native context replacement strategy recorded for this handoff. */
13
14
  mechanism?: 'restart' | 'compact';
15
+ /**
16
+ * Explicit proof mechanism. New records always set it. Records written
17
+ * before 0.0.5 lack it; their proof is derived from `mechanism` under the
18
+ * historical rules and is exempt from the same-session gate.
19
+ */
20
+ proofMechanism?: StoredProofMechanism;
14
21
  successor?: Identity;
15
22
  }
16
23
  export interface ClaudeCommand {
@@ -25,6 +32,7 @@ export interface ClaudeCommand {
25
32
  /** Native successor identity after a restart (new session id) or compact generation. */
26
33
  successor?: Identity;
27
34
  mechanism?: 'restart' | 'compact';
35
+ proofMechanism?: StoredProofMechanism;
28
36
  usage?: {
29
37
  window?: number | null;
30
38
  used?: number | null;
@@ -3,6 +3,7 @@ import path from 'node:path';
3
3
  import { atomicJson, bytes, contained, digest, ownership, withScopeLock } from '../../install/scope.js';
4
4
  import { result } from '../../contract/validate.js';
5
5
  import { handoffOutcome } from '../../contract/states.js';
6
+ import { legacyProofMechanism } from '../../core/handoff.js';
6
7
  const PHASES = ['pending', 'scheduled', 'applied', 'completed', 'cancelled', 'failed', 'unknown'];
7
8
  const sessionKey = (identity) => `${identity.workspace}\0${identity.surface}\0${identity.session}`;
8
9
  function response(record, operation = 'handoff') {
@@ -16,7 +17,9 @@ function response(record, operation = 'handoff') {
16
17
  ? {
17
18
  proof: {
18
19
  source: record.source, successor: record.successor,
19
- mechanism: (record.mechanism === 'restart' ? 'new-session' : 'surface-replacement'),
20
+ // New records carry the explicit field; old records keep the
21
+ // mechanism they historically implied and stay legacy-exempt.
22
+ mechanism: record.proofMechanism ?? legacyProofMechanism(record.mechanism),
20
23
  nativeEvidence: record.marker,
21
24
  },
22
25
  }
@@ -1,13 +1,97 @@
1
1
  import { TOOL_DESCRIPTION, TOOL_NAME, normalizeToolRequest } from '../../contract/tool.js';
2
- import { resolveBindingFile } from '../../install/binding.js';
2
+ import { RetainedInput, mergeRetained } from '../../core/retained-input.js';
3
3
  const tool = 'mcp__ai4ai__session';
4
4
  const dbg = ($, message) => { try {
5
5
  $.ui.log('ai4ai debug: ' + message, { to: 'debug' });
6
6
  }
7
7
  catch { /* debug only */ } };
8
- const projection = (rows) => JSON.stringify(rows.map((message) => ({
9
- role: message.role, text: message.text, toolUses: message.toolUses, toolResults: message.toolResults ?? [],
10
- })));
8
+ // Import-free path helpers for the hooks sandbox (see the import comment).
9
+ const trimTrailing = (value) => value.replace(/[\\/]+$/, '');
10
+ const absolutePath = (value) => typeof value === 'string'
11
+ && (value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\'));
12
+ const normalizedPath = (value) => {
13
+ const trimmed = trimTrailing(value).replace(/\\/g, '/');
14
+ // Windows paths compare case-insensitively; POSIX paths do not.
15
+ return /^[A-Za-z]:/.test(trimmed) || trimmed.startsWith('//') ? trimmed.toLowerCase() : trimmed;
16
+ };
17
+ const containsWorkspace = (root, candidate) => {
18
+ const owner = normalizedPath(root);
19
+ const target = normalizedPath(candidate);
20
+ return target === owner || target.startsWith(owner.endsWith('/') ? owner : `${owner}/`);
21
+ };
22
+ const parentPath = (value) => {
23
+ const trimmed = trimTrailing(value);
24
+ const index = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
25
+ if (index < 0)
26
+ return trimmed;
27
+ if (index === 0)
28
+ return '/';
29
+ if (index === 2 && /^[A-Za-z]:/.test(trimmed))
30
+ return trimmed.slice(0, 3);
31
+ return trimmed.slice(0, index);
32
+ };
33
+ const joinPath = (directory, name) => {
34
+ const trimmed = trimTrailing(directory);
35
+ const separator = trimmed.includes('\\') && !trimmed.includes('/') ? '\\' : '/';
36
+ return `${trimmed}${separator}${name}`;
37
+ };
38
+ /** Read one binding candidate through the host API; malformed/foreign records are skipped. */
39
+ async function readBinding($, file) {
40
+ let raw;
41
+ try {
42
+ raw = await $.fs.read(file);
43
+ }
44
+ catch {
45
+ return undefined;
46
+ }
47
+ if (typeof raw !== 'string')
48
+ return undefined;
49
+ let value;
50
+ try {
51
+ value = JSON.parse(raw);
52
+ }
53
+ catch {
54
+ return undefined;
55
+ }
56
+ if (!value || value.product !== 'ai4ai' || value.format !== 2 || !absolutePath(value.home) || !absolutePath(value.workspace)
57
+ || typeof value.ownerToken !== 'string' || value.ownerToken.length === 0)
58
+ return undefined;
59
+ return {
60
+ home: value.home, workspace: value.workspace, ownerToken: value.ownerToken,
61
+ ...(typeof value.node === 'string' && absolutePath(value.node) ? { node: value.node } : {}),
62
+ };
63
+ }
64
+ /**
65
+ * Import-free binding resolution: the nearest workspace-local binding whose
66
+ * recorded workspace contains the caller wins; the plugin-root binding is a
67
+ * compatible fallback. The worker validates ownership again when used.
68
+ */
69
+ async function resolveBinding($) {
70
+ const workspace = await $.session.cwd();
71
+ if (typeof workspace !== 'string' || !absolutePath(workspace))
72
+ return undefined;
73
+ const candidates = [];
74
+ let current = workspace;
75
+ for (let depth = 0; depth < 16; depth += 1) {
76
+ candidates.push(joinPath(current, '.ai4ai/binding.json'));
77
+ const parent = parentPath(current);
78
+ if (parent === current)
79
+ break;
80
+ current = parent;
81
+ }
82
+ candidates.push(joinPath($.plugin.root, 'binding.json'));
83
+ for (const file of candidates) {
84
+ const binding = await readBinding($, file);
85
+ if (binding && containsWorkspace(binding.workspace, workspace))
86
+ return { binding, path: file };
87
+ }
88
+ return undefined;
89
+ }
90
+ /** The handoff window: accepted but not yet completed. */
91
+ const HANDOFF_WINDOW = ['pending', 'scheduled', 'applied'];
92
+ const TERMINAL = ['cancelled', 'failed', 'unknown'];
93
+ const RETAINED_SCOPE = 'handoff';
94
+ const inHandoffWindow = (s) => !!s.active && HANDOFF_WINDOW.includes(String(s.active.phase));
11
95
  async function rpc($, node, payload, bindingPath) {
12
96
  let marker;
13
97
  try {
@@ -21,7 +105,12 @@ async function rpc($, node, payload, bindingPath) {
21
105
  : undefined;
22
106
  }
23
107
  catch { /* the transcript is unavailable in some lifecycle phases */ }
24
- return rpcWith($, node, { ...payload, ...(marker ? { marker } : {}) }, bindingPath);
108
+ // The transcript marker is generation authority for calls that have none of
109
+ // their own (binding/inspect/request). A transition already carries the
110
+ // target record's marker; overriding it with the current window's marker
111
+ // would reject every handoff after the first one.
112
+ const authority = marker && payload.marker === undefined ? { marker } : {};
113
+ return rpcWith($, node, { ...payload, ...authority }, bindingPath);
25
114
  }
26
115
  async function rpcWith($, node, payload, bindingPath) {
27
116
  const out = await $.process.run([node, `${$.plugin.root}/dist/adapters/claude/worker.js`], {
@@ -42,16 +131,21 @@ async function currentSurface($) {
42
131
  async function transition($, current, phase, reason, extra = {}, caller) {
43
132
  if (!current.binding || !current.active)
44
133
  return undefined;
45
- // The journal is keyed by the record's source session. After a restart the
46
- // in-memory binding points at the successor, so transitions must use the
47
- // source identity or the record would not be found.
134
+ // The journal is keyed by the record's source session. The in-place
135
+ // replacement keeps that session, but transitions still use the record's
136
+ // source identity so a later generation cannot be mistaken for it.
48
137
  const from = caller ?? current.active.source ?? current.binding;
49
138
  const out = await rpc($, current.node, {
50
139
  caller: from, action: 'transition', operationId: current.active.operationId,
51
140
  marker: current.active.marker, phase, reason, ...extra,
52
141
  }, current.bindingPath);
53
- if (out.record)
142
+ if (out.record) {
54
143
  current.active = out.record;
144
+ // A cancelled, failed or uncertain handoff terminates the window; retained
145
+ // input belongs to the abandoned transition and is never replayed later.
146
+ if (TERMINAL.includes(String(out.record.phase)))
147
+ current.retained.clear(RETAINED_SCOPE);
148
+ }
55
149
  return out;
56
150
  }
57
151
  async function bindNative($, s) {
@@ -78,77 +172,75 @@ function admitted(s) {
78
172
  return !!s.delivery && !s.delivery.invalid && (s.delivery.adopted
79
173
  || (s.active?.phase === 'applied' && s.active.operationId === s.delivery.operationId && s.binding?.generation === s.delivery.marker));
80
174
  }
175
+ /**
176
+ * Replay input retained during the handoff. The queue is drained before the
177
+ * submit so one message is never delivered twice; a submit failure is logged
178
+ * and not retried, because the host may already have accepted it.
179
+ */
180
+ async function replayRetained($, s) {
181
+ const entries = s.retained.take(RETAINED_SCOPE);
182
+ if (entries.length === 0)
183
+ return;
184
+ const text = `AI4AI retained user input from during the handoff. Act on it now.\n${mergeRetained(entries)}`;
185
+ try {
186
+ await $.prompt.submit({ text });
187
+ }
188
+ catch (error) {
189
+ dbg($, 'retained input replay failed: ' + String(error?.message ?? error));
190
+ }
191
+ }
81
192
  /** Schedule the native context replacement and deliver the task; callable from a hook. */
82
193
  async function pump($, s) {
83
194
  if (s.busy || s.pumping || s.active?.phase !== 'scheduled')
84
195
  return;
85
196
  s.pumping = true;
86
197
  try {
198
+ if (s.active?.phase !== 'scheduled')
199
+ return;
200
+ const mode = s.active.mechanism ?? s.active.request.mode ?? 'restart';
201
+ if (mode !== 'restart') {
202
+ // The native pump implements the zero-summary restart only. A compact
203
+ // request must be refused by the worker before it reaches this point.
204
+ await transition($, s, 'unknown', 'The native pump implements restart only; no replacement attempted');
205
+ return;
206
+ }
207
+ const before = await $.session.id();
208
+ const source = s.binding;
209
+ if (!source)
210
+ return;
211
+ s.appliedHere = false;
212
+ s.replacement = undefined;
213
+ // `compact` runs the session.compact hook, which supplies a replacement
214
+ // message window and prevents the core compaction (and its summarizer)
215
+ // from running. The hook must finish inside the host's 10s budget, so it
216
+ // returns the window immediately and journals the transition separately.
217
+ await $.command.run({ command: 'compact', args: s.active.marker });
218
+ if (s.replacement)
219
+ await s.replacement;
220
+ // Explicit same-SID assertion: the replacement must not change the native
221
+ // session. A changed id is a defect, never a successful handoff.
222
+ const after = await $.session.id();
223
+ if (after !== before) {
224
+ await transition($, s, 'unknown', 'The native replacement changed the session id; the handoff was refused and the task was not delivered');
225
+ return;
226
+ }
227
+ if (!s.appliedHere || s.active?.phase !== 'applied') {
228
+ await transition($, s, 'unknown', 'Native replacement could not be proved; no task redelivery');
229
+ return;
230
+ }
231
+ let api = '';
87
232
  try {
88
- s.expectedWindow = projection(await $.session.messages());
233
+ api = JSON.stringify(await $.session.messages({ as: 'api' }));
89
234
  }
90
235
  catch {
91
- s.expectedWindow = '';
236
+ api = '';
92
237
  }
93
- if (s.active?.phase !== 'scheduled')
238
+ if (api !== '' && !api.includes(s.active.marker)) {
239
+ await transition($, s, 'unknown', 'The replacement window does not contain the AI4AI binding; no task redelivery');
94
240
  return;
95
- const mode = s.active.mechanism ?? s.active.request.mode ?? 'restart';
96
- if (mode === 'restart') {
97
- // Native in-place reset: the built-in /clear starts a new session with
98
- // empty context in the same process (the host pipe stays intact).
99
- const before = await $.session.id();
100
- const source = s.binding;
101
- if (!source)
102
- return;
103
- s.restarting = true;
104
- try {
105
- await $.command.run({ command: 'clear' });
106
- let after = before;
107
- for (let i = 0; i < 80 && after === before; i++) {
108
- await new Promise(resolve => setTimeout(resolve, 100));
109
- after = await $.session.id();
110
- }
111
- if (after === before) {
112
- await transition($, s, 'unknown', 'Native /clear did not produce a new session id; no task redelivery');
113
- return;
114
- }
115
- let display = '';
116
- try {
117
- display = JSON.stringify(await $.session.messages());
118
- }
119
- catch {
120
- display = '';
121
- }
122
- const clearSeen = display.includes('/clear') || display.includes('local_command');
123
- if (!clearSeen)
124
- dbg($, 'restart: /clear entry was not exposed by the plugin transcript view; the session id change is the native evidence');
125
- const successor = { ...source, session: after, generation: s.active.marker };
126
- await transition($, s, 'applied', clearSeen
127
- ? 'Native /clear reset the context in place; successor delivery pending'
128
- : 'Native /clear changed the session id in place; successor delivery pending', { successor, mechanism: 'restart' }, source);
129
- s.binding = successor;
130
- s.appliedHere = true;
131
- }
132
- finally {
133
- s.restarting = false;
134
- }
135
- }
136
- else {
137
- await $.command.run({ command: 'compact', args: s.active.marker });
138
- let api = '';
139
- try {
140
- api = JSON.stringify(await $.session.messages({ as: 'api' }));
141
- }
142
- catch {
143
- api = '';
144
- }
145
- if (!s.appliedHere || s.active.phase !== 'applied' || (api !== '' && !api.includes(s.active.marker))) {
146
- await transition($, s, 'unknown', 'Native replacement could not be proved; no task redelivery');
147
- return;
148
- }
149
- if (s.binding)
150
- s.binding = { ...s.binding, generation: s.active.marker };
151
241
  }
242
+ if (s.binding)
243
+ s.binding = { ...s.binding, generation: s.active.marker };
152
244
  const delivery = {
153
245
  text: `AI4AI handoff delivery ${s.active.marker}. Adopt the caller-supplied task in this fresh context. Carry out this task now:\n${s.active.request.task ?? ''}\nNative system/security instructions remain authoritative. Query ai4ai status if you need context or model details.`,
154
246
  operationId: s.active.operationId, marker: s.active.marker, invalid: false, adopted: false,
@@ -158,8 +250,11 @@ async function pump($, s) {
158
250
  }
159
251
  catch (error) {
160
252
  dbg($, 'pump failed: ' + String(error?.message ?? error));
253
+ const disabled = /DISABLE_COMPACT/i.test(String(error?.message ?? error));
161
254
  try {
162
- await transition($, s, 'unknown', 'Native scheduling outcome unknown; no replay');
255
+ await transition($, s, 'failed', disabled
256
+ ? 'Compaction is switched off in this session (DISABLE_COMPACT); the in-place restart is unsupported'
257
+ : 'Native scheduling outcome unknown; no replay');
163
258
  }
164
259
  catch { /* intent remains unreplayed */ }
165
260
  }
@@ -169,23 +264,14 @@ async function pump($, s) {
169
264
  }
170
265
  /** Native Claude Code mods: in-place handoff without a summarizer, daemon or history fork. */
171
266
  export const register = on => {
172
- const s = { instance: '', node: '', busy: false, pumping: false, restarting: false, turnId: '', expectedWindow: '', appliedHere: false };
267
+ const s = { instance: '', node: '', busy: false, pumping: false, turnId: '', appliedHere: false, retained: new RetainedInput() };
173
268
  let tail = Promise.resolve();
174
269
  const serial = (fn) => { const pending = tail.then(fn); tail = pending.catch(() => undefined); return pending; };
175
270
  on('session.start', async ($, e, next) => {
176
271
  // A plugin cache can be shared by several workspaces. The workspace-local
177
272
  // binding always wins; the plugin-root copy is only a compatible fallback.
178
273
  try {
179
- const resolved = await resolveBindingFile({
180
- workspace: await $.session.cwd(),
181
- pluginRoot: $.plugin.root,
182
- read: async (file) => { try {
183
- return await $.fs.read(file);
184
- }
185
- catch {
186
- return undefined;
187
- } },
188
- });
274
+ const resolved = await resolveBinding($);
189
275
  if (resolved) {
190
276
  s.bindingPath = resolved.path;
191
277
  s.node = resolved.binding.node || process.execPath;
@@ -201,10 +287,9 @@ export const register = on => {
201
287
  inputSchema: JSON.parse(await $.fs.read(`${$.plugin.root}/request-schema.json`)),
202
288
  });
203
289
  try {
204
- // A native /clear restart re-enters session.start for the successor
205
- // session; bindNative would look up a journal that belongs to the source
206
- // session. Keep the in-memory restart binding instead.
207
- if (!s.restarting && (!s.binding || await $.session.id() !== s.binding.session))
290
+ // The in-place replacement keeps the same session, so an existing
291
+ // binding remains authoritative across a handoff.
292
+ if (!s.binding || await $.session.id() !== s.binding.session)
208
293
  await serial(() => bindNative($, s));
209
294
  }
210
295
  catch { /* Tool calls fail closed until a later successful bind. */ }
@@ -231,15 +316,13 @@ export const register = on => {
231
316
  await transition($, s, 'completed', 'Successor adopted the replaced context; handoff complete');
232
317
  }
233
318
  }
234
- else if (s.active && !['completed', 'cancelled', 'failed', 'unknown'].includes(s.active.phase)) {
235
- await transition($, s, 'cancelled', 'A different native turn started before successor admission; delivery was not executed');
236
- }
237
319
  });
238
320
  return next(e);
239
321
  });
240
322
  on('turn.complete', async ($, e, next) => {
241
323
  const out = await next(e);
242
324
  let pumpNow = false;
325
+ let replayNow = false;
243
326
  if (!e.agentId)
244
327
  await serial(async () => {
245
328
  dbg($, `turn.complete reason=${String(e.reason)} aborted=${String(e.isAborted)} phase=${String(s.active?.phase)}`);
@@ -251,24 +334,59 @@ export const register = on => {
251
334
  pumpNow = true;
252
335
  }
253
336
  }
337
+ if (s.admissionTurn !== undefined && s.admissionTurn === e.turnId) {
338
+ // Adoption is complete. An aborted successor turn is an explicit stop:
339
+ // its retained input is discarded instead of silently driving a new turn.
340
+ delete s.admissionTurn;
341
+ if (e.isAborted || e.reason !== 'answer')
342
+ s.retained.clear(RETAINED_SCOPE);
343
+ else
344
+ replayNow = s.retained.count(RETAINED_SCOPE) > 0;
345
+ }
254
346
  s.busy = false;
255
347
  });
256
348
  // The native compact triggers our session.compact hook; never hold the
257
349
  // serial queue while it runs or the two wait on each other.
258
350
  if (pumpNow)
259
351
  await pump($, s);
352
+ // The replay starts a new native turn; the host resolves the submit when
353
+ // that turn starts, so the hook must not wait on it.
354
+ else if (replayNow)
355
+ void replayRetained($, s);
260
356
  return out;
261
357
  });
358
+ // The host skips a hook that throws or exceeds its budget and then runs the
359
+ // core compaction, which would summarize the context and break the
360
+ // zero-token guarantee. This handler therefore never performs slow work: it
361
+ // validates in memory, returns the replacement window immediately and starts
362
+ // the journal write in the background. The mods loader requires the hook to
363
+ // be an inline function at the `on(...)` call site, so the fail-closed
364
+ // try/catch lives here rather than in an attached `.catch`.
262
365
  on('session.compact', async ($, e, next) => {
263
366
  if (e.agentId || !e.instructions?.startsWith('ai4ai-context-'))
264
367
  return next(e);
265
- return (async () => {
266
- if (!s.binding || !s.active || s.active.phase !== 'scheduled' || e.instructions !== s.active.marker || s.busy || (s.expectedWindow !== '' && projection(e.messages) !== s.expectedWindow)) {
267
- await transition($, s, 'unknown', 'Native compaction input changed or intent is not owned');
268
- return { skip: 'AI4AI did not authorize this replacement; original native context retained' };
269
- }
270
- await transition($, s, 'applied', 'Native compact hook supplied a fresh task window; successor adoption pending');
368
+ try {
369
+ const refuse = (detail) => {
370
+ void transition($, s, 'unknown', `Native compaction input changed or intent is not owned: ${detail}`).catch(() => undefined);
371
+ return { skip: `AI4AI did not authorize this replacement; original native context retained (${detail})` };
372
+ };
373
+ if (!s.binding)
374
+ return refuse('no native binding');
375
+ if (!s.active)
376
+ return refuse('no active handoff record');
377
+ // Fault-injection seam used only by the release gate: a caller that
378
+ // deliberately uses this operation id exercises the fail-closed catch.
379
+ // It is inert for every other operation id.
380
+ if (s.active.operationId === 'ai4ai-hook-fault-throw')
381
+ throw new Error('injected session.compact hook fault');
382
+ if (s.active.phase !== 'scheduled')
383
+ return refuse(`handoff phase is ${String(s.active.phase)}`);
384
+ if (e.instructions !== s.active.marker)
385
+ return refuse('marker does not match the owned intent');
386
+ if (s.busy)
387
+ return refuse('the plugin is busy with another native turn');
271
388
  s.appliedHere = true;
389
+ s.replacement = transition($, s, 'applied', 'Native compact hook supplied a fresh task window; successor adoption pending');
272
390
  return {
273
391
  messages: [{
274
392
  role: 'user',
@@ -276,27 +394,51 @@ export const register = on => {
276
394
  toolUses: [],
277
395
  }],
278
396
  };
279
- })().catch(() => ({ skip: 'AI4AI native gate failed closed; no replacement authorized' }));
397
+ }
398
+ catch (error) {
399
+ s.appliedHere = false;
400
+ const detail = String(error?.message ?? error).slice(0, 300);
401
+ dbg($, 'session.compact gate failed closed: ' + detail);
402
+ return { skip: 'AI4AI native gate failed closed; no replacement authorized (' + detail + ')' };
403
+ }
280
404
  });
281
405
  on('prompt.submit', async ($, e, next) => {
282
- const own = e.origin.kind === 'plugin' && e.origin.name === $.plugin.name;
406
+ const origin = e.origin ?? {};
407
+ const own = origin.kind === 'plugin' && origin.name === $.plugin.name;
408
+ const isDelivery = own && String(e.text ?? '').startsWith('AI4AI handoff delivery ');
283
409
  const ownCompact = e.command?.name === 'compact' && e.command.args === s.active?.marker && s.pumping;
284
- if (own && e.text.startsWith('AI4AI handoff delivery ')) {
285
- const allow = await serial(async () => e.text === s.delivery?.text && admitted(s) && await $.session.id() === s.binding?.session);
286
- if (!allow)
287
- return { drop: 'Superseded or uncertain AI4AI delivery; task not admitted' };
410
+ try {
411
+ if (isDelivery) {
412
+ // Delivery admission must prove the replacement actually happened in
413
+ // this session; anything uncertain drops the task instead of injecting
414
+ // it into a stale context.
415
+ const allow = await serial(async () => e.text === s.delivery?.text && admitted(s) && await $.session.id() === s.binding?.session);
416
+ if (!allow)
417
+ return { drop: 'Superseded or uncertain AI4AI delivery; task not admitted' };
418
+ }
419
+ else if (!own && !ownCompact) {
420
+ // A handoff is atomic once accepted: real user input never cancels it.
421
+ // Hold the prompt back and deliver it in the fresh context instead.
422
+ const retained = await serial(async () => {
423
+ if (!inHandoffWindow(s))
424
+ return false;
425
+ return s.retained.retain(RETAINED_SCOPE, e.text);
426
+ });
427
+ if (retained)
428
+ return { drop: 'AI4AI handoff is in progress; the input was retained and will be delivered in the fresh context' };
429
+ }
430
+ }
431
+ catch {
432
+ // Never fail open on the one path that injects handoff material.
433
+ if (isDelivery)
434
+ return { drop: 'AI4AI delivery admission failed closed; task not admitted' };
288
435
  }
289
- else if (!ownCompact && !s.restarting && !s.pumping)
290
- await serial(async () => { if (s.active && s.active.phase === 'pending')
291
- await transition($, s, 'cancelled', 'Later user input retained; handoff not replayed'); });
292
436
  return next(e);
293
437
  });
294
438
  on('session.end', async ($, e, next) => {
295
- // The /clear restart ends the source session on purpose; the successor
296
- // session owns the handoff now, so the source must not mark it unknown.
439
+ // The in-place replacement keeps this session; an unfinished handoff at
440
+ // session end is genuinely uncertain and never replayed.
297
441
  await serial(async () => {
298
- if (s.restarting || (s.active?.mechanism === 'restart' && s.delivery))
299
- return;
300
442
  if (s.active && !['completed', 'cancelled', 'failed', 'unknown'].includes(s.active.phase))
301
443
  await transition($, s, 'unknown', 'Native session ended; unfinished handoff is not resumed automatically');
302
444
  });
@@ -338,8 +480,13 @@ export const register = on => {
338
480
  if (!s.binding)
339
481
  throw new Error('AI4AI native binding is unavailable');
340
482
  const out = await rpc($, s.node, { caller: s.binding, instance: s.instance, action: 'request', request, ...usage }, s.bindingPath);
341
- if (out.record)
483
+ if (out.record) {
342
484
  s.active = out.record;
485
+ // An explicit cancel/stop or a failed request ends the window; retained
486
+ // input is discarded with the abandoned transition.
487
+ if (TERMINAL.includes(String(out.record.phase)))
488
+ s.retained.clear(RETAINED_SCOPE);
489
+ }
343
490
  dbg($, `tool result state=${String(out.result?.status)} record=${String(out.record?.phase)}`);
344
491
  return { result: JSON.stringify(out.result) };
345
492
  }).catch((error) => ({ result: JSON.stringify({ operation: e.operation, operationId: e.operationId, status: 'unknown', reason: 'AI4AI native handler failed: ' + String(error?.message ?? error).slice(0, 600), durable: false, modelVerification: 'unknown', verification: { model: 'unknown', context: 'reported' }, context: { window: null, used: null, percent: null, percentSource: null }, unavailable: [], notices: [] }) }));