@aisac/cli 0.0.0-stage → 0.4.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +202 -2
  2. package/dist/assets/claude/.claude-plugin/plugin.json +147 -0
  3. package/dist/assets/claude/hooks/context-compaction.ts +6934 -0
  4. package/dist/assets/claude/hooks/hooks.json +3 -0
  5. package/dist/assets/claude/hooks/native-host-contract-runtime.ts +18 -0
  6. package/dist/assets/claude/hooks/native-host-contract.test.ts +51 -0
  7. package/dist/assets/claude/hooks/provider-window.js +263 -0
  8. package/dist/assets/claude/hooks/state-fitting.d.mts +47 -0
  9. package/dist/assets/claude/hooks/state-fitting.mjs +324 -0
  10. package/dist/assets/codex-context-compaction.mjs +4786 -0
  11. package/dist/assets/context-selection-fitting.mjs +194 -0
  12. package/dist/assets/context-state-fitting.mjs +324 -0
  13. package/dist/assets/context-telemetry-reporter.mjs +305 -0
  14. package/dist/assets/jev-paid-pilot-terminal.mjs +1066 -0
  15. package/dist/claude-checkpoint.mjs +1338 -0
  16. package/dist/claude-compatibility.mjs +506 -0
  17. package/dist/claude-observation.mjs +1338 -0
  18. package/dist/cli.mjs +805 -0
  19. package/dist/codex-compatibility.mjs +531 -0
  20. package/dist/codex-diagnostics.mjs +447 -0
  21. package/dist/codex-engineering.mjs +165 -0
  22. package/dist/codex-permissions.mjs +590 -0
  23. package/dist/codex-protocol-fingerprint.json +131 -0
  24. package/dist/context-telemetry.mjs +257 -0
  25. package/dist/engineering-pack-public-key.json +10 -0
  26. package/dist/engineering-pack.mjs +845 -0
  27. package/dist/engineering.mjs +194 -0
  28. package/dist/extensions-catalog.mjs +310 -0
  29. package/dist/extensions-cli.mjs +486 -0
  30. package/dist/extensions-preferences.mjs +151 -0
  31. package/dist/guardrails/continuity.mjs +239 -0
  32. package/dist/guardrails/format.mjs +111 -0
  33. package/dist/guardrails/guards.mjs +397 -0
  34. package/dist/guardrails/run.mjs +211 -0
  35. package/dist/guardrails/shell-words.mjs +206 -0
  36. package/dist/guardrails-plugin.mjs +149 -0
  37. package/dist/launch.mjs +786 -0
  38. package/dist/mcp-servers.mjs +192 -0
  39. package/dist/mcp.mjs +962 -0
  40. package/dist/monitor.mjs +166 -0
  41. package/dist/package.json +5 -0
  42. package/dist/platform.mjs +156 -0
  43. package/dist/policy.mjs +218 -0
  44. package/dist/state.mjs +408 -0
  45. package/dist/telemetry-report.mjs +133 -0
  46. package/package.json +24 -4
