@aisac/cli 0.4.0-beta.17 → 0.4.0-beta.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -108,7 +108,7 @@ older client requires a verified support migration; do not delete checkpoints,
108
108
  notes or lock files to work around a reported storage error.
109
109
 
110
110
  The reviewed native compatibility set is Claude Code 2.1.294, 2.1.295, 2.1.296,
111
- 2.1.299, 2.1.300, 2.1.301, 2.1.302, 2.1.303, 2.1.311 or 2.1.322, and Codex CLI 0.161.0,
111
+ 2.1.299, 2.1.300, 2.1.301, 2.1.302, 2.1.303, 2.1.311, 2.1.322 or 2.1.323, and Codex CLI 0.161.0,
112
112
  0.162.0, 0.162.1, 0.163.0, 0.164.0, 0.166.0 or 0.167.1 (0.165.0 and 0.167.0 were never
113
113
  qualified; 0.167.0 shares the 0.167.1 contract, so the structural probe admits it). A newer stable Codex 0.x release may continue only
114
114
  after its locally generated experimental protocol schemas and transport flags
@@ -143,6 +143,12 @@ and the [Claude 2.1.322 record](../../docs/reference/claude-322-compatibility-20
143
143
  (like `init/`), and lets a command exit with `3`. The qualified Claude Code and Codex
144
144
  versions are those of `0.4.0-beta.16`.
145
145
 
146
+ `0.4.0-beta.18` qualifies Claude Code 2.1.323. Its `claude plugin validate` type-checks the
147
+ hook modules, so the bundled plugin now type-checks under the host's tsconfig (typing only,
148
+ no behaviour change) and ships `provider-window.d.ts`; the host probe also reads an
149
+ inventory that the validator wraps across several notes. See the
150
+ [Claude 2.1.323 record](../../docs/reference/claude-323-compatibility-2026-11-12.md).
151
+
146
152
  The Codex terminal bridge permits the native session picker's separate read-only
147
153
  connection while keeping the primary conversation and monitor intact. A picker
148
154
  cannot compact, start a turn, inject history or take ownership of the primary
@@ -4508,11 +4508,19 @@ type ClaudeTelemetry = {
4508
4508
  disconnected(): boolean;
4509
4509
  flush(timeoutMs?: number): Promise<void>;
4510
4510
  };
4511
+ // The host tsconfig (lib es2023 only) declares no timers; the hook runtime provides them
4512
+ // on globalThis, so the handle stays opaque and the defaults are read from there.
4513
+ type ClaudeTimerHandle = unknown;
4511
4514
  type ClaudeTelemetryTimers = {
4512
- setTimeout(callback: () => void, delay: number): ReturnType<typeof setTimeout>;
4513
- clearTimeout(timer: ReturnType<typeof setTimeout>): void;
4515
+ setTimeout(callback: () => void, delay: number): ClaudeTimerHandle;
4516
+ clearTimeout(timer: ClaudeTimerHandle): void;
4514
4517
  };
4515
4518
 
4519
+ function hostTelemetryTimers(): ClaudeTelemetryTimers {
4520
+ const host = globalThis as unknown as ClaudeTelemetryTimers;
4521
+ return { setTimeout: host.setTimeout, clearTimeout: host.clearTimeout };
4522
+ }
4523
+
4516
4524
  const TELEMETRY_HELPER_MAX_STDOUT_BYTES = 8 * 1024;
4517
4525
 
4518
4526
  type TelemetryHelperConfiguration = 'none' | 'valid' | 'invalid';
@@ -4677,7 +4685,7 @@ export function createClaudeTelemetryReporter(
4677
4685
  getSessionId: () => PromiseLike<string> | string,
4678
4686
  sendReport: (payload: Record<string, unknown>) => PromiseLike<unknown> | unknown,
4679
4687
  now: () => number = () => Date.now(),
4680
- timers: ClaudeTelemetryTimers = { setTimeout, clearTimeout },
4688
+ timers: ClaudeTelemetryTimers = hostTelemetryTimers(),
4681
4689
  ): ClaudeTelemetry {
4682
4690
  const active =
4683
4691
  enabled === true &&
@@ -4752,7 +4760,7 @@ export function createClaudeTelemetryReporter(
4752
4760
  if (attempt.expired) return;
4753
4761
  if (!telemetryAckAccepted(response)) throw new Error('telemetry_report_rejected');
4754
4762
  })();
