@arnilo/prism 0.0.19 → 0.0.22

package/docs/ponytail.md

@@ -0,0 +1,127 @@
+# Ponytail behavior integration
+
+## What it does
+
+`@arnilo/prism-ponytail` is an optional package that wires [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) into Prism contribution contracts.
+
+It registers upstream skills and commands, injects active mode instructions via upstream `getPonytailInstructions` / `filterSkillBodyForMode`, and persists mode as session custom `ponytail-mode` entries. Import is inert; missing upstream fails closed at `setup` with a bounded redacted error.
+
+## When to use it
+
+Use it when a host wants lazy-minimalism coding behavior (`lite`, `full`, `ultra`) with upstream Ponytail skills (`ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`) in a Prism extension kernel.
+
+Install optional peer `@dietrichgebert/ponytail@^4.8.4` **or** pass `upstreamPath` to a checkout with `skills/` and `hooks/`.
+
+Pair with progressive disclosure: mode slices on the `ponytail-mode` injector; full skill bodies via `load_skill` only.
+
+## Inputs / request
+
+`createPonytailExtension(options)`:
+
+| Field | Type | Required | Purpose |
+| --- | --- | --- | --- |
+| `upstreamPath` | `string` | no | Override path to Ponytail root; default resolves optional peer package. |
+| `defaultMode` | `PonytailMode` | no | Initial mode when no session entry exists (default `full`). |
+| `quietStartup` | `boolean` | no | Suppress startup status events. |
+| `appendEntry` | `(entry, opts?) => Promise<void>` | yes | Host session append (OM `attach` pattern). |
+| `getEntries` | `() => readonly SessionEntry[] \| Promise<...>` | yes | Current branch entries for mode restore. |
+| `configPath` | `string` | no | Bounded local config for `defaultMode` / `quietStartup` / `hideStatus`. |
+
+`PonytailMode`: `off` \| `lite` \| `full` \| `ultra`.
+
+Session custom entry shape:
+
+```json
+{ "kind": "custom", "data": { "type": "ponytail-mode", "mode": "full" } }
+```
+
+Registered skills: `ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`.
+
+Registered commands: `ponytail`, `ponytail-review`, `ponytail-audit`, `ponytail-gain`, `ponytail-debt`, `ponytail-help`.
+
+`ponytail` command actions: `lite|full|ultra|off`, `status`, `default <mode>`.
+
+## Outputs / response / events
+
+| Export | Purpose |
+| --- | --- |
+| `createPonytailExtension(options)` | Returns an inert `Extension` until `kernel.load([...])`. |
+| `ponytail-mode` injector | `InstructionInjector` calling upstream `getPonytailInstructions(mode)`. |
+| `ponytail` command | Set mode, report status, or persist default mode to config file. |
+| Alias commands | Dispatch `{ skill, dispatch: "load_skill" }` for companion skills. |
+| `ponytail:status` / `ponytail:loaded` events | Optional host metadata (no statusline shell scripts). |
+
+Deactivation: exact phrases `stop ponytail` and `normal mode`.
+
+## Request/response example
+
+```json
+{ "command": "ponytail", "args": { "mode": "lite" }, "sessionId": "s1" }
+```
+
+```json
+{ "kind": "custom", "data": { "type": "ponytail-mode", "mode": "lite" } }
+```
+
+## Implementation example
+
+```ts
+import { createPonytailExtension } from "@arnilo/prism-ponytail";
+import {
+  createExtensionKernel,
+  createLoadSkillTool,
+  createLoadedSkillSet,
+  createMemorySessionStore,
+  createSkillRegistry,
+} from "@arnilo/prism";
+
+const store = createMemorySessionStore();
+const callbacks = {
+  appendEntry: async (entry, options) => store.append(entry, options),
+  getEntries: async () => store.list("s1"),
+};
+
+const kernel = createExtensionKernel({ errorPolicy: "throw" });
+await kernel.load([
+  createPonytailExtension({
+    upstreamPath: undefined, // optional peer @dietrichgebert/ponytail
+    defaultMode: "full",
+    quietStartup: true,
+    ...callbacks,
+  }),
+]);
+
+const registry = createSkillRegistry(kernel.registries.skills.list());
+const loaded = createLoadedSkillSet();
+const loadSkill = createLoadSkillTool({ registry, loaded });
+
+await kernel.registries.commands.get("ponytail")!.execute({ mode: "lite" }, { sessionId: "s1" });
+// Select instructionInjectors: ["ponytail-mode"] on runs that should receive mode slices.
+```
+
+See `examples/caveman-ponytail.ts` for combined Caveman + Ponytail progressive disclosure demo (network-free fixtures).
+
+## Extension and configuration notes
+
+- Import alone registers nothing (`sideEffects: false`); no timers, watchers, network, or shell scripts.
+- Upstream hook modules load via `createRequire` from resolved root — instruction strings are not forked in Prism.
+- Mode restore scans `getEntries()` for latest `data.type === "ponytail-mode"` (OM attach pattern).
+- `ponytail-subagent` hook is not wired; nested-agent behavior is host responsibility.
+- No TUI statusline scripts; use `ponytail status` command or extension events.
+- Not included in `@arnilo/prism-code` or `@arnilo/prism-sdk` profiles — opt-in install only.
+
+## Security and performance notes
+
+- Upstream text is untrusted; reads bounded (`MAX_SKILL_FILE_BYTES` 256 KiB, `MAX_INJECTED_INSTRUCTION_BYTES` 32 KiB).
+- Config writes only to host `configPath` with size cap (`MAX_CONFIG_FILE_BYTES` 16 KiB).
+- Errors redact absolute paths and home directories.
+- O(skills) setup scan; O(1) mode tracking per turn; no background workers.
+
+## Related APIs
+
+- [Caveman behavior integration](caveman.md): complementary terse-communication mode package.
+- [Extension kernel and event bus](extensions.md): explicit `kernel.load`.
+- [Context and skills](context-and-skills.md): progressive catalog + `load_skill`.
+- [Instruction injection](instruction-injection.md): `ponytail-mode` injector.
+- [Observational memory compaction package](compaction-observational-memory.md): session callback attach pattern.
+- [Migration guide](migration.md): `0.0.21 → 0.0.22` notes.

