@warlock.js/ai-workspace 5.34.1 → 5.34.3
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/CHANGELOG.md +12 -0
- package/README.md +1 -1
- package/llms-full.txt +28 -2
- package/llms.txt +3 -2
- package/package.json +3 -3
- package/skills/index.md +1 -1
- package/skills/README.md +0 -13
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,18 @@ All notable changes to `@warlock.js/ai-workspace` are documented in this file.
|
|
|
4
4
|
|
|
5
5
|
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.
|
|
6
6
|
|
|
7
|
+
## 5.34.3 - 2026-10-20
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- Condensed the package agent skill description to at most 450 characters, with API names and package routing guidance.
|
|
12
|
+
|
|
13
|
+
## 5.34.2 - 2026-10-19
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- Point the README at the package skill index, remove the redundant loose catalog, and include orientation in generated LLM projections.
|
|
18
|
+
|
|
7
19
|
## 5.32.0 - 2026-10-18
|
|
8
20
|
|
|
9
21
|
### Changed
|
package/README.md
CHANGED
|
@@ -160,7 +160,7 @@ plus provisioning helpers.
|
|
|
160
160
|
|
|
161
161
|
## Skills
|
|
162
162
|
|
|
163
|
-
Progressive-disclosure, per-task docs live under [`skills/`](./skills/
|
|
163
|
+
Progressive-disclosure, per-task docs live under [`skills/`](./skills/index.md):
|
|
164
164
|
|
|
165
165
|
- [`use-a-workspace/`](./skills/use-a-workspace/SKILL.md) — build a jailed workspace
|
|
166
166
|
and operate it (policy, tools, direct methods, `readonly` / `scope`).
|
package/llms-full.txt
CHANGED
|
@@ -4,7 +4,33 @@
|
|
|
4
4
|
|
|
5
5
|
> Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/ai-workspace/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Package orientation
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
description: 'Policy-confined file and shell tools for coding agents: `workspace`, `createLocalBackend`, `createMockBackend`, `makeEditFileTool`, `makeRunShellTool` and `WorkspacePolicyError`. Use for "let an agent edit files", "sandbox shell commands" or "loop until tests pass". Not this package → @warlock.js/ai-tools for MCP/web tools; @warlock.js/ai for agents; @warlock.js/ai-cli for installed coding CLIs.'
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# @warlock.js/ai-workspace
|
|
14
|
+
|
|
15
|
+
A workspace is a policy jail around a directory: it decides which paths an agent may read or write and which shell commands may run, then exposes read, write, edit, multi-edit, list, glob, grep, shell (argv by default, opt-in `sh`, background commands), test and todo tools bound to that policy. Importing the package registers `ai.workspace(...)` on the shared `ai` object.
|
|
16
|
+
|
|
17
|
+
## The 80% path
|
|
18
|
+
|
|
19
|
+
1. Create a workspace with a root and policy (`use-a-workspace.md`).
|
|
20
|
+
2. Hand its tools to an `ai.agent()`.
|
|
21
|
+
3. For a coding agent, follow the read → edit → run tests loop until green (`build-loop-agent.md`).
|
|
22
|
+
|
|
23
|
+
## Conventions and pitfalls
|
|
24
|
+
|
|
25
|
+
- The policy is the security boundary: keep the root narrow and the shell allowlist explicit; violations throw `WorkspacePolicyError`.
|
|
26
|
+
- Paths resolve inside the jail; escaping it via `..` or symlinks is rejected on purpose.
|
|
27
|
+
- The local backend runs real processes. Use `createMockBackend` in tests so no disk or shell is touched.
|
|
28
|
+
- Shell refusals carry a `reason` and a message that says how to split the command; `interpreter: "sh"` is an explicit opt-in that still checks every command in the line.
|
|
29
|
+
- Call `ws.dispose()` when done: it kills background commands (whole process trees).
|
|
30
|
+
- Edits fail loudly (`WorkspaceEditError`) when the target text is not found; re-read the file rather than retrying blindly.
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
## build-loop-agent `@warlock.js/ai-workspace/skills/build-loop-agent/SKILL.md`
|
|
8
34
|
|
|
9
35
|
---
|
|
10
36
|
name: build-loop-agent
|
|
@@ -108,7 +134,7 @@ ai.supervisor({
|
|
|
108
134
|
- The `run-supervisor` topic of the `warlock-js-ai` skill — coordinating the members that share one workspace.
|
|
109
135
|
|
|
110
136
|
|
|
111
|
-
## use-a-workspace `@warlock.js/ai-workspace/use-a-workspace/SKILL.md`
|
|
137
|
+
## use-a-workspace `@warlock.js/ai-workspace/skills/use-a-workspace/SKILL.md`
|
|
112
138
|
|
|
113
139
|
---
|
|
114
140
|
name: use-a-workspace
|
package/llms.txt
CHANGED
|
@@ -6,5 +6,6 @@
|
|
|
6
6
|
|
|
7
7
|
## Skills
|
|
8
8
|
|
|
9
|
-
- [
|
|
10
|
-
- [
|
|
9
|
+
- [Package orientation](@warlock.js/ai-workspace/skills/index.md): Policy-confined file and shell tools for coding agents: `workspace`, `createLocalBackend`, `createMockBackend`, `makeEditFileTool`, `makeRunShellTool` and `WorkspacePolicyError`. Use for "let an agent edit files", "sandbox shell commands" or "loop until tests pass". Not this package → @warlock.js/ai-tools for MCP/web tools; @warlock.js/ai for agents; @warlock.js/ai-cli for installed coding CLIs.
|
|
10
|
+
- [build-loop-agent](@warlock.js/ai-workspace/skills/build-loop-agent/SKILL.md): Wire a @warlock.js/ai-workspace into a coding agent that closes the read → edit → run-tests loop on its own. Triggers: `ws.tools.all()`, `ai.agent({ tools: ws.tools.all() })`, `maxTrips`, `run_tests`, `run_shell`, 'agent that fixes a failing test', 'make the suite green', 'coding agent that edits a repo', 'build-loop agent', 'self-correcting agent', 'read-only code reviewer', 'scaffold then hand off to an agent', 'share one workspace across a supervisor', 'least-privilege agent tools', 'errors as tool data'; typical wiring `const ws = ai.workspace({ cwd, shell }); ai.agent({ model, tools: ws.tools.all(), maxTrips })`. Skip: constructing the workspace / its policy / direct methods / readonly / scope — the `use-a-workspace` topic; the agent loop / maxTrips / events themselves — the `run-ai-agent` topic of the `warlock-js-ai` skill.
|
|
11
|
+
- [use-a-workspace](@warlock.js/ai-workspace/skills/use-a-workspace/SKILL.md): Build and operate a policy-jailed filesystem + shell workspace with @warlock.js/ai-workspace. Triggers: `ai.workspace`, `workspace(`, `WorkspacePolicy`, `WorkspaceShellPolicy`, `WorkspaceToolName`, `ws.tools.all`, `ws.tools.pick`, `ws.readFile`, `ws.writeFile`, `ws.editFile`, `ws.exec`, `ws.grep`, `ws.glob`, `ws.readonly`, `ws.scope`, `ws.multiEdit`, `ws.listDir`, `ws.startShell`, `ws.shellOutput`, `ws.shellKill`, `ws.dispose`, `ws.readTodos`, `ws.writeTodos`, `WorkspacePolicyError`, `WorkspaceEditError`, `WorkspaceJobError`, `WorkspaceShellRefusalReason`, `checkShellCommand`, `denyPaths`, `denyPatterns`, `allowCommand`, `interpreter`, `shell.background`, `list.ignore`, `inheritEnv`, `expectHash`, `read.maxBytes`, `bytesCapped`, `cancelled`, `ExecOptions`, `tokenizeCommand`, `read_file`/`edit_file`/`multi_edit`/`write_file`/`list_dir`/`run_shell`/`shell_output`/`shell_kill`/`run_tests`/`grep`/`todo_write`/`todo_read`; 'give an agent file tools', 'jail an agent to a directory', 'let an agent read/write/grep a repo', 'read-only workspace for a reviewer', 'scope an agent to a subdirectory', 'run a shell command under policy', 'edit a file with a stale-hash guard', 'command injection guard for an agent shell tool', 'ReDoS-safe grep for an agent', 'cap how many bytes a read returns', 'cancel a running workspace command', 'let the agent use pipes and &&', 'why was my shell command refused', 'deny git push --force', 'run a dev server in the background', 'atomic multi-edit', 'list a directory for an agent', 'todo list tool for an agent'; typical import `import "@warlock.js/ai-workspace"; import { ai } from "@warlock.js/ai"`. Skip: building the agent loop that consumes the tools — the `build-loop-agent` topic; defining a non-filesystem custom tool — the `define-ai-tool` topic of the `warlock-js-ai` skill.
|
package/package.json
CHANGED
|
@@ -19,13 +19,13 @@
|
|
|
19
19
|
"directory": "packages/ai-workspace"
|
|
20
20
|
},
|
|
21
21
|
"peerDependencies": {
|
|
22
|
-
"@warlock.js/ai": "5.34.
|
|
22
|
+
"@warlock.js/ai": "5.34.3"
|
|
23
23
|
},
|
|
24
24
|
"dependencies": {
|
|
25
25
|
"@standard-schema/spec": "^1.0.0",
|
|
26
|
-
"@warlock.js/fs": "5.34.
|
|
26
|
+
"@warlock.js/fs": "5.34.3"
|
|
27
27
|
},
|
|
28
|
-
"version": "5.34.
|
|
28
|
+
"version": "5.34.3",
|
|
29
29
|
"main": "./cjs/index.cjs",
|
|
30
30
|
"module": "./esm/index.mjs",
|
|
31
31
|
"types": "./esm/index.d.mts",
|
package/skills/index.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description:
|
|
2
|
+
description: 'Policy-confined file and shell tools for coding agents: `workspace`, `createLocalBackend`, `createMockBackend`, `makeEditFileTool`, `makeRunShellTool` and `WorkspacePolicyError`. Use for "let an agent edit files", "sandbox shell commands" or "loop until tests pass". Not this package → @warlock.js/ai-tools for MCP/web tools; @warlock.js/ai for agents; @warlock.js/ai-cli for installed coding CLIs.'
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# @warlock.js/ai-workspace
|
package/skills/README.md
DELETED
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
# `@warlock.js/ai-workspace` — skills index
|
|
2
|
-
|
|
3
|
-
Per-task skills. Cross-references name the topic ("the `<topic>` topic"), and for another package add its skill ("the `<topic>` topic of the `warlock-js-<pkg>` skill").
|
|
4
|
-
|
|
5
|
-
## Skills
|
|
6
|
-
|
|
7
|
-
### `use-a-workspace`
|
|
8
|
-
|
|
9
|
-
Build a policy-jailed filesystem + shell workspace with `ai.workspace(policy)` and operate it from both ends — the agent-facing `ws.tools.*` (files, `list_dir`, `multi_edit`, `run_shell` with background commands, `shell_output` / `shell_kill`, `run_tests`, `grep`, `glob`, `todo_write` / `todo_read`, plus `all()` / `pick(...)`) and the human-facing direct methods (`readFile` / `writeFile` / `editFile` / `multiEdit` / `listDir` / `exec` / `startShell` / `shellOutput` / `shellKill` / `grep` / `glob` / `exists` / `mkdir` / `remove` / `readTodos` / `writeTodos` / `dispose`). Covers the policy surface (the `cwd` jail, `allowPaths` / `denyPaths`, the fail-closed shell allow/deny + `denyPatterns` / `allowCommand` + `inheritEnv`, the opt-in `interpreter: "sh"` shell mode and its refusal reasons, read caps, list bounds), the local vs mock backend, the read-before-edit stale-hash guard, the typed `WorkspacePolicyError` / `WorkspaceEditError`, and the `readonly()` / `scope(subdir)` projections. Load when constructing a workspace, choosing a policy, vending tools to an agent, or driving the filesystem programmatically.
|
|
10
|
-
|
|
11
|
-
### `build-loop-agent`
|
|
12
|
-
|
|
13
|
-
Wire a workspace into a coding agent that closes the read → edit → run-tests loop on its own — `ai.agent({ tools: ws.tools.all() })` so a failing suite comes back as tool _data_ and the model self-corrects until green. Covers the minimal build-loop wiring, why errors-as-data drives the loop, the shell policy a test command needs (`shell.allow` + `inheritEnv: ["PATH"]`), the read-only reviewer via `tools.pick` / `readonly()`, scaffolding from code before handing off, and sharing one jail across a supervisor's members. Load when building an agent that edits a repo, runs tests, reviews code, or scaffolds then hands off.
|