package/README.md CHANGED
@@ -1,3 +1,203 @@
1
- # Temporary Holding Version
1
+ # aisac
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The AISAC client for Claude Code and Codex on Linux/WSL, and for Claude Code on
4
+ macOS, with Node.js 22 or newer:
5
+ AI Brain memory, context management and, for AISAC Founding Cohort members,
6
+ AISAC Engineering.
7
+
8
+ The command is `aisac`. `aibrain` is an alias for the same program, so existing
9
+ scripts and habits keep working. The same files are published as `@aisac/cli`
10
+ and, for existing installs, `@brunobracaioli/aibrain`. Install only one of them:
11
+ both provide the `aisac` and `aibrain` commands. State stays in `~/.aibrain`.
12
+
13
+ `aisac setup` and `aisac doctor` report the AISAC Engineering license
14
+ (`active`, `inactive` or `unavailable`). The server decides; the client only
15
+ shows the answer and sends the request only to the configured AI Brain address.
16
+ `aisac status` stays offline.
17
+
18
+ For licensed accounts, `aisac claude` downloads the AISAC Engineering pack for
19
+ the session, verifies its Ed25519 signature against the key pinned in this
20
+ release, and loads it as the `aisac-engineering` plugin from the session's
21
+ private folder, which is deleted on exit. Any failure starts Claude without the
22
+ pack. `aisac setup --lang pt-BR|en` picks the pack language without a network
23
+ call. The pack is never part of this npm package.
24
+
25
+ `aisac codex` (Codex 0.164.0 or later) loads the same verified pack for that
26
+ session only: its skills are added to the Codex app-server the launch owns
27
+ (call one with `$`, for example `$spec`) and its agents become session agent
28
+ roles. Nothing is written to `~/.codex`, `~/.agents` or the project, and the
29
+ session's folder is deleted on exit. An older Codex starts without the pack and
30
+ says `codex_outdated`.
31
+
32
+ Licensed `aisac claude` sessions also load guardrail hooks as the session plugin
33
+ `aisac-guardrails`.
34
+ - **Default on:** `secrets-guard` refuses secret files by name. Four more hooks
35
+ keep continuity: a repository snapshot at start and after a compaction, a
36
+ docs reminder, and the NOTES/spec/CHANGELOG pass.
37
+ - **Default off:** `git-guard`, `destructive-guard` and `format-on-edit`.
38
+ - **Changing them:** `aisac hooks` lists them, and `aisac hooks enable|disable
39
+ <id>` or `aisac hooks reset` changes the next session. The agent cannot change
40
+ them from inside a session.
41
+ - **Code:** it ships in this package and runs locally. Nothing comes from the
42
+ server.
43
+
44
+ Licensed sessions of `aisac claude` and `aisac codex` can also load reviewed MCP
45
+ servers: `github` (read-only, token in `GITHUB_PERSONAL_ACCESS_TOKEN`), `supabase`
46
+ (read-only), `vercel`, `playwright` (pinned, isolated) and `context7`.
47
+ - **Default:** every server is off. `aisac mcp` lists them, `aisac mcp enable|disable
48
+ <id>` or `aisac mcp reset` changes the next session, and `aisac mcp info <id>` says
49
+ what a server reaches and how to log in.
50
+ - **Login:** the host does it (`/mcp` in Claude Code, `aisac mcp login <id>` for Codex)
51
+ and keeps it in its own store. No token reaches `~/.aibrain` or AISAC.
52
+
53
+ Codex capture also requires the `flock` utility from `util-linux`, normally
54
+ included in Linux/WSL. The launcher and doctor check availability before a
55
+ monitored Codex session starts. Capture coordination is released by the kernel
56
+ after a process exits unexpectedly. An unidentifiable empty lock left by an
57
+ older client requires a verified support migration; do not delete checkpoints,
58
+ notes or lock files to work around a reported storage error.
59
+
60
+ The reviewed native compatibility set is Claude Code 2.1.294, 2.1.295, 2.1.296,
61
+ 2.1.299, 2.1.300, 2.1.301, 2.1.302 or 2.1.303, and Codex CLI 0.161.0,
62
+ 0.162.0, 0.162.1, 0.163.0, 0.164.0 or 0.166.0 (0.165.0 was never qualified). A newer stable Codex 0.x release may continue only
63
+ after its locally generated experimental protocol schemas and transport flags
64
+ match the bundled adapter contract; prereleases, older releases and new majors
65
+ remain rejected. Starting with beta14, newer stable Claude 2.1 patches can
66
+ continue after isolated strict plugin validation, required hook/API checks and
67
+ an enabled-hook test in the native offline runner. Doctor distinguishes
68
+ `host_checked` from `qualified`; this check does not establish full behavioral
69
+ equivalence with a tested native release. Unknown older patches, prereleases
70
+ and other major/minor families remain rejected. No credentials, conversations,
71
+ model requests or JEV calls are used by these compatibility probes.
72
+
73
+ Beta17 refreshes the Codex contract to 0.164.0, including its image-generation
74
+ record formats. Native launch/resume qualification is separate from a new
75
+ model/JEV compaction qualification. A later native release that changes the
76
+ consumed contract can still require an AI Brain compatibility update.
77
+
78
+ `0.4.0-beta.9` refreshes the bundled contract to Codex 0.166.0. Its delta is
79
+ additive: optional item timing, an image generation id, an attach-to-source fork
80
+ flag and two error codes. See the
81
+ [Codex 0.166 qualification record](../../docs/reference/codex-166-compatibility-2026-11-04.md).
82
+
83
+ The Codex terminal bridge permits the native session picker's separate read-only
84
+ connection while keeping the primary conversation and monitor intact. A picker
85
+ cannot compact, start a turn, inject history or take ownership of the primary
86
+ connection. Its failure or timeout closes only that auxiliary connection.
87
+
88
+ ```sh
89
+ # Install the published beta:
90
+ npm install -g @aisac/cli@beta
91
+ aisac setup --client both
92
+ aisac doctor --json
93
+ aisac claude
94
+ aisac codex
95
+ ```
96
+
97
+ To move from `@brunobracaioli/aibrain` to `@aisac/cli`, close running sessions,
98
+ then run `npm uninstall -g @brunobracaioli/aibrain` before
99
+ `npm install -g @aisac/cli@beta`. Setup, notes and checkpoints are kept.
100
+
101
+ Installation does not contact AI Brain, change native client configuration, or
102
+ enable all paid accounts. Setup requires an existing AI Brain PAT, explicit
103
+ versioned disclosure, and successful provider-free pilot access. Claude and
104
+ Codex continue to own their own authentication. Windows native is unsupported;
105
+ run the beta inside WSL. On macOS, `aisac setup` configures Claude Code, and
106
+ `aisac codex` is refused with `CODEX_MACOS_UNSUPPORTED`. Codex capture needs
107
+ Linux procfs and `flock`, so use Codex from Linux/WSL. Pricing and general customer activation are outside
108
+ this beta.
109
+
110
+ For reviewed noninteractive automation only, use a private token file and
111
+ explicitly acknowledge the displayed disclosure with
112
+ `aibrain setup --client both --token-file /private/path/brain.pat
113
+ --accept-disclosure`.
114
+
115
+ For a CI-reviewed tarball, use `aisac-cli-*.tgz` with
116
+ `npm install -g ./aisac-cli-*.tgz` (the same files are also packed as
117
+ `brunobracaioli-aibrain-*.tgz`); registry installation is gated on the
118
+ operator's npm review and authentication.
119
+
120
+ For users of an earlier unscoped review tarball, close its client sessions,
121
+ run `npm uninstall -g aibrain`, and install this scoped package. Local
122
+ `~/.aibrain` state, notes, and checkpoints are retained.
123
+
124
+ This `0.3` client adds configurable context profiles. A fresh
125
+ setup defaults to `upstream`: 60% trigger, 0.5 keep threshold, six recent items
126
+ protected, and broader completed text-tool eligibility in Claude. Existing
127
+ schema1 configurations keep their previous behavior. After a reviewed v2 backend
128
+ and client release, opt in explicitly with:
129
+
130
+ ```sh
131
+ aibrain setup --client both --context-profile upstream
132
+ # Or retain conservative retention with the v2 protocol:
133
+ aibrain setup --client both --context-profile conservative
134
+ ```
135
+
136
+ Use `aibrain --help` for individual overrides. Claude-only flags are rejected for
137
+ Codex-only setup. Status and doctor show effective settings without custom goal
138
+ text; they do not claim that a live session is being monitored. Codex keeps native
139
+ compaction and recovery notes in the same thread. The backend checks paid access
140
+ and unchanged shared quotas before any JEV request.
141
+
142
+ The `0.3.0-beta.14` Claude launcher uses the durable context strategy and
143
+ records bounded recovery reasons when native summary proof cannot be confirmed:
144
+ JEV selects compatible historical tool evidence, bounded private notes retain
145
+ the selected text, and Claude core summarizes the reduced input. The next
146
+ prompt restores those notes in the same session after verifying native state.
147
+ The final native context contains a summary; this is not summary-free transcript
148
+ replacement. Direct hook-owned history replacement remains experimental because
149
+ resume can replay older content in affected Claude versions.
150
+
151
+ The notes preserve only the selected retained text that fits the local bound;
152
+ oversized entries are omitted as whole entries and counted. The separate full
153
+ checkpoint has its own retention. Neither path guarantees perfect preservation
154
+ of every internal host field. Shadow prefiltering continues to observe without
155
+ changing tool results. Native qualification and publication evidence is tracked
156
+ in the [release record](https://github.com/brunobracaioli/mcp-ai-brain/blob/main/docs/reference/claude-durable-context-2026-10-14.md).
157
+
158
+ The launcher grants the native clients the provider-free `brain_context_budget`
159
+ read alongside the existing context tools. It is a short-lived advisory snapshot,
160
+ not a billing meter, reservation, or provider authorization; atomic admission
161
+ remains authoritative.
162
+
163
+ Codex diagnostics are kept in the launched adapter's private state directory.
164
+ `aibrain diagnostics --client codex --json` shows only bounded stages, closed
165
+ reasons, pseudonymous session identifiers, client versions, and small numeric
166
+ counters. Prompts, notes, paths, credentials, raw errors, and app-server stdout
167
+ are excluded.
168
+
169
+ Beta12 reads large Codex histories in bounded pages and keeps their complete
170
+ contents in verified private capture segments. It checks history again before
171
+ selection and before native compaction; notes and recovery stay in the same
172
+ thread. Older captures remain readable. A single turn exceeding 8 MiB, a capture
173
+ exceeding the bounded page/item/128 MiB limits, or exhausted private storage is
174
+ reported explicitly. Such a failure does not authorize discarding protected
175
+ history or retrying a paid operation. The private capture directory remains
176
+ bounded to 256 MiB and 128 managed files, with current recovery references
177
+ protected from cleanup.
178
+
179
+ Claude plan diagnostics distinguish response parsing, identity, expiry and
180
+ history changes. A text JSON plan can use the same 256 KiB limit as structured
181
+ plans; smaller budget/error envelopes retain their separate limits. These local
182
+ diagnostics contain format names and numeric sizes, never plan contents.
183
+
184
+ Context dashboard telemetry is disabled for fresh and existing configurations.
185
+ Enable it only after reviewing the extended disclosure:
186
+
187
+ ```sh
188
+ aibrain setup --client both --telemetry on --accept-disclosure
189
+ ```
190
+
191
+ Omit `--telemetry` to preserve the stored choice, or use `--telemetry off` to stop
192
+ future-launch reports. Settings are captured when a client starts, so close and
193
+ restart currently monitored sessions after opting out to stop their reporting.
194
+ Enabled reports use the existing authenticated MCP transport and
195
+ contain only a hashed native session key, random lifecycle identifiers, native
196
+ client version, phase, timestamps, numeric counts, and allowed measurements or
197
+ reasons. Prompts, notes, paths, tool names, credentials, and raw errors are not
198
+ reported. The dashboard shows a 30-day visible window; physical cleanup runs on
199
+ the next successful daily cleanup. Delivery failure never fails or triggers a
200
+ context operation.
201
+
202
+ Read the [canonical subscriber beta guide](https://github.com/brunobracaioli/mcp-ai-brain/blob/main/docs/how-to/aibrain-subscriber-beta.md)
203
+ for setup, support, disclosure, limits, and disable procedures.
@@ -0,0 +1,147 @@
1
+ {
2
+ "name": "ai-brain-context-compaction",
3
+ "version": "0.3.0-beta.14",
4
+ "author": { "name": "AISAC" },
5
+ "description": "AI Brain paid-plan context monitoring with conservative Claude compaction fallback.",
6
+ "hooks": "./hooks/hooks.json",
7
+ "userConfig": {
8
+ "policyVersion": {
9
+ "type": "number",
10
+ "title": "Context policy version",
11
+ "description": "Use 2 for configurable broader parity; omit or use 1 to preserve legacy behavior.",
12
+ "default": 1
13
+ },
14
+ "brainServer": {
15
+ "type": "string",
16
+ "title": "AI Brain MCP server",
17
+ "description": "The name of the already authenticated AI Brain MCP server. The hook uses that connection and never accepts a JEV key.",
18
+ "default": "brain"
19
+ },
20
+ "compactAtPercent": {
21
+ "type": "number",
22
+ "title": "Context threshold",
23
+ "description": "Request host compaction at or above this reported context percentage.",
24
+ "default": 85
25
+ },
26
+ "keepThreshold": {
27
+ "type": "number",
28
+ "title": "JEV keep threshold",
29
+ "description": "V2 score threshold for retaining eligible content.",
30
+ "default": 0.5
31
+ },
32
+ "preserveRecentMessages": {
33
+ "type": "number",
34
+ "title": "Recent messages to preserve",
35
+ "description": "Number of recent messages pinned before scoring.",
36
+ "default": 6
37
+ },
38
+ "minReductionRatio": {
39
+ "type": "number",
40
+ "title": "Minimum reduction ratio",
41
+ "description": "Minimum configured reduction required before returning a candidate.",
42
+ "default": 0.25
43
+ },
44
+ "truncateHeadChars": {
45
+ "type": "number",
46
+ "title": "Truncated result head characters",
47
+ "description": "Unicode-safe head size for eligible result truncation.",
48
+ "default": 300
49
+ },
50
+ "maxStateTokens": {
51
+ "type": "number",
52
+ "title": "Maximum scoring state units",
53
+ "description": "Upper bound for the provider scoring state.",
54
+ "default": 25000
55
+ },
56
+ "maxRequestTokens": {
57
+ "type": "number",
58
+ "title": "Maximum scoring request units",
59
+ "description": "Upper bound for the provider scoring request.",
60
+ "default": 30000
61
+ },
62
+ "toolPolicy": {
63
+ "type": "string",
64
+ "title": "Claude tool policy",
65
+ "description": "Use read_only or compatible v2 eligibility.",
66
+ "default": "compatible"
67
+ },
68
+ "goal": {
69
+ "type": "string",
70
+ "title": "Private task goal",
71
+ "description": "Optional bounded private task goal sent in the redacted projection.",
72
+ "default": ""
73
+ },
74
+ "enabled": {
75
+ "type": "boolean",
76
+ "title": "Enable automatic compaction",
77
+ "description": "Requires explicit local opt-in and AI Brain disclosure; failures use Claude's built-in fallback.",
78
+ "default": false
79
+ },
80
+ "disclosed": {
81
+ "type": "boolean",
82
+ "title": "Projection disclosure acknowledged",
83
+ "description": "Allow the redacted projection to be sent to AI Brain for the paid-gated plan.",
84
+ "default": false
85
+ },
86
+ "preservationMode": {
87
+ "type": "string",
88
+ "title": "Claude preservation mode",
89
+ "description": "preserve_internal keeps handled messages intact. upstream_compatible rebuilds selected handled read messages from exposed fields and may lose hidden engine metadata.",
90
+ "default": "preserve_internal"
91
+ },
92
+ "compactionStrategy": {
93
+ "type": "string",
94
+ "title": "Compaction strategy",
95
+ "description": "direct_experimental returns a hook-owned transcript; native_summary_notes delegates the final summary to Claude core and keeps selected evidence in private notes.",
96
+ "default": "direct_experimental"
97
+ },
98
+ "diagnosticMode": {
99
+ "type": "boolean",
100
+ "title": "Emit runtime diagnostics",
101
+ "description": "Opt-in content-free hook entry diagnostics for local pilot verification.",
102
+ "default": false
103
+ },
104
+ "telemetryEnabled": {
105
+ "type": "boolean",
106
+ "title": "Enable context dashboard telemetry",
107
+ "description": "Opt-in operational telemetry for the authenticated Contexto dashboard. The launcher enables this only after the extended AI Brain disclosure.",
108
+ "default": false
109
+ },
110
+ "telemetryDisclosed": {
111
+ "type": "boolean",
112
+ "title": "Context telemetry disclosure acknowledged",
113
+ "description": "Permit content-free lifecycle reports containing a hashed session key, bounded measurements, counts, phases and reasons.",
114
+ "default": false
115
+ },
116
+ "telemetryClientVersion": {
117
+ "type": "string",
118
+ "title": "Native Claude version",
119
+ "description": "Launcher-provided native semver used to label telemetry; empty values keep telemetry inactive.",
120
+ "default": ""
121
+ },
122
+ "telemetryNodePath": {
123
+ "type": "string",
124
+ "title": "Owned telemetry Node path",
125
+ "description": "Launcher-provided absolute Node executable path for the report helper.",
126
+ "default": ""
127
+ },
128
+ "telemetryHelperPath": {
129
+ "type": "string",
130
+ "title": "Owned telemetry helper path",
131
+ "description": "Launcher-provided absolute report-only helper path.",
132
+ "default": ""
133
+ },
134
+ "telemetryStateDir": {
135
+ "type": "string",
136
+ "title": "Owned telemetry state path",
137
+ "description": "Launcher-provided private aibrain state directory for the helper.",
138
+ "default": ""
139
+ },
140
+ "telemetryConfigDigest": {
141
+ "type": "string",
142
+ "title": "Owned telemetry configuration binding",
143
+ "description": "Launcher-provided binding for the private endpoint, token and disclosure state.",
144
+ "default": ""
145
+ }
146
+ }
147
+ }