package/docs/release-and-install.md

@@ -2,13 +2,13 @@
 
 ## What it does
 
-Prism is published as one core package, thirty-seven first-party capability packages, and six pure-manifest family/profile packages (**44** publishable manifests total). This page describes how they are packed, what each tarball contains, how to install them, the required `@arnilo/prism` peer dependency, the release workflow, and the offline test budget. The measurable 1.0 readiness gates (command-per-gate) live in [`0.1.0-readiness.md`](./0.1.0-readiness.md).
+Prism is published as one core package, thirty-nine first-party capability packages, and six pure-manifest family/profile packages (**46** publishable manifests total). This page describes how they are packed, what each tarball contains, how to install them, the required `@arnilo/prism` peer dependency, the release workflow, and the offline test budget. The measurable 1.0 readiness gates (command-per-gate) live in [`0.1.0-readiness.md`](./0.1.0-readiness.md).
 
 Core package:
 
 - `@arnilo/prism` — the runtime, contracts, registries, streaming events, CLI (including `prism init`), and the `/docs` hub. `files`: `dist` (with `!dist/__tests__` and `!dist/**/*.map` negations), `docs`, `templates`, `CHANGELOG.md`. `bin`: `prism` -> `dist/cli.js`. `sideEffects`: `["dist/cli.js"]`.
 
-First-party workspace packages (each has non-optional `@arnilo/prism@0.0.19` peer and `sideEffects: false`; RAG also peers on memory, and server also peers on workflows):
+First-party workspace packages (each has non-optional `@arnilo/prism@0.0.22` peer and `sideEffects: false`; RAG also peers on memory, and server also peers on workflows):
 
 - `@arnilo/prism-provider-anthropic`, `@arnilo/prism-provider-google`, `@arnilo/prism-provider-openai`, `@arnilo/prism-provider-openrouter`, `@arnilo/prism-provider-kimi`, `@arnilo/prism-provider-zai`, `@arnilo/prism-provider-opencode-go`, `@arnilo/prism-provider-neuralwatt` — provider adapters.
 - `@arnilo/prism-provider-azure`, `@arnilo/prism-provider-bedrock`, `@arnilo/prism-provider-vertex` — optional enterprise-cloud adapters (Entra/IAM/ADC; separate from consumer Anthropic/Google).
