Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 64 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -338,23 +338,83 @@ The [`dynamic-workflows` skill](packages/plugin/skill/dynamic-workflows/SKILL.md
| `model` | The launching session's model as `"provider/model#variant"`, or `null` for a headless/synthetic caller. What `agent(…, { model: "inherit" })` and a bare `effort` inherit. |
| `$`, `file`, `fetch` | Shell, files and HTTP, confined to the project and recorded in the Run's activity. |
| `workflow(name, args?)` | Run a saved Workflow as one step of this Run (one level deep). |
| `worktrees()` | The git worktrees kept by `isolation: "worktree"` Units that changed files. |
| `worktrees()` | The git worktrees kept by `worktree: true` Units that changed files. |

`agent()` options: `schema`, `label`, `phase`, `subagent` (alias `agentType`; default `general`), `model`
(`"provider/model#variant"`, `{ providerID, modelID }`, or `"inherit"` for the launching session's model), `effort`
(the reasoning variant; with no `model` the Unit inherits the caller's model at that effort), `retries` (repair turns,
default 2), `timeoutMs`, `permissions`, `isolation: "worktree"` (a fresh git worktree, removed if unchanged),
default 2), `timeoutMs`, `permissions`, `worktree: true` (a fresh git worktree, removed if unchanged),
`isolation` (narrow THIS Unit's policy below `meta.isolation`; see [Isolating a Run](#isolating-a-run)),
`location` (another directory) and `session` (continue an existing session — see [Continuing a Unit](#continuing-a-unit)).
`{ receipts: true }` and `{ keepSession: true }` are separate flags rather than options — see
[Asserting what a Unit did](#asserting-what-a-unit-did) and [Continuing a Unit](#continuing-a-unit).

`meta`: `name`, `description`, `whenToUse`, `phases`, `args` (zod), `concurrency`, `unitTimeout`, `budget` (a number,
or `{ tokens, hard: true }` to stop at the limit), `permissions` (rules for every Unit), `limits`, and
`interaction: { permissions: "ask" | "auto" | "deny", graceMs }`.
or `{ tokens, hard: true }` to stop at the limit), `permissions` (rules for every Unit), `isolation` (skills,
subagents, and MCP servers every Unit may use — deny-by-default; see [Isolating a Run](#isolating-a-run)), `limits`,
and `interaction: { permissions: "ask" | "auto" | "deny", graceMs }`.

Default to `pipeline`. Use `parallel` as a barrier only when a stage needs every result of the previous one, such as
deduplicating findings across all files before verifying them.

### Isolating a Run

By default a Unit sees every skill, subagent, and MCP server the surrounding OpenCode config exposes. To bound that,
declare `meta.isolation` — a **deny-by-default allow-list** (a name not listed cannot be used by any Unit of the Run):

```ts
export default defineWorkflow({
meta: {
name: "audit",
description: "Read-only audit",
isolation: { skills: ["code-markup"], subagents: ["explore"], mcp: ["playwright"] },
},
async run({ agent }) {
await agent("audit the repo", { subagent: "explore" })
},
})
```

Each axis is independent: omit a field to leave that axis unrestricted; `[]` allows nothing. A Workflow that names a
subagent outside `isolation.subagents` fails that Unit **before a session is created**, with a clear message.

**Narrow-only at every level.** Three sources are intersected, so no level can widen another:

| Level | Where | Role |
| --- | --- | --- |
| Workflow | `meta.isolation` | the author's contract |
| Unit | `agent(prompt, { isolation })` | this one Unit tightens further |
| Caller | `workflow({ isolation })` | ad-hoc bound for the caller |

A Workflow can keep its policy in `workflows.json` and import it — the plugin reads no files of its own, an ordinary
JSON import is inlined by the bundler:

```ts
import manifest from "./workflows.json"

export default defineWorkflow({
meta: { name: "audit", description: "…", isolation: manifest.workflows.audit.isolation },
async run({ agent }) { /* … */ },
})
```

Because every level is intersected, an imported policy is a floor: `meta.isolation` (when also set) and a Unit's
a Unit `isolation` can tighten it, never loosen it.

A Unit tightens with its own `isolation`:

```ts
await agent("review only", { subagent: "explore", isolation: { mcp: [] } })
```

For a region of the script where many Units share a tighter policy, `withIsolation(ctx, policy)` returns a view whose
`agent` carries the narrower policy — sugar over the Unit `isolation`. It is **not** a security boundary: `parallel`/`pipeline`
thunks close over whatever `ctx` is in scope, so a thunk that calls the original `ctx.agent` bypasses the view. Use
the Unit `isolation` option when a Unit must be provably narrowed.

MCP is enforced by hiding the disallowed servers' tools from the Unit's toolset and denying them by name as a second
layer — a server not listed is not just refused, it is not shown to the model.

### Typed results

A Unit with a `schema` gets a `workflow_result` tool whose input is your schema. The tool validates each call, so the
Expand Down
2 changes: 1 addition & 1 deletion docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Point a test project at the package directory (OpenCode resolves a directory plu
build whose desktop app hosts `./gui-experimental` bundles; it loads beside the TUI, not instead of it.
- **Web app changes**: `bun run --cwd packages/web dev` serves it with hot reload and forwards `/v1` to
`WF_GATEWAY` (default `http://127.0.0.1:4320`).
- **Worktree Units** (`isolation: "worktree"`) only work when the plugin is configured in a committed
- **Worktree Units** (`worktree: true`) only work when the plugin is configured in a committed
`opencode.json` (or globally): worktrees check out the committed tree.
- **Do not load the checkout where the published package is installed.** A checkout (plugin id = its path) and the
npm package (id `@syn7xx/opencode-dynamic-workflows`) are two plugins to OpenCode: both load, both register
Expand Down
68 changes: 64 additions & 4 deletions packages/plugin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -340,23 +340,83 @@ The [`dynamic-workflows` skill](https://github.com/syn7xx/opencode-dynamic-workf
| `model` | The launching session's model as `"provider/model#variant"`, or `null` for a headless/synthetic caller. What `agent(…, { model: "inherit" })` and a bare `effort` inherit. |
| `$`, `file`, `fetch` | Shell, files and HTTP, confined to the project and recorded in the Run's activity. |
| `workflow(name, args?)` | Run a saved Workflow as one step of this Run (one level deep). |
| `worktrees()` | The git worktrees kept by `isolation: "worktree"` Units that changed files. |
| `worktrees()` | The git worktrees kept by `worktree: true` Units that changed files. |

`agent()` options: `schema`, `label`, `phase`, `subagent` (alias `agentType`; default `general`), `model`
(`"provider/model#variant"`, `{ providerID, modelID }`, or `"inherit"` for the launching session's model), `effort`
(the reasoning variant; with no `model` the Unit inherits the caller's model at that effort), `retries` (repair turns,
default 2), `timeoutMs`, `permissions`, `isolation: "worktree"` (a fresh git worktree, removed if unchanged),
default 2), `timeoutMs`, `permissions`, `worktree: true` (a fresh git worktree, removed if unchanged),
`isolation` (narrow THIS Unit's policy below `meta.isolation`; see [Isolating a Run](#isolating-a-run)),
`location` (another directory) and `session` (continue an existing session — see [Continuing a Unit](#continuing-a-unit)).
`{ receipts: true }` and `{ keepSession: true }` are separate flags rather than options — see
[Asserting what a Unit did](#asserting-what-a-unit-did) and [Continuing a Unit](#continuing-a-unit).

`meta`: `name`, `description`, `whenToUse`, `phases`, `args` (zod), `concurrency`, `unitTimeout`, `budget` (a number,
or `{ tokens, hard: true }` to stop at the limit), `permissions` (rules for every Unit), `limits`, and
`interaction: { permissions: "ask" | "auto" | "deny", graceMs }`.
or `{ tokens, hard: true }` to stop at the limit), `permissions` (rules for every Unit), `isolation` (skills,
subagents, and MCP servers every Unit may use — deny-by-default; see [Isolating a Run](#isolating-a-run)), `limits`,
and `interaction: { permissions: "ask" | "auto" | "deny", graceMs }`.

Default to `pipeline`. Use `parallel` as a barrier only when a stage needs every result of the previous one, such as
deduplicating findings across all files before verifying them.

### Isolating a Run

By default a Unit sees every skill, subagent, and MCP server the surrounding OpenCode config exposes. To bound that,
declare `meta.isolation` — a **deny-by-default allow-list** (a name not listed cannot be used by any Unit of the Run):

```ts
export default defineWorkflow({
meta: {
name: "audit",
description: "Read-only audit",
isolation: { skills: ["code-markup"], subagents: ["explore"], mcp: ["playwright"] },
},
async run({ agent }) {
await agent("audit the repo", { subagent: "explore" })
},
})
```

Each axis is independent: omit a field to leave that axis unrestricted; `[]` allows nothing. A Workflow that names a
subagent outside `isolation.subagents` fails that Unit **before a session is created**, with a clear message.

**Narrow-only at every level.** Three sources are intersected, so no level can widen another:

| Level | Where | Role |
| --- | --- | --- |
| Workflow | `meta.isolation` | the author's contract |
| Unit | `agent(prompt, { isolation })` | this one Unit tightens further |
| Caller | `workflow({ isolation })` | ad-hoc bound for the caller |

A Workflow can keep its policy in `workflows.json` and import it — the plugin reads no files of its own, an ordinary
JSON import is inlined by the bundler:

```ts
import manifest from "./workflows.json"

export default defineWorkflow({
meta: { name: "audit", description: "…", isolation: manifest.workflows.audit.isolation },
async run({ agent }) { /* … */ },
})
```

Because every level is intersected, an imported policy is a floor: `meta.isolation` (when also set) and a Unit's
a Unit `isolation` can tighten it, never loosen it.

A Unit tightens with its own `isolation`:

```ts
await agent("review only", { subagent: "explore", isolation: { mcp: [] } })
```

For a region of the script where many Units share a tighter policy, `withIsolation(ctx, policy)` returns a view whose
`agent` carries the narrower policy — sugar over the Unit `isolation`. It is **not** a security boundary: `parallel`/`pipeline`
thunks close over whatever `ctx` is in scope, so a thunk that calls the original `ctx.agent` bypasses the view. Use
the Unit `isolation` option when a Unit must be provably narrowed.

MCP is enforced by hiding the disallowed servers' tools from the Unit's toolset and denying them by name as a second
layer — a server not listed is not just refused, it is not shown to the model.

### Typed results

A Unit with a `schema` gets a `workflow_result` tool whose input is your schema. The tool validates each call, so the
Expand Down
75 changes: 73 additions & 2 deletions packages/plugin/skill/dynamic-workflows/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ export default defineWorkflow({
| `model` | The launching session's model (`"provider/model#variant"`), or `null` for a headless/synthetic caller. What `agent(…, { model: "inherit" })` and a bare `effort` inherit. |
| `$`, `file`, `fetch` | Shell, files and HTTP, confined to the project (see below). |
| `workflow(name, args?)` | Run a **saved** Workflow as one step of this Run and get its result (see below). |
| `worktrees()` | The worktrees kept by `isolation: "worktree"` Units that changed files. |
| `worktrees()` | The worktrees kept by `worktree: true` Units that changed files. |

### `agent()` options

Expand All @@ -84,6 +84,7 @@ export default defineWorkflow({
| `timeoutMs` | A deadline for this Unit. There is none by default. |
| `permissions` | Rules for this Unit's session, e.g. `[{ action: "edit", resource: "*", effect: "deny" }]`. |
| `isolation` | `"worktree"`: run the Unit in a fresh git worktree — for Units that **edit files in parallel** (see below). |
| `isolation` | Narrow THIS Unit's access below the Workflow (`{ skills?, subagents?, mcp? }`). Intersected, never replaces: a Unit can tighten, never widen. Use when one Unit legitimately needs fewer skills/subagents/MCP servers than the rest. |
| `location` | Run the Unit in a directory you prepared yourself. |
| `session` | Send this turn into an existing session (`handle.sessionID`) — a follow-up, not a new Unit session. Refuses `subagent`, `model`, `effort`, `location`, `isolation`, `permissions`. |

Expand Down Expand Up @@ -262,7 +263,7 @@ Parallel Units editing the same checkout overwrite each other. Give each its own

```ts
const results = await pipeline(modules, (m) =>
agent(`Migrate ${m} to the new API. Commit your change with a clear message.`, { label: m, isolation: "worktree" }),
agent(`Migrate ${m} to the new API. Commit your change with a clear message.`, { label: m, worktree: true }),
)
for (const tree of worktrees()) log(`review and merge: ${tree.branch} (${tree.directory})`)
```
Expand All @@ -272,6 +273,76 @@ script (or the person) can merge it — e.g. a final Unit, or `$\`git merge ${br
and disk: use them only for Units that write. The plugin must be active in the worktree, so it has to be
configured in a committed `opencode.json` (or globally); otherwise those Units fail with a clear message.

## Isolating what a Unit may use

A Unit sees whatever skills, subagents, and MCP servers the surrounding OpenCode config exposes. When a Workflow must
run predictably — regardless of what else is installed locally — declare `meta.isolation`: a **deny-by-default
allow-list** on three independent axes. A name not listed cannot be used by any Unit of the Run.

```ts
import { defineWorkflow } from "@syn7xx/opencode-dynamic-workflows/workflow"

export default defineWorkflow({
meta: {
name: "audit",
description: "Read-only audit that cannot touch the delivery toolchain",
isolation: { skills: ["code-markup"], subagents: ["explore"], mcp: ["playwright"] },
},
async run({ agent }) {
await agent("audit the repo", { subagent: "explore" })
},
})
```

- Each axis is independent: **omit** a field to leave that axis unrestricted; `[]` allows nothing on it.
- A Unit naming a subagent outside `isolation.subagents` fails **before a session is created**, with a clear message —
a misconfiguration surfaces immediately, not as a denied tool mid-turn.
- MCP is enforced twice: the disallowed servers' tools are **hidden** from the Unit's toolset (the model never sees
them) and, as a second layer, denied by name if the model invents one.

**Narrow-only, three levels.** Every level is intersected (`meta ∩ unit ∩ caller`), so nothing can widen
anything else:

| Level | Where | When to use |
| -------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Imported | `import manifest from "./workflows.json"` → `meta.isolation` | the policy lives in a JSON file you import; the plugin reads no files itself |
| Workflow | `meta.isolation` | the default for the whole Run — declare it here |
| Unit | `agent(prompt, { isolation })` | one Unit legitimately needs fewer skills/subagents/MCP than the rest |
| Caller | `workflow({ isolation })` | an ad-hoc bound for a Workflow that declares nothing |

A policy kept in a JSON file (e.g. `workflows/workflows.json`) is imported, not read by the plugin:

```ts
// workflows/audit.ts — the policy is inlined from the imported JSON by the bundler
import manifest from "./workflows.json"
// meta: { …, isolation: manifest.workflows.audit.isolation }
```

Tighten a single Unit when it needs a smaller surface than the Workflow:

```ts
await agent("review only", { subagent: "explore", isolation: { mcp: [] } })
```

`withIsolation(ctx, policy)` returns a view whose `agent` carries the narrower policy — sugar over the Unit `isolation` for a region
where many Units share a tighter policy:

```ts
import { withIsolation } from "@syn7xx/opencode-dynamic-workflows/workflow"

async run(ctx) {
const viewing = withIsolation(ctx, { mcp: ["playwright"] })
await viewing.agent("look, don't touch")
}
```

It is **not a security boundary**: `parallel`/`pipeline` thunks close over whatever `ctx` is in scope, so a thunk
that calls the original `ctx.agent` bypasses the view. Use the Unit `isolation` option when a Unit must be provably narrowed.

Guidance: put the Run-wide bound in `meta.isolation` (one place, easy to review); reach for the Unit `isolation` only when a
Unit genuinely differs. Do not use permissions for isolation — a `permissions` rule can `allow` but cannot narrow
what `meta.isolation` already permits.

## pipeline by default

Default to `pipeline`. Use a barrier only when a stage needs cross-item context from _all_ results of the previous
Expand Down
Loading
Loading