@anhlp/alp 0.0.0-beta.1

package/docs/modular-monorepo.md

@@ -0,0 +1,210 @@
+# Modular ALP monorepo
+
+ALP uses npm workspaces inspired by [Paseo's package layout](https://github.com/getpaseo/paseo/blob/main/package.json). The `@anhlp/alp` root package now uses the canonical workspace builds; root source shims and legacy checkout directories have been removed.
+
+## Repository layout
+
+```text
+packages/       ALP libraries and executables, published as @anhlp/alp-*
+  protocol  core  runtime  client  daemon  cli
+integrations/   optional adapters to external hosts, each a separate package
+  paseo/        @anhlp/alp-paseo (Paseo plugin, web app, relay)
+  web.json      development-only descriptor; not shipped in core
+apps/           standalone applications
+  tui/          @anhlp/alp-tui (reserved, private)
+```
+
+Workspaces are `packages/*` (the six libraries), `integrations/paseo` and `apps/tui`; package names, versions and public exports did not change with the move. Dependencies run one way: `packages/*` never depend on `integrations/*` or `apps/*`, and nothing depends on an integration or an app. `npm run check:boundaries` fails on any such edge, on dependencies outside the allowed graph, and on cycles. Update path-based tooling through `scripts/test-lib.mjs` (`workspaceDirectory`) and `scripts/build-workspace.mjs` (`locations`).
+
+The plugin depends on the daemon only for its embedded mode and for the `alpd` it bundles; every other interaction goes through `@anhlp/alp-client` and `@anhlp/alp-protocol` over IPC. The daemon, runtime, core, client and cli packages do not import it.
+
+## Ownership and dependency rules
+
+| Workspace | Public API | Owns | ALP dependencies |
+|---|---|---|---|
+| `@anhlp/alp-protocol` | version/constants/errors, JSON Schemas, event/session DTOs, connection contract | wire and data contracts | none |
+| `@anhlp/alp-core` | named domain namespaces and exported domain subpaths | configuration, resolution, teams, tasks, hooks, permissions, templates | protocol |
+| `@anhlp/alp-runtime` | `createAlpRuntime`, native transports, provider registry, runtime subpaths | sessions, delegation, mailbox, board, provider execution | core, protocol |
+| `@anhlp/alp-client` | `AlpClient`, `connect`, discovery/lifecycle and helper subpaths | IPC client, supervision, service definitions, setup/diagnostics | core, protocol |
+| `@anhlp/alp-daemon` | `createDaemonServer`, stores, neutral IPC extensions | runtime hosting, persistence and server surfaces | runtime, core, client, protocol |
+| `@anhlp/alp-cli` | `alp` executable; ACP subpaths | command domains and ACP editor adapter | client, core, protocol |
+| `@anhlp/alp-paseo` | existing Paseo server/client entrypoints | Paseo host adapter and panels | daemon, runtime, client, core, protocol |
+| `@anhlp/alp-tui` | none | reserved private workspace | none |
+
+Cross-package code imports package exports, never sibling source paths. Public domain subpaths omit `.js`, for example `@anhlp/alp-core/tasks`. Imports inside a package remain relative. `npm run check:boundaries` checks source imports, declared dependencies, the allowed graph and cycles. Native SDKs stay in runtime or host adapters; core/protocol do not import them.
+
+Canonical implementations live in `packages/*/src`, `integrations/paseo` and `apps/tui`; the root package exposes built compatibility artifacts rather than source shims. Shared server-side panel RPC handlers belong to the plugin; the daemon hosts only neutral IPC extensions and does not depend on the plugin package.
+
+The root `templates/` remains the editable source of truth. Build scripts copy it into the core package's generated `templates/` for standalone installation. Do not edit the generated copy. Existing template and data formats are unchanged.
+
+## Build and test
+
+`npm run validate` is the shared local/CI baseline. Run `validate:core`,
+`validate:paseo`, or `validate:packages` separately to isolate failures. See
+[CI baseline](ci-baseline.md) for build ordering, requirements and recorded results.
+
+```sh
+npm ci
+npm run check:boundaries
+npm run check
+npm test
+npm run build:packages
+npm run build --workspace=@anhlp/alp-runtime
+npm run test --workspace=@anhlp/alp-runtime
+```
+
+Root `npm run build` retains the neutral legacy bundle paths and builds the CLI without Paseo. `npm run build:paseo` builds the optional plugin. Workspace builds compile the selected package and its dependencies, preserving individual module imports and emitting declarations. The `alp-source` export condition is only for repository builds/typechecking; published consumers use ordinary JavaScript and declaration exports.
+
+## Test layout
+
+Tests follow package ownership. A test that imports only one package and the packages it declares as dependencies lives in `<workspace>/tests/` (`packages/<name>`, or `integrations/paseo` for the plugin) and runs with that package's `npm test`, which builds the package and its dependencies first. A test that crosses packages (several runtimes through the CLI, a daemon with a client and the plugin, repository-wide checks) lives in `test/integration/`. Live-provider scripts live in `test/e2e/`. Shared fixture transports stay in `test/support/`; they are plain files, not a package, and package tests may import them (and only them) from outside the package.
+
+| Package | Tests |
+| --- | --- |
+| protocol | wire contract: fixtures, schema, method and event inventories |
+| core | adapter, delegation, IR validation, library editing, resolver, upgrade |
+| runtime | sessions, context, hardening, limits, pause, recall, supervisor, verdicts, worktrees, providers, v1 events |
+| client | prompt, golden output, daemon endpoints |
+| daemon | daemon lifecycle, board, extensions RPC, recovery, settings, usage, method inventory |
+| cli | init, library, default providers, doctor, web pairing |
+| @anhlp/alp-paseo | plugin bridge, panel, settings screen, web, relay, providers, skills, workflow, supervise, integration process logs |
+| `test/integration` | ACP, Antigravity, beads, epics, hooks, language, permissions, service, setup, tasks, teams, template sync, verify, library tools, distribution layout, boundaries, web process and discovery, test layout |
+
+Commands, from the repository root:
+
+```sh
+npm test                    # unit + integration, hermetic, each file once
+npm run test:unit           # every packages/*/tests
+npm run test:integration    # test/integration
+npm run test:e2e            # test/e2e, live providers (opt-in)
+npm run test:all            # all of the above
+npm test -w @anhlp/alp-core # one package, independently
+```
+
+Every run uses an isolated `ALP_HOME`. `npm run test:packages` runs each package's own `npm test` in turn; it overlaps with `test:unit` and is meant for checking that a package tests on its own. Live `test:e2e:*` scripts require authenticated providers (and sometimes a running Paseo host). `test/integration/layout.test.js` fails when a test file sits outside these directories, is selected twice, or names a package its own package does not depend on.
+
+Every core workspace — protocol, core, runtime, client, daemon and CLI — compiles and tests without a web build; `scripts/build-core.mjs` emits the neutral core bundles and the six core packages' tests never build the plugin. Packing the optional plugin requires the pinned web app; packing `@anhlp/alp` does not:
+
+```sh
+npm run build:web
+npm run build:packages
+npm run release:pack-check
+npm run test:packages:smoke
+```
+
+Plugin prepack verifies its web artifact's pinned Paseo commit and patch inventory; core prepack runs only the core build. The daemon and CLI distributions carry `alpd.js` (CLI also `acp.js`) but no web app; the plugin ships the web app and the integration entry (`server/dist/main.js`), and the root `@anhlp/alp` distribution ships only core artifacts. The existing Claude SDK external dependency remains declared in the executable distributions.
+
+### Breaking migration: the daemon no longer serves the web app
+
+The web/Paseo surface moved out of the neutral daemon into the optional plugin. Consumers that reached the web app through `@anhlp/alp-daemon` must move to the plugin package:
+
+| Removed | Replacement |
+| --- | --- |
+| `@anhlp/alp-daemon/web` (`createWebServer`, `createPaseoBridge`, `webAppDir`, `webFile`, `DEFAULT_WEB_PORT`) | `@anhlp/alp-paseo/web` (same named exports) |
+
+`@anhlp/alp-daemon` keeps only its `index`, `lock`, `main`, `server` and `store` subpaths; the `web` export and `src/web.ts` are gone, so an `alp-daemon/web` import now fails at resolution. The daemon's neutral core bundles (`dist/runtime/index.js`, `dist/daemon/index.js`, `dist/alpd.js`, `dist/acp.js`, `dist/acp/agent.js`) never include the plugin or `@getpaseo`; `npm run check:boundaries` reads `dist/build-manifest.json` to prove it. The plugin's own subpaths (`@anhlp/alp-paseo`, `/main`, `/web`, `/paseo/*`, `/panel/*`) replace the old in-daemon copies, and Paseo's installed integration can register its descriptor at `$ALP_HOME/integrations/web.json` using `alp-web-integration --register`.
+
+Migrate an in-repo consumer in two steps:
+
+```sh
+# 1. Install the optional integration beside the CLI.
+npm install -g @anhlp/alp-paseo@beta
+# 2. Move the import to the plugin and restart the daemon so it picks up the new build.
+#    -import { createWebServer } from '@anhlp/alp-daemon/web';
+#    +import { createWebServer } from '@anhlp/alp-paseo/web';
+alp daemon restart
+```
+
+#### Dependency inventory
+
+The six core workspaces depend only on `@anhlp/*` packages and their own declared SDKs; none declares or imports `@getpaseo/*`. The plugin is an optional consumer and declares Paseo as peer dependencies:
+
+| Package | Declares `@getpaseo/*` | Provides |
+| --- | --- | --- |
+| `@anhlp/alp-protocol` … `@anhlp/alp-cli` | no | the neutral core |
+| `@anhlp/alp-paseo` | peers `@getpaseo/plugin`, `@getpaseo/client`, `@getpaseo/protocol`, `@getpaseo/relay` (and React) | the Paseo host adapter, the web app and the panels |
+
+`npm run release:pack-check` packs the main distribution and each public workspace, rejects Paseo paths in core tarballs and verifies public exports; `npm run release:tarball-check` then installs the tarballs in isolation — the core set with no `@getpaseo`, plugin or React package must import and typecheck, and the plugin must install with its declared peers.
+
+#### Neutral extensions and the plugin's process data
+
+The daemon hosts *neutral* IPC extensions: a connection registers a method with `extension.register`, owns it until it disconnects or calls `extension.unregister`, and the daemon routes `extension.invoke` calls back to the owner (bounded pending calls, torn down on disconnect). The daemon assigns no meaning to a method. The plugin registers `web.pairing` on its alpd connection and re-registers it after a daemon restart; `alp web pair` waits for the fresh registration instead of failing on an unknown method.
+
+The plugin's per-process data stays under the selected home, never inside the daemon: the integration lock is `<home>/integrations/web.lock`, the ready address is `<home>/web.json`, the registered descriptor is `<home>/integrations/web.json`, and the log is `<home>/logs/integrations/paseo.log`. `alp web` reads the lock and `web.json` and ignores a stale file named by another pid. Set `ALP_HOME` to keep everything in one directory.
+
+#### Restart and upgrade
+
+Restarting is non-destructive. `alp daemon restart` (or the plugin's supervision) starts a fresh daemon; the plugin reconnects and re-registers its extensions, and sessions resume from their threads at the next prompt. A daemon left running by an older install is never killed or migrated in place: `alp web` reports that it is "older than this alp (alp daemon restart)" and waits for the operator, so a restart to migrate is always explicit.
+
+## Independent versions and publishing
+
+> **For the beta `0.0.0-beta.1`, do not use the commands in this section.** The beta gives all
+> eight published packages one version, packs them once and publishes those tarballs with
+> `--tag beta`, following the manual checklist in [beta-scope.md](alp/beta-scope.md) §7. The
+> `npm publish` below has no `--tag`, so it would set `latest`.
+
+Versions are per manifest. Bump one package and update its dependency references/lockfile with:
+
+```sh
+npm run version:package -- @anhlp/alp-protocol 0.9.6
+npm run build --workspace=@anhlp/alp-protocol
+npm run test --workspace=@anhlp/alp-protocol
+npm pack --workspace=@anhlp/alp-protocol --dry-run
+npm publish --workspace=@anhlp/alp-protocol --access public
+```
+
+Publishing is an explicit operator action. Publish changed dependencies before dependents: protocol → core → runtime/client → daemon/CLI → plugin/compatibility root. The helper does not bump or publish unrelated package versions. TUI remains private and contains no implementation.
+
+## Provider extension
+
+The normalized request/notification/lifecycle interface is `RuntimeTransport`. Existing `RuntimeOptions.transport(cwd, env, kind, acp, antigravity)` remains the highest-priority injection hook. Each runtime can instead receive adapter overrides in `providers`, or an explicit `ProviderRegistry`:
+
+```ts
+import { createAlpRuntime, createProviderRegistry } from '@anhlp/alp-runtime';
+const registry = createProviderRegistry();
+registry.register('acp:my-agent', context => myTransport(context));
+const runtime = createAlpRuntime({ providerRegistry: registry });
+```
+
+Codex, Claude, ACP and Antigravity factories retain existing command/environment precedence. Named ACP factories fall back to the generic ACP adapter. Provider normalization, sandbox configuration and native SDK specifics remain behind runtime adapters. No global registry is mutated.
+
+## Protocol and future Rust modules
+
+`packages/protocol/schema/ipc-v1.json` defines JSON-RPC frames and discriminated session events. `methods-v1.json` inventories built-in methods and parameter shapes. JSONL fixtures exercise handshake, success, error and event notification frames; tests compare method/event inventories with their implementations and validate emitted events.
+
+The portable seam is JSON, not a TypeScript object or an in-process callback:
+
+- Local sockets/named pipes carry UTF-8 newline-delimited JSON-RPC 2.0; event notifications use method `event`.
+- Protocol version remains 1; the existing handshake, method names and error codes remain unchanged.
+- Events retain opaque session ids, runtime epoch, per-session sequence and ISO timestamps. Replay cursors never cross epochs.
+- Schemas accept additive fields, matching existing clients. Preserve JSON field names, nullability and persisted version-1 records when replacing implementations.
+- Incompatible method/event semantics require a negotiated new protocol version. Package SemVer and wire protocol version are separate.
+- The current frame guard is `MAX_FRAME` (16 × 1024 × 1024 decoded JavaScript string units); a Rust replacement must preserve that guard or negotiate a changed byte limit.
+
+A Rust daemon can implement the same method/event contract and run the JSON fixtures plus client/daemon tests. An in-process Rust runtime replacement must preserve the exported `AlpRuntime` interface through a Node binding or package-owned proxy, including synchronous snapshot/list reads, event ordering and lifecycle behavior. Client, CLI and Paseo surfaces then continue over IPC. A Rust core would need an explicit serialized command boundary around current filesystem operations before replacing the in-process core API; this migration does not pretend TypeScript function calls are language-neutral IPC. No Rust implementation or TUI is introduced.
+
+The Paseo plugin workspace lives in `integrations/paseo` and uses the npm name `@anhlp/alp-paseo`. Build with `npm run build -w @anhlp/alp-paseo` and test with `npm run test -w @anhlp/alp-paseo`. Tool selectors accept `paseo`; the previous `paseo-plugin` selector remains an alias.
+
+## Paseo isolation
+
+The ALP core six workspaces (`protocol`, `core`, `runtime`, `client`, `daemon`, `cli`) now contain no `@getpaseo/*` imports or dependencies. Paseo-specific protocol handling, panel RPC implementations, shared RPC mapping, and the `createPaseoBridge` web/relay gateway moved to `integrations/paseo`; daemon artifacts expose them no longer. The Paseo integration remains an optional consumer of ALP daemon IPC and may be shipped separately or bundled as an optional executable/app. `check-boundaries` additionally validates packed `dist` artifacts for leaked Paseo dependencies.
+
+### Main distribution and standalone proof
+
+`@anhlp/alp` has no required, optional, peer or bundled `@getpaseo/*` dependency,
+and ships neither the web app nor integration descriptors/server artifacts.
+The root build/prepack and all six workspace builds are core-only. Declaration
+emission uses `packages/daemon/src/alp-templates.d.ts`, with no Paseo source input.
+
+`npm run test:core:standalone` copies only the six core sources, templates and
+build scripts into a temporary source tree, installs build dependencies there,
+and runs actual npm prepack lifecycles without `integrations/paseo` or a web
+build. It installs the resulting six tarballs in one consumer and `@anhlp/alp`
+with only its declared ALP dependencies in another. Both run CLI/daemon/IPC and
+ACP stdio handshake, prompt and streamed response with a fake provider. Installed
+artifacts and the complete npm dependency tree are checked for Paseo leakage.
+The existing runtime/reconnect test also runs against the six installed packages.
+
+To retain the web UI after upgrading core, install `@anhlp/alp-paseo` separately
+and run `alp-web-integration --register` in the intended `ALP_HOME` (global PATH
+discovery also works). See the [plugin installation and compatibility notes](../integrations/paseo/README.md#optional-web-installation).

package/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "@anhlp/alp",
+  "version": "0.0.0-beta.1",
+  "description": "ALP command line and alpd, the per-user daemon that runs filesystem-defined Codex and Claude Code agent teams",
+  "type": "module",
+  "files": [
+    "packages/cli/dist",
+    "packages/core/dist",
+    "packages/client/dist",
+    "dist/alpd.js",
+    "dist/acp.js",
+    "templates",
+    "README.md",
+    "docs/modular-monorepo.md",
+    "/NOTICE",
+    "dist/THIRD-PARTY-NOTICES.txt"
+  ],
+  "bin": {
+    "alp": "packages/cli/dist/cli.js"
+  },
+  "scripts": {
+    "test": "node scripts/test.mjs",
+    "test:unit": "node scripts/test.mjs unit",
+    "test:integration": "node scripts/test.mjs integration",
+    "test:e2e": "node scripts/test.mjs e2e",
+    "test:all": "node scripts/test.mjs all",
+    "check": "tsc -p tsconfig.paseo.json && tsc -p tsconfig.client.json",
+    "build": "node scripts/build-workspace.mjs cli && node scripts/build-core.mjs",
+    "test:e2e:workflow": "node test/e2e/workflow-e2e.mjs pho && node test/e2e/workflow-e2e.mjs cafe",
+    "test:e2e:mailbox": "node test/e2e/mailbox-e2e.mjs ask && node test/e2e/mailbox-e2e.mjs wake && node test/e2e/mailbox-e2e.mjs steer",
+    "test:e2e:team": "node test/e2e/team-e2e.mjs",
+    "test:e2e:claude": "node test/e2e/claude-e2e.mjs",
+    "test:e2e:claude-runtime": "node test/e2e/claude-runtime-e2e.mjs",
+    "test:e2e:paseo": "node test/e2e/paseo-e2e.mjs",
+    "test:e2e:paseo-remote": "node test/e2e/paseo-remote-e2e.mjs",
+    "test:e2e:alpd": "node scripts/build-core.mjs && node test/e2e/alpd-e2e.mjs",
+    "test:e2e:detach": "node test/e2e/viewer-detach-e2e.mjs",
+    "test:e2e:persistence": "node scripts/build-core.mjs && node test/e2e/persistence-e2e.mjs",
+    "test:e2e:import": "node test/e2e/import-e2e.mjs",
+    "test:e2e:worktree": "node scripts/build-core.mjs && node test/e2e/worktree-e2e.mjs",
+    "test:e2e:human": "node test/e2e/human-e2e.mjs cli && node test/e2e/human-e2e.mjs paseo",
+    "test:e2e:board": "node scripts/build-core.mjs && node test/e2e/board-e2e.mjs",
+    "prepack": "npm run build",
+    "build:web": "node scripts/build-paseo-web.mjs",
+    "build:packages": "npm run build --workspaces --if-present",
+    "test:packages": "npm run test --workspaces --if-present",
+    "check:boundaries": "node scripts/check-boundaries.mjs",
+    "release:check": "npm run check:boundaries && npm run check && npm test && npm run build:packages && npm run release:pack-check",
+    "version:package": "node scripts/version-package.mjs",
+    "release:pack-check": "node scripts/pack-check.mjs",
+    "release:tarball-check": "node scripts/tarball-consumer.mjs",
+    "release:check-version": "node scripts/release-check.mjs",
+    "release:pack": "node scripts/release-pack.mjs",
+    "release:verify": "node scripts/release-verify.mjs",
+    "release:consumer": "node scripts/release-consumer.mjs",
+    "release:gate": "node scripts/release-gate.mjs",
+    "test:packages:smoke": "node scripts/package-smoke.mjs",
+    "test:gateway:smoke": "node scripts/gateway-smoke.mjs",
+    "validate": "node scripts/validate.mjs",
+    "validate:core": "node scripts/validate.mjs core",
+    "validate:paseo": "node scripts/validate.mjs paseo",
+    "validate:packages": "node scripts/validate.mjs packages",
+    "check:core": "tsc -p tsconfig.core.json",
+    "test:core:standalone": "node scripts/core-standalone-smoke.mjs",
+    "build:paseo": "node scripts/build-workspace.mjs paseo",
+    "dev:alp-web": "npm run dev --workspace @anhlp/alp-web",
+    "build:alp-web": "npm run build --workspace @anhlp/alp-web",
+    "typecheck:alp-web": "npm run typecheck --workspace @anhlp/alp-web",
+    "test:alp-web": "npm test --workspace @anhlp/alp-web",
+    "test:alp-web:e2e": "node scripts/build-workspace.mjs cli && node scripts/build-workspace.mjs daemon && npm run build --workspace @anhlp/alp-web && npm run test:e2e --workspace @anhlp/alp-web",
+    "validate:web": "node scripts/validate.mjs web"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "devDependencies": {
+    "@agentclientprotocol/sdk": "1.7.0",
+    "@anthropic-ai/sdk": "^0.131.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@types/node": "22.20.5",
+    "@types/react": "19.1.17",
+    "@types/react-dom": "19.1",
+    "@types/ws": "^8.18.2",
+    "ajv": "8.20.0",
+    "esbuild": "0.25.12",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "5.9.3",
+    "ws": "^8.22.0",
+    "zod": "4.4.3"
+  },
+  "dependencies": {
+    "@anhlp/alp-client": "0.0.0-beta.1",
+    "@anhlp/alp-core": "0.0.0-beta.1",
+    "@anhlp/alp-protocol": "0.0.0-beta.1",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.292",
+    "smol-toml": "1.9.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phucanh08/alp.git"
+  },
+  "homepage": "https://github.com/phucanh08/alp#readme",
+  "bugs": {
+    "url": "https://github.com/phucanh08/alp/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "workspaces": [
+    "packages/protocol",
+    "packages/core",
+    "packages/runtime",
+    "packages/client",
+    "packages/daemon",
+    "packages/cli",
+    "apps/tui",
+    "apps/gateway",
+    "integrations/paseo",
+    "apps/web"
+  ]
+}

package/packages/cli/README.md

@@ -0,0 +1,7 @@
+# @anhlp/alp-cli
+
+The alp executable and ACP editor surface.
+
+Build: `npm run build --workspace=@anhlp/alp-cli`. Test: `npm run test --workspace=@anhlp/alp-cli`.
+
+Public imports use the package root and its explicitly exported subpaths. See [architecture, provider extension, compatibility and release instructions](../../docs/modular-monorepo.md).