@@ -33,10 +33,12 @@ First-party workspace packages (each has non-optional `@arnilo/prism@0.0.19` pee
 - `@arnilo/prism-web-tools` — optional bounded host-selected Brave/Exa search and Firecrawl Markdown/schema extraction; native fetch, no vendor SDK/browser.
 - `@arnilo/prism-browser` — optional host-supplied Playwright browser tools (`browser_open`/`browser_snapshot`/`browser_act`/`browser_close`); import launches nothing; `playwright-core@1.61.0` optional peer.
 - `@arnilo/prism-ag-ui` — optional bounded AG-UI mapper/authorized Web handler/replay plus stable `./acp` sibling; root and ACP imports are inert.
+- `@arnilo/prism-caveman` — optional upstream Caveman behavior integration (`upstreamPath` required; not in code/sdk/all profiles).
+- `@arnilo/prism-ponytail` — optional upstream Ponytail behavior integration (peer `@dietrichgebert/ponytail` or `upstreamPath`; not in code/sdk/all profiles).
 
 ### 0.0.12 AG-UI package boundary
 
-`@arnilo/prism-ag-ui` is a publishable optional code package with root AG-UI exports and stable `./acp` sibling, peer `@arnilo/prism@0.0.19`, pinned `@ag-ui/core@0.0.57` / `@agentclientprotocol/sdk@1.3.0`, and no import-time network/listener/run. It is included by `@arnilo/prism-all` only—not `@arnilo/prism-code` or `@arnilo/prism-sdk`—so coding and SDK profiles stay free of UI protocol dependencies.
+`@arnilo/prism-ag-ui` is a publishable optional code package with root AG-UI exports and stable `./acp` sibling, peer `@arnilo/prism@0.0.22`, pinned `@ag-ui/core@0.0.57` / `@agentclientprotocol/sdk@1.3.0`, and no import-time network/listener/run. It is included by `@arnilo/prism-all` only—not `@arnilo/prism-code` or `@arnilo/prism-sdk`—so coding and SDK profiles stay free of UI protocol dependencies.
 
 Family/profile packages (pure manifests, no code or `dist`; ship `README.md` and `CHANGELOG.md`; use exact hard `dependencies`):
 
@@ -78,9 +80,9 @@ Consumers install the core package for the runtime and add first-party packages
 | Run the default (network-free) test suite | `npm test` |
 | Dry-run pack core + every package | `npm run pack:dry-run` |
 | Local mirror of the release verify gate | `npm run release:dry-run` |
-| Validate clean tag/version/ranges and reject registry collisions | `npm run release:check -- --version 0.0.19` |
-| Preview deterministic publish order | `npm run release:publish -- --version 0.0.19 --dry-run --allow-dirty --allow-untagged` |
-| Resume interrupted tagged publication | `npm run release:publish -- --version 0.0.19 --resume --report release-artifacts/publish-report.json` |
+| Validate clean tag/version/ranges and reject registry collisions | `npm run release:check -- --version 0.0.22` |
+| Preview deterministic publish order | `npm run release:publish -- --version 0.0.22 --dry-run --allow-dirty --allow-untagged` |
+| Resume interrupted tagged publication | `npm run release:publish -- --version 0.0.22 --resume --report release-artifacts/publish-report.json` |
 | Full SDK readiness gate (typecheck + offline tests + pack) | `npm run sdk:ready` |
 
 Public core import specifiers (from the root `exports` map):
@@ -117,7 +119,7 @@ A packed tarball contains only public compiled output and release files:
 - Code packages ship `README.md`, `LICENSE`, and `CHANGELOG.md`; family/profile packages ship `README.md` and `CHANGELOG.md`.
 - The core tarball additionally ships the full `docs/` directory (the docs hub) and `templates/init/` used by `prism init`.
 - `dist/cli.js` and the `bin` link in core.
-- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.0.19.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.0.19.tgz` / `arnilo-prism-compaction-<name>-0.0.19.tgz` / `arnilo-prism-coding-agent-0.0.19.tgz`; family/profile packages produce `arnilo-prism-{providers,compaction,base,code,sdk,all}-0.0.19.tgz`. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
+- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.0.22.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.0.22.tgz` / `arnilo-prism-compaction-<name>-0.0.22.tgz` / `arnilo-prism-coding-agent-0.0.22.tgz`; family/profile packages produce `arnilo-prism-{providers,compaction,base,code,sdk,all}-0.0.22.tgz`. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
 
 Excluded from every tarball by `files` negation:
 
@@ -136,9 +138,9 @@ Excluded from every tarball by `files` negation:
   "name": "host-app",
   "type": "module",
   "dependencies": {
-    "@arnilo/prism": "0.0.19",
-    "@arnilo/prism-provider-openai": "0.0.19",
-    "@arnilo/prism-compaction-observational-memory": "0.0.19"
+    "@arnilo/prism": "0.0.22",
+    "@arnilo/prism-provider-openai": "0.0.22",
+    "@arnilo/prism-compaction-observational-memory": "0.0.22"
   }
 }
 ```
@@ -181,11 +183,11 @@ For SDK readiness, run the same one-command gate directly. It composes existing
 npm run sdk:ready
 ```
 
