@warlock.js/ai-workspace 4.5.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog — @warlock.js/ai-workspace
+
+All notable changes to `@warlock.js/ai-workspace` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
+
+## 4.5.0 - 2026-07-01
+
+Initial release — the policy-jailed filesystem + shell workspace for `@warlock.js/ai` agents (the W1 surface).
+
+### Added
+
+- `ai.workspace(policy)` — the workspace verb, registered on the shared `ai` object via a `declare module "@warlock.js/ai"` augmentation + a runtime side-effect on import (no edit to `@warlock.js/ai`'s own source). Exported as the `workspace` factory; `WorkspaceCapableAi` is the typed view consumers cast `ai` through.
+- **Policy jail** — every path is `realpath`-resolved and must sit under `cwd` (or an `allowPaths` root); `denyPaths` globs are blocked even inside `cwd`; the shell allow/deny list gates each command's leading executable basename (deny wins, fail-closed); per-command timeout + output byte cap; and `process.env` is never inherited wholesale (opt-in `shell.inheritEnv`, plus explicit `shell.env`).
+- **Seven agent-facing tools** under `ws.tools.*`, each a `ToolContract` built on the core `tool()` factory: `read_file`, `edit_file`, `write_file`, `run_shell`, `run_tests`, `grep`, `glob`. Each factory takes an optional `{ name }` (and `run_tests` a `{ command }`) override.
+- `tools.all()` — every tool in canonical order — and `tools.pick(...names)` — a least-privilege subset (e.g. `pick("readFile", "grep", "glob")` for a reviewer).
+- **Direct programmatic methods** sharing the same policy seam: `readFile` / `writeFile` / `editFile` / `exec` / `grep` / `glob` / `exists` / `mkdir` / `remove`.
+- `readonly()` — a projection that vends only the read/grep/glob tools and rejects every mutating direct method with a `WorkspacePolicyError`.
+- `scope(subdir)` — a sub-jailed workspace rooted at `subdir` (narrowed `cwd`, same sub-policies and backend selection).
+- **Read-before-edit guard** — `read_file` / `readFile` return a SHA-256 content `hash` (via `@warlock.js/fs` `hashString`); `edit_file` requires an exact, unique `oldString` (or `replaceAll`) and rejects a mismatched `expectHash` as stale.
+- **Backends** — `createLocalBackend` (default `"local"`; `@warlock.js/fs` for IO + `node:child_process` for the shell) and `createMockBackend` (in-memory `Map` + scripted `exec`, for hermetic disk-free tests), behind the `WorkspaceBackend` contract.
+- **Policy engine seam** exports: `resolveInJail`, `isCommandAllowed`, `buildEnv`, and the `ResolvedPath` type.
+- **Ops layer** export `createOps` — the single policy-enforced operation layer both the tools and the direct methods funnel through.
+- **Typed errors** `WorkspacePolicyError` (`type: "path-escape" | "denied-command"`) and `WorkspaceEditError` (`type: "not-found" | "not-unique" | "stale-hash"`), both extending the `@warlock.js/ai` `AIError` base (code `TOOL_EXEC_FAILED`) so failures surface to the agent as tool-error data, never thrown run-killers.
+- **Public type surface** re-exported from the barrel: `Workspace`, `WorkspaceTools`, `WorkspacePolicy`, `WorkspaceShellPolicy`, `WorkspaceReadPolicy`, `WorkspaceBackendType`, `WorkspaceToolName`, `WorkspaceOps`, `WorkspaceBackend` (+ `WorkspaceBackendExecOptions` / `WorkspaceBackendExecResult`), and the per-tool IO shapes (`ReadFileInput`/`Result`, `EditFileInput`/`Result`, `WriteFileInput`/`Result`, `RunShellInput`/`Result`, `RunTestsInput`, `GrepInput`/`Match`/`Result`, `GlobInput`/`Result`).
+- `scripts/generate-llms.mjs` and the generated `llms.txt` / `llms-full.txt` projections of `skills/`.
+- `skills/use-a-workspace/SKILL.md` — building a jailed workspace and operating it (policy, the seven tools, the direct methods, `readonly` / `scope`).
+- `skills/build-loop-agent/SKILL.md` — wiring `ws.tools.all()` into a coding agent that reads → edits → runs tests until green.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hassan Zohdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @warlock.js/ai-workspace
+
+> Policy-jailed filesystem + shell workspace for `@warlock.js/ai` agents.
+
+A **workspace** is the bounded place an agent reads, writes, and runs commands — a
+policy-enforced handle to a filesystem + shell that (a) vends tools to agents and
+(b) you can drive directly from code. One policy, one shared rule set, two ways to
+touch it: the agent uses `ws.tools.*`; you use the direct methods (`ws.readFile`,
+`ws.exec`, …). Importing the package registers the verb on the shared `ai` object,
+so it is reached as `ai.workspace(policy)` per the `ai.`-namespace convention.
+
+## Security: a policy jail, not OS isolation
+
+The workspace is a **policy jail**, and it is honest about that — it is **not** an
+OS sandbox. Every path is `realpath`-resolved and must sit under `cwd` (or an
+`allowPaths` root); `denyPaths` globs are blocked even inside `cwd`; shell commands
+are gated by an executable allow/deny list; and `process.env` is **never** inherited
+wholesale (a command can't even find `node`/`npm` unless the policy opts in via
+`shell.inheritEnv: ["PATH"]`). What it does **not** do is contain what an *allowed*
+process does once it runs — an allowed `node` can still open a socket or read a file
+its own user can reach. For untrusted code you want real isolation (a container /
+microVM backend), which is a later phase. Treat this as least-privilege guardrails
+for a **trusted** agent, not a security boundary around a hostile one.
+
+## Install
+
+```bash
+npm install @warlock.js/ai-workspace
+```
+
+It declares `@warlock.js/ai` as a peer and depends on `@warlock.js/fs`; beyond those
+it uses only Node built-ins (`node:child_process` for the shell). Import the package
+once for its side effect so `ai.workspace(...)` is registered:
+
+```ts
+import "@warlock.js/ai-workspace";
+```
+
+## Usage
+
+### 1. Minimal build-loop agent
+
+Hand the whole tool set to an agent and let it read, edit, and run tests until green.
+The failure comes back as tool *data*, so the agent self-corrects.
+
+```ts
+import "@warlock.js/ai-workspace";
+import { ai } from "@warlock.js/ai";
+
+const ws = ai.workspace({
+  cwd: "/srv/acme-api",
+  denyPaths: [".git/**", ".env*"],
+  shell: { allow: ["npm", "node"], inheritEnv: ["PATH"], timeoutMs: 60_000 },
+});
+
+const dev = ai.agent({
+  model: ai.openai.model({ name: "gpt-4o" }),
+  tools: ws.tools.all(),
+  maxTrips: 25,
+});
+
+await dev.execute("`npm test` fails on the cart-total suite. Make it green.");
+```
+
+### 2. Read-only reviewer (least privilege via `tools.pick`)
+
+A reviewer needs to read and search — never to write or run a shell. Pick exactly
+those three tools, or take a `readonly()` projection (which omits every mutating tool
+*and* rejects the mutating direct methods).
+
+```ts
+const ws = ai.workspace({ cwd: "/srv/acme-api" });
+
+const reviewer = ai.agent({
+  model: ai.openai.model({ name: "gpt-4o" }),
+  tools: ws.tools.pick("readFile", "grep", "glob"),
+});
+
+await reviewer.execute("Review src/cart for off-by-one bugs and summarize.");
+
+// Equivalent, as a projection of the same jail:
+const ro = ws.readonly();
+ai.agent({ model, tools: ro.tools.all() }); // read_file + grep + glob only
+```
+
+### 3. Direct programmatic use (no LLM)
+
+Drive the workspace from code — scaffold before an agent runs, or do a mechanical
+bulk migration under the read-before-edit stale-hash guard.
+
+```ts
+const ws = ai.workspace({
+  cwd: "/srv/acme-api",
+  shell: { allow: ["npm"], inheritEnv: ["PATH"] },
+});
+
+// Seed structure, install a dep, then hand off to an agent.
+await ws.writeFile("src/routes.ts", ROUTES_BOILERPLATE);
+await ws.exec("npm install zod");
+
+// Bulk migration — no LLM needed.
+for (const file of await ws.glob("src/models/**/*.ts")) {
+  const { content, hash } = await ws.readFile(file);
+
+  if (content.includes("legacyImport")) {
+    await ws.editFile({
+      path: file,
+      oldString: 'import { legacyImport } from "../legacy";',
+      newString: 'import { modernImport } from "../modern";',
+      replaceAll: true,
+      expectHash: hash, // rejected if the file moved underneath us
+    });
+  }
+}
+```
+
+## What's in this release (W1)
+
+- **Policy jail** — `cwd` path jail (`realpath`-resolved), `allowPaths` / `denyPaths`,
+  a fail-closed shell allow/deny list (deny wins), per-command timeout + output cap,
+  and opt-in `inheritEnv` (no blanket `process.env`).
+- **Backends** — `local` (default; `@warlock.js/fs` + `node:child_process`) and
+  `mock` (in-memory, for hermetic disk-free tests).
+- **Seven tools** under `ws.tools.*` — `read_file`, `edit_file`, `write_file`,
+  `run_shell`, `run_tests`, `grep`, `glob` — each a `ToolContract` ready for
+  `ai.agent({ tools })`.
+- **Direct methods** — `readFile` / `writeFile` / `editFile` / `exec` / `grep` /
+  `glob` / `exists` / `mkdir` / `remove`, sharing the exact same policy seam.
+- **`tools.all()` / `tools.pick(...)`** — every tool, or a least-privilege subset.
+- **`readonly()`** — a projection that vends only read/grep/glob and rejects every
+  mutating direct method.
+- **`scope(subdir)`** — a sub-jailed view rooted at `subdir` (tighter blast radius).
+- **Read-before-edit guard** — `read_file` returns a SHA-256 `hash`; `edit_file`
+  requires an exact, unique `oldString` (or `replaceAll`) and rejects on an
+  `expectHash` mismatch.
+
+**Deferred to later phases** (intentionally absent here): the transactional
+lifecycle (`snapshot` / `restore` / `diff` / `changes`), `on()` hooks, `dispose`,
+`usage()`, and the worktree / container backends plus provisioning helpers.
+
+## Skills
+
+Progressive-disclosure, per-task docs live under [`skills/`](./skills/README.md):
+
+- [`use-a-workspace/`](./skills/use-a-workspace/SKILL.md) — build a jailed workspace
+  and operate it (policy, tools, direct methods, `readonly` / `scope`).
+- [`build-loop-agent/`](./skills/build-loop-agent/SKILL.md) — wire `ws.tools.all()`
+  into a coding agent that reads → edits → runs tests until green.
+```