4755
- let timer: ReturnType<typeof setTimeout> | undefined;
4763
+ let timer: ClaudeTimerHandle | undefined;
4756
4764
  void (async () => {
4757
4765
  try {
4758
4766
  await Promise.race([
@@ -1,4 +1,4 @@
1
- import { register as registerContext } from './context-compaction.ts';
1
+ import { register as registerContext } from './context-compaction.js';
2
2
 
3
3
  export function register(on: Parameters<typeof registerContext>[0]): void {
4
4
  return registerContext(on, {
@@ -10,7 +10,7 @@ const contractTest: Parameters<typeof test>[2] = async ($, on) => {
10
10
  on('session.usage', () => ({
11
11
  value: (() => {
12
12
  usageCalls += 1;
13
- return { context: { percent: 90, tokens: 900, window: 1_000 } };
13
+ return { startedAt: 0, context: { percent: 90, tokens: 900, window: 1_000 }, rateLimits: [] };
14
14
  })(),
15
15
  }));
16
16
  on('ui.log', () => ({ value: undefined }));
@@ -23,17 +23,21 @@ const contractTest: Parameters<typeof test>[2] = async ($, on) => {
23
23
  };
24
24
  });
25
25
  on('turn.complete', () => ({ text: '' }));
26
- const prompt = await $.prompt.submit({ text: 'native-host-contract-input' });
26
+ const prompt = await $.prompt.submit({
27
+ text: 'native-host-contract-input',
28
+ wait: false,
29
+ origin: { kind: 'composer' },
30
+ });
27
31
  const tool = await $.tool.call({ tool: 'Read', file_path: 'native-host-contract.txt' });
28
32
  await $.turn.complete({
29
33
  turnId: 'native-contract-turn',
30
34
  answer: 'native-turn-contract-ok',
31
35
  durationMs: 1,
32
36
  isAborted: false,
33
- usage: null,
37
+ reason: 'answer',
34
38
  });
35
39
  expect(prompt.text).toBe('native-host-contract-ok');
36
- expect(tool.result.content).toBe('native-host-tool-ok');
40
+ expect((tool.result as { readonly content: unknown }).content).toBe('native-host-tool-ok');
37
41
  expect(usageCalls).toBe(1);
38
42
  expect(compactCalls).toBe(1);
39
43
  const monotonicEnd = globalThis.performance?.now?.();
@@ -0,0 +1,83 @@
1
+ import type { ProviderFitOptions, ProviderFitPreflight, ProviderFitProjection, ProviderFitProjectionMessage, ProviderFitProjectionPair } from './state-fitting.mjs';
2
+ export declare const PROVIDER_WINDOW_MAX_PAIRS = 200;
3
+ export declare const PROVIDER_WINDOW_MAX_MESSAGES = 1000;
4
+ export declare const PROVIDER_WINDOW_MAX_REFERENCES = 200;
5
+ export declare const PROVIDER_WINDOW_MAX_REQUEST_BYTES: number;
6
+ export declare const PROVIDER_WINDOW_REQUEST_HEADROOM_BYTES: number;
7
+ export declare const PROVIDER_WINDOW_MAX_SEARCH_ATTEMPTS = 12;
8
+ export declare const PROVIDER_WINDOW_MAX_STATE_TOKENS = 25000;
9
+ export declare const PROVIDER_WINDOW_MAX_REQUEST_TOKENS = 30000;
10
+ export declare const PROVIDER_WINDOW_MAX_RESERVED_TOKENS = 120000;
11
+ export declare const PROVIDER_WINDOW_OUTPUT_TOKEN_ALLOWANCE = 4000;
12
+ export type ProviderWindowMessage = ProviderFitProjectionMessage;
13
+ export interface ProviderWindowPair extends ProviderFitProjectionPair {
14
+ readonly callId: string;
15
+ readonly resultId: string;
16
+ readonly callMessage: number;
17
+ readonly resultMessage: number;
18
+ readonly resultText: string;
19
+ readonly protectedPair: boolean;
20
+ }
21
+ export interface ProviderWindowProjection {
22
+ readonly goal: string;
23
+ readonly messages: readonly ProviderWindowMessage[];
24
+ readonly pairs: readonly ProviderWindowPair[];
25
+ readonly protectedItemCount: number;
26
+ }
27
+ export interface ProviderWindowWireProjection {
28
+ readonly goal: string;
29
+ readonly messages: readonly {
30
+ readonly id: string;
31
+ readonly role: 'user' | 'assistant';
32
+ readonly text: string;
33
+ readonly call_ids: readonly string[];
34
+ readonly result_ids: readonly string[];
35
+ }[];
36
+ readonly pairs: readonly {
37
+ readonly id: string;
38
+ readonly tool: string;
39
+ readonly input_text: string;
40
+ readonly result_chars: number;
41
+ readonly result_is_error: boolean;
42
+ readonly eligibility: 'reproducible_read' | 'compatible_tool' | 'protected';
43
+ readonly pin_reasons: readonly string[];
44
+ }[];
45
+ readonly protected_item_count: number;
46
+ }
47
+ export interface ProviderWindowOptions extends ProviderFitOptions {
48
+ readonly preserveRecentMessages: number;
49
+ readonly maxPairs?: number;
50
+ readonly maxMessages?: number;
51
+ readonly maxReferencesPerMessage?: number;
52
+ readonly maxRequestBytes?: number;
53
+ readonly requestHeadroomBytes?: number;
54
+ readonly maxReservedTokens?: number;
55
+ /** Shared capacity snapshot limits. These are advisory; backend admission remains authoritative. */
56
+ readonly maxBatchesPerOperation?: number;
57
+ readonly outputTokenAllowance?: number;
58
+ }
59
+ export interface ProviderWindowPreflight extends ProviderFitPreflight {
60
+ readonly requestBytes: number;
61
+ readonly estimatedReservationTokens: number;
62
+ }
63
+ export interface ProviderWindowSuccess {
64
+ readonly ok: true;
65
+ readonly projection: ProviderWindowWireProjection;
66
+ readonly pairs: readonly ProviderWindowPair[];
67
+ readonly deferredPairs: readonly ProviderWindowPair[];
68
+ readonly preflight: ProviderWindowPreflight;
69
+ readonly attempts: number;
70
+ readonly anchorPairCount: number;
71
+ readonly selectedEligibleCount: number;
72
+ }
73
+ export type ProviderWindowFailureReason = 'anchor_overflow' | 'message_limit_exceeded' | 'no_feasible_window';
74
+ export interface ProviderWindowFailure {
75
+ readonly ok: false;
76
+ readonly reason: ProviderWindowFailureReason;
77
+ readonly attempts: number;
78
+ readonly anchorPairCount: number;
79
+ }
80
+ export type ProviderWindowResult = ProviderWindowSuccess | ProviderWindowFailure;
81
+ type ProviderFit = (projection: ProviderFitProjection, eligible: readonly ProviderFitProjectionPair[], options: ProviderFitOptions) => ProviderFitPreflight;
82
+ export declare function prepareProviderWindow(input: ProviderWindowProjection, options: ProviderWindowOptions, fit?: ProviderFit): ProviderWindowResult;
83
+ export {};
@@ -32,6 +32,7 @@ const QUALIFIED_VERSIONS = new Set([
32
32
  '2.1.303',
33
33
  '2.1.311',
34
34
  '2.1.322',
35
+ '2.1.323',
35
36
  ]);
36
37
  const REQUIRED_FLAGS = ['--settings', '--mcp-config', '--allowedTools', '--plugin-dir'];
37
38
  const REQUIRED_INVENTORY = [
@@ -59,6 +60,7 @@ const ALLOWED_PLUGIN_FILES = Object.freeze([
59
60
  'hooks/hooks.json',
60
61
  'hooks/context-compaction.ts',
61
62
  'hooks/provider-window.js',
63
+ 'hooks/provider-window.d.ts',
62
64
  'hooks/state-fitting.mjs',
63
65
  'hooks/state-fitting.d.mts',
64
66
  'hooks/native-host-contract.test.ts',
@@ -331,24 +333,30 @@ async function runHostProbe(executable, pluginRoot, limits = {}) {
331
333
  ];
332
334
  if (errors.length > 0) return { ok: false, reason: 'plugin_validation_failed' };
333
335
  const notes = contents.flatMap((item) => item.notes);
334
- const hookNote = notes.find((note) => typeof note === 'string' && note.includes(' hooks: '));
335
- const callNote = notes.find((note) => typeof note === 'string' && note.includes(' calls: '));
336
+ // Claude 2.1.323 wraps a long inventory into several notes that repeat the
337
+ // "<module> hooks: " or "<module> calls: " prefix, so read every matching note.
338
+ /** @param {string} marker */
339
+ const inventoryNotes = (marker) =>
340
+ notes.filter(
341
+ /** @returns {note is string} */
342
+ (note) => typeof note === 'string' && note.includes(marker),
343
+ );
336
344
  const hooks = new Set(
337
- typeof hookNote === 'string'
338
- ? hookNote
339
- .split(' hooks: ', 2)[1]
340
- .split(', ')
341
- .map((item) => item.trim())
342
- : [],
345
+ inventoryNotes(' hooks: ').flatMap((note) =>
346
+ note
347
+ .split(' hooks: ', 2)[1]
348
+ .split(', ')
349
+ .map((item) => item.trim()),
350
+ ),
343
351
  );
344
352
  const calls = new Set(
345
- typeof callNote === 'string'
346
- ? callNote
347
- .split(' calls: ', 2)[1]
348
- .replace(/\s+\(via[^)]*\)/gu, '')
349
- .split(', ')
350
- .map((item) => item.trim())
351
- : [],
353
+ inventoryNotes(' calls: ').flatMap((note) =>
354
+ note
355
+ .split(' calls: ', 2)[1]
356
+ .replace(/\s+\(via[^)]*\)/gu, '')
357
+ .split(', ')
358
+ .map((item) => item.trim()),
359
+ ),
352
360
  );
353
361
  const inventory = new Set([...hooks, ...calls]);
354
362
  if (inventory.size === 0 || REQUIRED_INVENTORY.some((item) => !inventory.has(item)))
@@ -16,7 +16,7 @@ export const MAX_LOG_FILES = 3;
16
16
  const LOCK_WAIT_MS = 250;
17
17
  const LOCK_STALE_MS = 30_000;
18
18
  const ADMISSION_MS = 60 * 60 * 1000;
19
- export const ADAPTER_VERSION = '0.4.0-beta.17';
19
+ export const ADAPTER_VERSION = '0.4.0-beta.18';
20
20
  const MAX_DIAGNOSTIC_COUNT = 10_000_000;
21
21
  const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
22
22
  const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);
@@ -206,6 +206,7 @@ const SAFE_ERROR_CODES = new Set([
206
206
  'mcp_tool_unavailable',
207
207
  'mcp_feature_disabled',
208
208
  'mcp_paid_plan_required',
209
+ 'mcp_invalid_input',
209
210
  'provider_error',
210
211
  'helper_failed',
211
212
  ]);
package/dist/cli.mjs CHANGED
@@ -25,7 +25,7 @@ import { launchClaude, launchCodex } from './launch.mjs';
25
25
  import { claudeCompatibilityError, resolveClaudeCompatibility } from './claude-compatibility.mjs';
26
26
  import { codexCompatibilityError, resolveCodexCompatibility } from './codex-compatibility.mjs';
27
27
  import { providerFreeProbe } from './mcp.mjs';
28
- import { tokenFailureGuide, tokenPromptGuide } from './token-guide.mjs';
28
+ import { setupFailureHint, tokenFailureGuide, tokenPromptGuide } from './token-guide.mjs';
29
29
  import { codexPolicyJson, makePolicy, publicPolicy, isProfile } from './policy.mjs';
30
30
  import { readDiagnostics } from './claude-observation.mjs';
31
31
  import { readCodexDiagnostics } from './codex-diagnostics.mjs';
@@ -45,7 +45,7 @@ import { anyFormatter } from './guardrails/format.mjs';
45
45
  import { readCodexGuardrails } from './guardrails-plugin.mjs';
46
46
  import { codexHooksStatus, supportsCodexHooks } from './codex-hooks.mjs';
47
47
 
48
- const VERSION = '0.4.0-beta.17';
48
+ const VERSION = '0.4.0-beta.18';
49
49
  // The command is `aisac`; `aibrain` is an alias installed from the same entry.
50
50
  const COMMAND = 'aisac';
51
51
  /** `aisac scan` could not scan as asked (scan spec D6); 1 means findings, 2 a usage error. */
@@ -138,7 +138,7 @@ async function maskedPrompt() {
138
138
  */
139
139
  function setupTokenError(code, locale, endpoint) {
140
140
  const error = new Error(code);
141
- const guide = tokenFailureGuide(code, locale, endpoint);
141
+ const guide = tokenFailureGuide(code, locale, endpoint) ?? setupFailureHint(code, locale);
142
142
  if (guide !== null) Object.defineProperty(error, 'guide', { value: guide });
143
143
  return error;
144
144
  }
package/dist/mcp.mjs CHANGED
@@ -556,11 +556,14 @@ function structuredErrorCode(result) {
556
556
  const text = result.content.find((item) => isObject(item) && typeof item.text === 'string')?.text;
557
557
  const prefix =
558
558
  typeof text === 'string'
559
- ? /^(FEATURE_DISABLED|TOOL_UNAVAILABLE|PAID_PLAN_REQUIRED)(?::|$)/u.exec(text)?.[1]
559
+ ? /^(FEATURE_DISABLED|TOOL_UNAVAILABLE|PAID_PLAN_REQUIRED|INVALID_INPUT)(?::|$)/u.exec(
560
+ text,
561
+ )?.[1]
560
562
  : undefined;
561
563
  if (prefix === 'FEATURE_DISABLED') return 'mcp_feature_disabled';
562
564
  if (prefix === 'TOOL_UNAVAILABLE') return 'mcp_tool_unavailable';
563
565
  if (prefix === 'PAID_PLAN_REQUIRED') return 'mcp_paid_plan_required';
566
+ if (prefix === 'INVALID_INPUT') return 'mcp_invalid_input';
564
567
  return undefined;
565
568
  }
566
569
 
@@ -923,7 +926,12 @@ export async function providerFreeProbeV2(endpoint, token, policy, clients) {
923
926
  name === 'brain_context_select',
924
927
  )
925
928
  )
926
- throw new Error(responseError(response.response, 'mcp_v2_unsupported'));
929
+ // A tool error carries the server's own code (paid plan, cohort, clock
930
+ // skew, disabled feature); only a reply that breaks the v2 contract is
931
+ // `mcp_v2_unsupported`. Same precedence as the v1 probe.
932
+ throw new Error(
933
+ responseError(response.response, structuredErrorCode(result) ?? 'mcp_v2_unsupported'),
934
+ );
927
935
  };
928
936
  await callTool(2, 'brain_context_select', {
929
937
  schema_version: 2,
package/dist/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "@aisac/cli",
3
- "version": "0.4.0-beta.17",
3
+ "version": "0.4.0-beta.18",
4
4
  "type": "module"
5
5
  }
package/dist/platform.mjs CHANGED
@@ -128,7 +128,7 @@ export function nativeVersion(executable, environment = process.env) {
128
128
  export function isTestedNativeVersion(client, version) {
129
129
  const value = version.trim();
130
130
  if (client === 'claude')
131
- return /^(?:(?:claude(?:\s+code)?)\s+)?2\.1\.(?:294|295|296|299|300|301|302|303|311|322)(?:\s+\(Claude\s+Code\))?$/iu.test(
131
+ return /^(?:(?:claude(?:\s+code)?)\s+)?2\.1\.(?:294|295|296|299|300|301|302|303|311|322|323)(?:\s+\(Claude\s+Code\))?$/iu.test(
132
132
  value,
133
133
  );
134
134
  return /^(?:codex(?:-cli)?\s+)?0\.16(?:1\.0|2\.0|2\.1|3\.0|4\.0|6\.0|7\.1)$/iu.test(value);
@@ -146,6 +146,7 @@ const TESTED_NATIVE_VERSIONS = Object.freeze({
146
146
  '2.1.303',
147
147
  '2.1.311',
148
148
  '2.1.322',
149
+ '2.1.323',
149
150
  ]),
150
151
  codex: Object.freeze([
151
152
  '0.161.0',
@@ -15,6 +15,16 @@ const TOKEN_FAILURES = Object.freeze({
15
15
  'provider_free_probe_failed:mcp_paid_plan_required': 'unlicensed',
16
16
  });
17
17
 
18
+ /**
19
+ * Setup failures that are not about the token but have one usual cause worth
20
+ * naming. `INVALID_INPUT` from the probe is almost always a system clock that
21
+ * is ahead of the server (the server rejects `observed_at` more than 30 s in
22
+ * the future); WSL2 drifts after a sleep.
23
+ */
24
+ const SETUP_HINTS = Object.freeze({
25
+ 'provider_free_probe_failed:mcp_invalid_input': 'clock',
26
+ });
27
+
18
28
  const TEXT = Object.freeze({
19
29
  'pt-BR': {
20
30
  intro: 'O aisac precisa de um token pessoal (PAT) do seu AI Brain.',
@@ -38,6 +48,10 @@ const TEXT = Object.freeze({
38
48
  unlicensed:
39
49
  'Este token pertence a uma conta sem a licença. Gere o token entrando com o e-mail usado na compra.',
40
50
  },
51
+ hints: {
52
+ clock:
53
+ 'O AI Brain recusou a sondagem como entrada inválida (INVALID_INPUT). Causa mais comum: o relógio do sistema está adiantado em relação ao servidor; no WSL2 isso acontece depois de suspender o computador. Acerte o relógio (ex.: `sudo hwclock -s` ou reinicie o WSL) e rode `aisac setup` de novo. O token não precisa mudar.',
54
+ },
41
55
  },
42
56
  en: {
43
57
  intro: 'aisac needs a personal access token (PAT) from your AI Brain.',
@@ -60,6 +74,10 @@ const TEXT = Object.freeze({
60
74
  unlicensed:
61
75
  'This token belongs to an account without the license. Create the token signed in with the purchase email.',
62
76
  },
77
+ hints: {
78
+ clock:
79
+ 'AI Brain rejected the probe as invalid input (INVALID_INPUT). Most common cause: the system clock is ahead of the server; on WSL2 this happens after the computer sleeps. Fix the clock (e.g. `sudo hwclock -s` or restart WSL) and run `aisac setup` again. The token does not need to change.',
80
+ },
63
81
  },
64
82
  });
65
83
 
@@ -92,6 +110,15 @@ export function tokenPromptGuide(locale, endpoint) {
92
110
  return steps(locale, endpoint, 'prompt');
93
111
  }
94
112
 
113
+ /**
114
+ * One-paragraph hint for a setup failure with a usual non-token cause, or null.
115
+ * @param {string} code @param {GuideLocale} locale
116
+ */
117
+ export function setupFailureHint(code, locale) {
118
+ const hint = /** @type {Record<string, keyof typeof TEXT.en.hints>} */ (SETUP_HINTS)[code];
119
+ return hint === undefined ? null : TEXT[locale].hints[hint];
120
+ }
121
+
95
122
  /**
96
123
  * Guidance for a setup failure caused by a missing, rejected or unlicensed token,
97
124
  * or null when the failure has another cause.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aisac/cli",
3
- "version": "0.4.0-beta.17",
3
+ "version": "0.4.0-beta.18",
4
4
  "private": false,
5
5
  "description": "AISAC client for Claude Code and Codex: AI Brain memory, context management and AISAC Engineering",
6
6
  "license": "UNLICENSED",