-Release publication derives all **44** manifests from the workspace once, validates exact `0.0.19` manifest/lockfile/internal ranges, then uses deterministic dependency order. `release:check` requires a clean commit tagged `v0.0.19` and rejects any existing registry version. `release:publish --resume` skips only registry versions whose internal dependency fingerprint matches the local manifest; conflicting versions fail closed. Each attempted package is written immediately to the JSON report, so a failed job can rerun safely. `--dry-run` performs registry availability checks and invokes `npm publish --dry-run` with explicit public access, provenance, and `latest` tag, but does not publish.
+Release publication derives all **46** manifests from the workspace once, validates exact `0.0.22` manifest/lockfile/internal ranges, then uses deterministic dependency order. `release:check` requires a clean commit tagged `v0.0.22` and rejects any existing registry version. `release:publish --resume` skips only registry versions whose internal dependency fingerprint matches the local manifest; conflicting versions fail closed. Each attempted package is written immediately to the JSON report, so a failed job can rerun safely. `--dry-run` performs registry availability checks and invokes `npm publish --dry-run` with explicit public access, provenance, and `latest` tag, but does not publish.
 
 ```bash
-npm run release:check -- --version 0.0.19
-npm run release:publish -- --version 0.0.19 --dry-run --allow-dirty --allow-untagged
+npm run release:check -- --version 0.0.22
+npm run release:publish -- --version 0.0.22 --dry-run --allow-dirty --allow-untagged
 ```
 
 `--allow-dirty` and `--allow-untagged` exist only for local preview; real publication and CI never pass them. npm registry calls occur only in these release preflight/publication commands, never build/test/package discovery.
@@ -196,6 +198,67 @@ Optional live smoke tests stay separate from SDK readiness because they require
 PRISM_LIVE_PROVIDER_TESTS=1 npm run test --workspaces --if-present
 ```
 
+### 0.0.22 publish handoff
+
+**Decision: GO after protected operator prerequisites below.** Release **0.0.22** (Phase 5 third-party behavior integrations, plan 005) ships `@arnilo/prism-caveman` and `@arnilo/prism-ponytail` as opt-in behavior packages (upstream Caveman/Ponytail wiring, session mode persistence, progressive disclosure + injector split). Core `@arnilo/prism` runtime is unchanged. The publish graph is **46 manifests** (+2). No intentional pre-1.0 breaks for hosts that do not install the new packages — see [migration](migration.md) under `0.0.21 → 0.0.22 third-party behavior integrations`.
+
+```bash
+git diff --check
+npm ci
+npm run sdk:ready
+node --test scripts/budget-gate.test.mjs
+node scripts/scan-secrets.mjs && node scripts/verify-sbom.mjs
+npm audit --audit-level=moderate
+npm run release:gate
+npm run release:check -- --version 0.0.22 --allow-dirty --allow-untagged --report /tmp/prism-0.0.22-preflight.json
+npm run release:publish -- --version 0.0.22 --dry-run --allow-dirty --allow-untagged --report /tmp/prism-0.0.22-dry-run.json
+git tag -s v0.0.22 -m "Prism 0.0.22"
+git verify-tag v0.0.22
+git push origin v0.0.22
+```
+
+### 0.0.21 publish handoff
+
+**Decision: GO after protected operator prerequisites below.** Release **0.0.21** (Phase 4 coding-tool capability gaps, plan 004) ships `repo_search` `outputMode`, bounded `glob`, optional session-scoped read-before-write, bounded `delete`/`move`, and coding-security approval/sandbox wiring. The exact graph stays **44 publishable manifests**; no package added or retired. Intentional pre-1.0 breaks are documented in [migration](migration.md) under `0.0.20 → 0.0.21 coding-tool capability gaps`.
+
+```bash
+git diff --check
+npm ci
+npm run sdk:ready
+node --test scripts/budget-gate.test.mjs
+node scripts/scan-secrets.mjs && node scripts/verify-sbom.mjs
+npm audit --audit-level=moderate
+npm run release:gate
+npm run release:check -- --version 0.0.21 --allow-dirty --allow-untagged --report /tmp/prism-0.0.21-preflight.json
+npm run release:publish -- --version 0.0.21 --dry-run --allow-dirty --allow-untagged --report /tmp/prism-0.0.21-dry-run.json
+git tag -s v0.0.21 -m "Prism 0.0.21"
+git verify-tag v0.0.21
+git push origin v0.0.21
+```
+
+The dry-run checks every registry collision and executes npm's non-publishing tarball validation for each dependency-ordered manifest. The protected tag workflow alone publishes through `npm run release:publish -- --version "${GITHUB_REF_NAME#v}" --resume --report release-artifacts/publish-report.json`; re-run a failed job for the same tag. `npm audit signatures --json --include-attestations` and artifact checksums remain post-publish checks.
+
+### 0.0.20 publish handoff
+
+**Decision: GO after protected operator prerequisites below.** Release **0.0.20** (Phase 3 skills and context progressive disclosure, plan 003) ships progressive skill catalog assembly (`skillsDisclosure`), session `load_skill`, empty `SkillRegistry` default with `activateAllSkills` migration opt-in, priority-aware context budget demotion, and optional `toolResultFold`. The exact graph stays **44 publishable manifests**; no package added or retired. Intentional pre-1.0 breaks are documented in [migration](migration.md) under `0.0.19 → 0.0.20 skills and context progressive disclosure`.
+
+```bash
+git diff --check
+npm ci
+npm run sdk:ready
+node --test scripts/budget-gate.test.mjs
+node scripts/scan-secrets.mjs && node scripts/verify-sbom.mjs
+npm audit --audit-level=moderate
+npm run release:gate
+npm run release:check -- --version 0.0.20 --allow-dirty --allow-untagged --report /tmp/prism-0.0.20-preflight.json
+npm run release:publish -- --version 0.0.20 --dry-run --allow-dirty --allow-untagged --report /tmp/prism-0.0.20-dry-run.json
+git tag -s v0.0.20 -m "Prism 0.0.20"
+git verify-tag v0.0.20
+git push origin v0.0.20
+```
+
+The dry-run checks every registry collision and executes npm's non-publishing tarball validation for each dependency-ordered manifest. The protected tag workflow alone publishes through `npm run release:publish -- --version "${GITHUB_REF_NAME#v}" --resume --report release-artifacts/publish-report.json`; re-run a failed job for the same tag. `npm audit signatures --json --include-attestations` and artifact checksums remain post-publish checks.
+
 ### 0.0.19 publish handoff
 
 **Decision: GO after protected operator prerequisites below.** Release **0.0.19** (Phase 2 observational memory lifecycle, plan 002) ships `@arnilo/prism-compaction-observational-memory` attach lifecycle, four-layer provider context, nested settings with legacy map, source-faithful recall/paging, and hard fold/render caps. Core `@arnilo/prism` runtime is unchanged. The exact graph stays **44 publishable manifests**; no package added or retired. Intentional pre-1.0 breaks are documented in [migration](migration.md) under `0.0.18 → 0.0.19 observational memory lifecycle`.
@@ -814,8 +877,8 @@ npm publication is not transactional and published versions are immutable. Parti
 
 ## Extension and configuration notes
 
-- **Required `@arnilo/prism` peer.** Every first-party code package declares a non-optional `@arnilo/prism@0.0.19` peer (`peerDependenciesMeta` must not mark `@arnilo/prism` optional; other peers such as `playwright-core` may be optional). The range stays pinned to `0.0.19` for the current 0.x release and will widen to `^1.0.0` at the 1.x stable release. Inside the workspace each package also declares `"@arnilo/prism": "file:../.."` in `devDependencies` so `npm install` resolves the peer locally; that devDependency is stripped from consumer installs and is not a runtime dependency.
-- **Public access.** All 43 manifests (37 code packages + 6 family/profile packages) declare `"publishConfig": { "access": "public" }`; the publisher also passes `--access public` explicitly because scoped packages otherwise default to restricted on first publish.
+- **Required `@arnilo/prism` peer.** Every first-party code package declares a non-optional `@arnilo/prism@0.0.22` peer (`peerDependenciesMeta` must not mark `@arnilo/prism` optional; other peers such as `playwright-core` may be optional). The range stays pinned to `0.0.22` for the current 0.x release and will widen to `^1.0.0` at the 1.x stable release. Inside the workspace each package also declares `"@arnilo/prism": "file:../.."` in `devDependencies` so `npm install` resolves the peer locally; that devDependency is stripped from consumer installs and is not a runtime dependency.
+- **Public access.** All 46 manifests (40 code packages + 6 family/profile packages) declare `"publishConfig": { "access": "public" }`; the publisher also passes `--access public` explicitly because scoped packages otherwise default to restricted on first publish.
 - **Map retention knob.** Source maps are emitted locally but stripped from tarballs by `!dist/**/*.map`. Removing that `files` negation ships maps in releases (larger tarballs, better consumer stack traces).
 - **Release workflow.** `.github/workflows/release.yml` has six jobs. `verify` runs network-free SDK readiness on Node 24; `node20-compat` builds/imports every public root `exports` default target on Node 20 for declared `engines.node >=20` (docs examples need Node >=22.6 native TypeScript stripping); `postgres-integration` uses `pgvector/pgvector:pg16`; `supply-chain` runs high-severity audit, SPDX/license policy, and tracked-source secret scanning; and tag-only `codeql-release` runs SAST. Tag-only `publish` needs all five gates, preserves clean exact-tag/version/topological publication, and alone receives `NPM_TOKEN`, `id-token: write`, and `attestations: write`. Before npm publish it packs all current tarballs, generates checksums plus SPDX, scans unpacked public artifacts, creates GitHub attestations for tarballs and SBOM, then retains artifacts for 30 days. Registry state remains the resumable journal. Local `npm run release:dry-run` remains network-free SDK readiness; local PostgreSQL coverage is `PRISM_TEST_POSTGRES_URL=... npm run test:postgres`.
 - **Adding a package.** New workspace packages are picked up automatically by `npm run build --workspaces`, `npm test --workspaces`, `npm run pack:dry-run`, the packaging guard (`src/__tests__/packaging.test.ts`), and the install-smoke test (`src/__tests__/install-smoke.test.ts`) via the workspace glob; add the package to both tests' config arrays for explicit per-package assertions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.0.19",
+  "version": "0.0.22",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",