foldrun 1.0.0 → 1.1.1

package/bin/foldrun.mjs

@@ -107,6 +107,7 @@ const HELP = `foldrun — agents are just folders
   foldrun agent run <name>  run one agent once on the platform (--task "…", --to, --wait, --test)
   foldrun agent link <agent>  add to its team, in its frontmatter: --subagent <worker>, --consult <agent> or --can-ask (--description for a worker with none)
   foldrun agent unlink <agent>  take one away: --subagent <name>, --consult <name> or --can-ask
+  foldrun agent network <agent>  the sites its sandbox may reach; set the level (open, trusted, none, inherit) and --add / --remove <site> (repeatable)
   foldrun agent import <workspace>/<agent>  copy an agent you already have in another workspace into this one — its agent.md, own skills and scripts, not its memory (--as <name>, --workspace <name>; --to <ws> on the platform)
   foldrun agent import --list  what could be imported into a deployed workspace: every other workspace you can read, and its agents (--to, --json)
   foldrun flow add <flow> <pattern>  one canvas block as a markdown edit: chain, parallel, router, fan-out, loop, approval, ask, wait, rescue, subflow — diff shown, checked, --dry-run
@@ -122,6 +123,8 @@ const HELP = `foldrun — agents are just folders
   foldrun flow copy-step <flow> --step <n|agent>[,<n>…]  the steps' markdown on stdout, as the canvas's Copy
   foldrun flow paste <flow>  step markdown from stdin or --file in as new groups (--after <g>, default last) or beside one (--group <g>) — diff, checked, --dry-run
   foldrun flow draft "<what it should do>"  Draft with AI on the platform (--to; --flow <name> redrafts one): shows the files and the check, saves on yes (--yes, --dry-run)
+  foldrun assistant ["<message>"]  the dashboard's assistant (also: foldrun ai): answers from the foldrun docs and the deployed workspace's files, writes agents, flows, tools and skills as diffs with the check, saves on yes (--to, --yes, --dry-run, --json); every reply is kept — --conversation <id> carries one on; no message in a terminal is a conversation (/save, /files, /drop, /new, /quit)
+  foldrun assistant history  your kept conversations, newest first (--q <text> searches them, --workspace, --json); show <id> prints one, rm <id> deletes it
   foldrun tool test <name>  exercise one tool alone, no model and no run (key=value args, --to)
   foldrun hook ls           the hooks in this workspace and the account library: on, tool, description — invalid ones with the reason (--json); --to <ws>: the DEPLOYED workspace's, who turns each on, and what they denied, rewrote or failed lately (--runs <n>, --all)
   foldrun hook add <name> --on <event>  a hook folder: hook.md and a run.mjs that allows everything, the contract in its comments (--tool <pattern>, --library, --to)
@@ -184,7 +187,8 @@ const HELP = `foldrun — agents are just folders
   foldrun restore <ws> --to <commit|time|age>  put a workspace's source back as it was then — shows the change, asks for the name typed back (--dry-run: the diff only, --yes)
   foldrun backups           how the account is backed up (encrypted?), when it last was, the snapshots it is in — also request --what runs|state|storage|everything --at "<when>" [--to <ws>] [--note]
   foldrun backups requests  every restore asked of the platform team, and where each stands (--json)
-  foldrun secrets set NAME  store a secret (prompted, never echoed) — also ls, rm, status; --kind file|ssh|api|service-account|m2m for the other shapes
+  foldrun secrets set NAME  store a secret (prompted, never echoed) — also ls, rm, status; --kind file|ssh|api|service-account|m2m for the other shapes; --site <domain> (repeatable) binds it as it is stored
+  foldrun secrets sites NAME [site…]  bind a secret to sites: the egress proxy fills it for those alone and it never enters a sandbox; no sites lists them, --clear unbinds
   foldrun secrets clients   the OAuth clients saved on the platform — also add <name> (--provider or --authorize-url/--token-url, --client-id, --scopes), rm <name>
   foldrun connect NAME      OAuth sign-in from the terminal, stored as an auto-refreshing secret — --client <saved> runs it from a saved client through the platform
   foldrun deploy [dir]      push the whole account, or deploy <workspace> for one of them
@@ -288,12 +292,16 @@ Options
   --step <n>                approve, reject: decide only that step; default is every step that is waiting
   --payload <json|text|@f>  approve: release a step waiting on wait: event with this body, recorded as you
   --note "<text>"           approve, reject: guidance the agent reads — or the reason for a refusal; billing credit: the ledger line's note
-  --yes                     approve, stop, rerun (bulk), flow rotate-hook, flow draft, history restore, restore <ws>, import, billing plan, repo, workspace set name, and every rm/revoke/unshare: skip the confirmation, deliberately (required with no terminal)
+  --yes                     approve, stop, rerun (bulk), flow rotate-hook, flow draft, assistant, history restore, restore <ws>, import, billing plan, repo, workspace set name, and every rm/revoke/unshare: skip the confirmation, deliberately (required with no terminal)
   --json                    report: the raw run record instead of the report; observe, usage, api version, changelog, find, preferences, workspace vocabulary, flags, workspaces, workspaces show, agent ls, flow ls, agent import --list, backups requests, team, hook ls: the raw document; version: {cli, core, platform}
   --events <a,b>            account set notify: failed, awaiting-approval, completed
   --failed                  webhooks deliveries: only the ones that gave up
   --limit <n>               runs, billing, history, changelog: how many rows
   --value "<text>"          secrets set: skip the prompt (careful with shell history)
+  --site <domain>           secrets set, secrets sites: a site the secret is bound to — the egress proxy fills it for those alone (repeatable, or a,b)
+  --clear                   secrets sites: unbind it
+  --add <site>              agent network: add a site to its network: list (repeatable)
+  --remove <site>           agent network: take a site off its network: list (repeatable)
   --out <file>              api spec: where to write the OpenAPI document (default: stdout)
   --file <path>             source put, library put, flow paste: the local file to send (default: stdin); secrets set --kind file|service-account: the file it holds; storage get, report get, report live, account export, export, billing statement: where to write it (- for stdout)
   --message "<why>"         source put: recorded on the file's revision
@@ -331,7 +339,7 @@ Platform options (deploy, invoke, secrets, logs, keys)
   --local                   deploy: into the installation on this machine, even when signed in
   --commit <sha>            deploy: record which commit this is
   --overwrite               import: replace files the workspace already has with different text (refused otherwise)
-  --dry-run                 deploy: check and report, change nothing; flow add, flow set, flow trigger, flow move-step, flow paste, flow draft, history restore, agent link, agent unlink: show the diff, write nothing; restore <ws>: the diff only, restore nothing; import: the preview only, write nothing; stop, rerun (bulk): list what matches, touch nothing
+  --dry-run                 deploy: check and report, change nothing; flow add, flow set, flow trigger, flow move-step, flow paste, flow draft, assistant, history restore, agent link, agent unlink: show the diff, write nothing; restore <ws>: the diff only, restore nothing; import: the preview only, write nothing; stop, rerun (bulk): list what matches, touch nothing
   --no-runtimes             deploy: do not wait for the workspace's environments to be built
   --force                   deploy: deploy even while runs are in flight; pull, storage get: overwrite local files
   --yes                     deploy: allow deleting files this folder no longer has (asked otherwise; required with no terminal)
@@ -352,9 +360,9 @@ if (!command || command === "--help" || command === "-h") {
 // `--value` as the account's argument and stored an empty secret; `--force
 // ./dir` swallowed the directory. A flag followed by another flag is also
 // boolean, so an unlisted switch at least does not eat its neighbour.
-const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library"]);
+const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear"]);
 // Flags said more than once collect into a list: `--tag a --tag b`.
-const REPEATABLE = new Set(["tag", "expect", "header"]);
+const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove"]);
 // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
 // a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
 // taken, so `invoke x --wait` and friends are as they were.

package/docs/agents.md

@@ -65,6 +65,7 @@ the point of the week; a step that weighs two arguments and picks one is not.
 | `mcpServers` | an MCP server declared inline |
 | `secrets` | vault entries its tools may use — names only, never values |
 | `limits` | the most calls one step may make — per tool, per web action, or in all: `limits: {web.search: 40, crm: 20, calls: 300}`. A call past a limit is refused, never run ([Tools](tools#limits--how-many-calls-a-step-may-make)) |
+| `network` | which sites its sandbox may reach: `open`, `trusted` or `none`, or a list of sites added to the trusted list — `network: [api.hubapi.com]`. Unset, an agent that may fetch or browse the web is `open` and every other `trusted`. Also in a workspace's or the account's `AGENTS.md` ([Network](network)) |
 | `permissionMode` | `plan` makes the run read-only, whatever else was granted |
 | `web` | the `web` tool's settings: `actions:` — which of its eight it may use (all when absent) — and who does each, `web: {search: brave, fetch: jina, browse: browserbase, crawl: firecrawl}`, with the key named in the vault. Unset is foldrun's own. `search:` also takes a block of the own engine's settings — engines, categories, safesearch, plugins ([Tools](tools#tuning-the-accounts-own-engine)); `browse:` a block of the browser's ([below](#webbrowse--which-browser-and-how-it-presents-itself)), and `browse:` alone cascades from `AGENTS.md`. The providers and their keys: [Tools](tools#reaching-the-web). A per-action key outside the block is not read — `check` errors on it |
 

package/docs/api.md

@@ -65,7 +65,7 @@ api workspaces/$WS/flows/publish/run -X POST   # start a flow
 
 | Route | Methods | |
 |---|---|---|
-| `/api/workspaces` | GET, POST | list; create (`name`, plus one of: `template: true` — blank, just an AGENTS.md, what the dashboard sends; `starter: true` — the example researcher, writer and publish flow; `demo: true`; `files`) |
+| `/api/workspaces` | GET, POST | list; create (`name`, plus one of: `template: true` — blank, just an AGENTS.md, what the dashboard sends; `starter: true` — the example researcher, writer and publish flow; `demo: true`; `files`). A POST to a name that exists deploys over it; add `ifAbsent: true` to create only — a name that exists is then `409` and nothing changes, decided atomically (the assistant's Create workspace and `foldrun assistant` send it) |
 | `/api/workspaces/<ws>` | GET, PATCH, DELETE | read; rename or re-describe (`name`, `description`), or set its defaults (`timezone`, `budget`, `notify` — null clears one, edited in AGENTS.md in place); delete |
 | `/api/workspaces/<ws>/vocabulary` | GET | which document kinds this workspace admits — its `docs` list is what `[[ ]]` resolves: knowledge, memory, `state/` and `storage/` files, plus the folders themselves |
 
@@ -145,12 +145,35 @@ Left out, `test` is decided by the platform:
 a preview workspace's runs are tests unless the flow says `live: true`;
 everywhere else a run is live.
 
+## Assistant
+
+| Route | Methods | |
+|---|---|---|
+| `/api/workspaces/<ws>/assistant` | POST | one reply from the assistant, which answers from the foldrun docs and this workspace's files only and writes agents, flows, tools and skills: `{ messages: [{ role: "user"\|"assistant", content }], files?: [{ path, content }], page?, conversation? }` — the conversation so far (the last message the person's, at most 8,000 characters), the files it proposed that are not saved yet, and the dashboard page being looked at. Returns `{ ok, reply, files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], sources: [{ doc, section, url }], supply, workspace, usage, chargedUsd }` — `files` is every unsaved proposal as it now stands, checked; `workspace` is `{ name, purpose }` when it proposes a new workspace (free and kebab-case when proposed; create it with `POST /api/workspaces { name, template: true }`, then talk to the assistant there), else `null`; `usage` is `{ inputTokens, outputTokens, costUsd }` across every model call of the reply; `chargedUsd` what the account was charged for it on the platform's models (the same price as a run's tokens), `null` on its own provider; `conversation` is the id it was kept under — send it back as `conversation` to carry on (without one, a new conversation starts). **Writes nothing**; save with the source PUT (`ifMatch` the `sha256`, `null` for a new file). With `Accept: text/event-stream` it streams `status` (what it is reading), `text` (the reply as it is written), then `done` with the same body, or `error`. Needs `workspace:write`; 60 replies an hour per person or key, and on the platform's models 300 a day per account (`429`); at most 200 messages of 60,000 characters each (`413`). Closing the stream does not stop the reply: it finishes (at most $2, 30 tool calls, five minutes) and is charged; a Chat-Completions `provider:` is `422`. On the platform's models the balance is checked first (`402`) and each reply is one ledger line, flow `ai-assistant` |
+| `/api/assistant/conversations?workspace=&q=&limit=` | GET | the asker's kept assistant conversations — a person's own, or a key's own — newest first, across the workspaces they may see: `{ conversations: [{ id, workspace, title, updatedAt, messages, unsaved }] }`. `q` searches the titles and every message; `workspace` narrows to one; `limit` 1–200 (50) |
+| `/api/assistant/conversations/<id>` | GET, DELETE | one kept conversation, whole: `{ id, workspace, title, messages: [{ role, content, meta? }], files, createdAt, updatedAt }` (`meta` is what the dashboard draws under a reply: sources, tokens, charge, a proposed workspace); DELETE removes it. Anyone else's id is `404`, the same as none |
+
+It may propose only `flows/<name>.md`, `agents/<name>/agent.md`,
+`skills/<name>/SKILL.md` (and files under the skill's `scripts/`,
+`references/` or `assets/`), and `tools/<name>/tool.md` with its program, or
+`tools/<name>.md`. It reads the workspace's source and the account library,
+never `state/`, `storage/`, runs or secrets. A proposal is checked with the
+deploy's checks and the flow lint; a frontmatter key the docs never name, and
+a value shaped like a credential, are errors.
+
+A reply is not computed by the web: it is queued, and the platform's
+assistant workers answer it — a pool of their own that scales with the
+queue, so a burst of questions never slows the dashboard or takes a run's
+turn. At most three replies of one account run at once. Each reply is kept
+as a conversation private to whoever asked; the caller still sends the
+history with each message.
+
 ## Agents and evals
 
 | Route | Methods | |
 |---|---|---|
 | `/api/workspaces/<ws>/agents` | GET, POST | list; create (`name`) |
-| `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description", value } }`. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
+| `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description", value } }`, or `{ network }` — the sites its sandbox may reach: `"open"`, `"trusted"`, `"none"`, a list of sites, or `{ level, allow, defaults }`; `null` removes the line so it inherits ([Network](network)). A `network` nobody could read is a 400 that says why. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
 | `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run) |
 | `/api/workspaces/<ws>/agents/import` | GET, POST | copy an agent in from another workspace of the account. GET lists what could be imported (every other workspace you can read, with its agents). POST `{ from, agent, as? }` copies `agents/<agent>/` — its agent.md and own skills/, scripts/, knowledge/; never memory/, outputs/, state/ — and answers `{ name, files, warnings }`; `warnings` names tools, skills, scripts and secrets the copy uses that this workspace lacks. 409 on a name clash (pass `as`), 404 for an unknown workspace or agent, 403 when `from` is outside your key's scope. Idempotent |
 | `/api/workspaces/<ws>/export` | GET | this workspace, one flow or one agent as a `.zip` — `?kind=flow&name=<flow>` (the flow, every flow it runs as a step, every agent those steps and their colleagues name, and the workspace tools, skills and scripts they grant), `?kind=agent&name=<agent>` (its folder and what it grants), or neither for the whole authored tree. Never memory/, state/, outputs/, storage, runs or a secret's value; `foldrun-package.json` inside says what it is. Any role that can read the workspace |
@@ -293,7 +316,7 @@ its header and requires a URL it can GET for itself.
 
 | Route | Methods | |
 |---|---|---|
-| `/api/secrets?workspace=` | GET, PUT, DELETE | the vault: list which secrets exist (never a value); set one (`name` plus one shape, below); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. PUT is idempotent |
+| `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set` |
 
 `PUT` takes `name` plus exactly one shape: `value` (a string), `file` (a PEM,
 a cert), `oauth2`, `service_account`, `ssh`, or `api`. They go to the vault;

package/docs/assistant.md

@@ -0,0 +1,139 @@
+# Assistant
+
+The assistant is a panel on every page of the dashboard. Ask it how
+foldrun works, or describe what you want built. It writes agents, flows,
+tools and skills for a workspace and shows each one as a diff, checked, for
+you to save.
+
+Open it with **Ask AI** at the bottom right. **Draft with AI** on the Flows
+page opens it too, with "Draft a flow that" ready to finish.
+
+Inside a workspace it works in that workspace. Anywhere else, such as the
+account home, Billing or the docs, it works in the one chosen in its header;
+your browser remembers the choice. Each workspace keeps its own conversation.
+
+## What it knows
+
+Only two things:
+
+- **foldrun's docs**, these pages. It searches them and reads the sections
+  it needs before it answers, and it cites what it used as
+  `[doc › section]`, which links to the heading. Under each reply,
+  **Read N doc sections** lists them.
+- **This workspace's files**: its `AGENTS.md`, agents, flows, skills,
+  tools, hooks, knowledge, evals and scripts, plus the account library and
+  the account's `AGENTS.md`. It never reads `state/`, `storage/`, runs or
+  secrets.
+
+It has no web access, no shell and no other tools. If the docs do not cover
+something, it says so; it does not guess. Anything that is not about
+building on foldrun gets a one-line refusal. Text inside your files is
+treated as data, never as instructions to it.
+
+## What it writes
+
+Only these paths:
+
+| Kind | Path |
+|---|---|
+| a flow | `flows/<name>.md` |
+| an agent | `agents/<name>/agent.md` |
+| a skill | `skills/<name>/SKILL.md`, and files under the skill's `scripts/`, `references/` or `assets/` |
+| a tool | `tools/<name>/tool.md` with its program beside it, or `tools/<name>.md` |
+
+When something else needs to change, such as `AGENTS.md`, a secret or a
+setting, it tells you what and where, and you make that change.
+
+## New workspaces
+
+When you ask for a new workspace, or describe a separate desk or pipeline,
+it proposes one: a name and what it is for, with a **Create workspace**
+button. Creating it needs `workspace:manage` (admin or owner). The workspace
+starts blank, with only its `AGENTS.md`. The dashboard then opens it, and the
+conversation carries on there: the assistant writes the new workspace's
+agents, flows, tools and skills for you to save.
+
+It never proposes a name that is taken. An account with no workspace yet
+gets a box to name its first one.
+
+Every file it proposes is checked as it writes it, and the model sees the
+result and fixes errors before it finishes:
+
+- the [deploy's own checks](deploying) and the flow lint, over the workspace
+  as it would be with the file in it;
+- a frontmatter key that appears nowhere in these docs is an error, because
+  foldrun would not read it;
+- a value shaped like a credential (an API key, a token, a private key) is
+  an error. Secrets go in the vault; see [Secrets](secrets);
+- a skill needs `name:` (its folder) and `description:`;
+- a script tool's `run:` program must be proposed or already exist.
+
+Anything still wrong after that is shown beside the file, not hidden.
+
+## Saving
+
+Nothing is written until you press **Save** on a file, or **Save all**. Each
+save goes through the same write as the editor: one revision per file, with
+the note "written with the assistant: …", which you can restore from
+[History](backups-and-restore). If a file changed after it was proposed, the
+save is refused and nothing is overwritten; ask the assistant to propose it
+again.
+
+Saving is not deploying. On the platform, the saved file is the workspace's
+source, the same as an edit in the dashboard.
+
+## History
+
+Every reply is kept. **History** in the panel's header lists your
+conversations, newest first and grouped by day, across every workspace you
+can see; type to search them, by title or by anything said in them. Open one
+to carry it on: the files it proposed and you did not save come back with
+it, and the panel moves to its workspace. **New chat** starts another.
+
+Conversations are yours alone. Nobody else in the account, owners included,
+can list or read them; an API key's conversations belong to that key. Each
+person keeps their newest 500.
+
+## Where it runs
+
+Not in the dashboard. Each reply is queued and answered by the platform's
+assistant workers, a pool of its own that grows with the queue, so a burst
+of questions never slows the dashboard or takes a turn from your runs. At
+most three replies of one account run at once; more wait their turn, and the
+panel says so. The model only ever reads through the assistant's own tools,
+on the server, scoped to your account and workspace; it runs no code and has
+no network or shell of its own.
+
+## Who can use it, and what it costs
+
+You need to be able to edit the workspace (`workspace:write`: editor,
+admin or owner). Viewers do not see the button enabled.
+
+Each reply is one model call that may use several tools, on the same models
+your runs use: the workspace's or account's own [provider](providers) or
+key when there is one, otherwise the platform's. On the platform's models
+the balance is checked first, and the reply is charged at the same price as
+a run's tokens, as one line on [usage](budgets-and-billing), flow
+`ai-assistant`. On your own provider or key, that provider bills you and
+foldrun charges nothing.
+
+Under every reply is what it used: tokens in (cache reads included) and out,
+and what it was charged, or "on your own model key". One reply is capped at
+$2, 30 tool calls and five minutes. Each person or key can send 60 replies an
+hour, and when the platform's models answer, an account can send 300 a day.
+
+**Stop** stops what you see, not the reply: it finishes on the server within
+those caps and is charged, because what a reply cost is only known when it
+ends. Its answer is in **History**.
+
+## From a terminal, and the API
+
+`foldrun assistant "<message>" --to <workspace>` (or `foldrun ai`) asks
+once, prints the reply, what it read and every proposed file as a diff, and
+saves on yes. With no message, in a terminal, it is a conversation.
+`foldrun assistant history` lists your kept conversations and
+`--conversation <id>` carries one on. See [CLI](cli).
+
+The route is `POST /api/workspaces/<ws>/assistant`. It writes nothing and
+returns the proposals for you to save with the source PUT. See
+[API](api#assistant).

package/docs/cli.md

@@ -47,6 +47,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun agent import <workspace>/<agent>` | copy an agent you already have in another workspace into this one: its `agent.md` and own `skills/`, `scripts/`, `knowledge/` — never `memory/`, `outputs/` or `state/`. Into the workspace you stand in, or `--workspace <name>`; `--as <name>` imports it under another name (and rewrites `name:`), which a name clash requires. `--to <workspace>` does it on the platform (`POST /api/workspaces/<ws>/agents/import`) and lists the tools, skills, scripts and secrets the copy uses that the workspace lacks. See [Importing an agent](workspaces#importing-an-agent-you-already-have) |
 | `foldrun agent import --list` | what could be imported into a deployed workspace: every other workspace this key may read, and each one's agents with their descriptions (`GET …/agents/import`). Imports nothing. `--to <workspace>`, `--json` |
 | `foldrun agent unlink <agent>` | take one away: `--subagent <name>`, `--consult <name>` or `--can-ask`. An emptied list is written `key: []`, not deleted. In this folder, refused the same way, nothing written, when the file changed since it was read |
+| `foldrun agent network <agent> [open\|trusted\|none\|inherit]` | which sites the agent's sandbox may reach ([Network](network)). Alone, prints what a run resolves — the level, where it came from, the sites added. With a level and/or `--add <site>` / `--remove <site>` (repeatable), rewrites the one `network:` line of its `agent.md` — the edit the dashboard's Network card makes — prints the diff and the new resolution; `inherit` drops the agent's own level, and a line with nothing left to say is removed. `--dry-run` writes nothing; `--to <workspace>` edits the deployed copy through `PATCH /api/workspaces/<ws>/agents/<name>` |
 | `foldrun flow add <flow> <pattern>` | one palette block from the [flow canvas](flows#editing-on-the-canvas), as the same markdown edit the canvas writes (core's `flow-patterns`): `chain` (alias `step`: `--agent <name>`, `--instruction "…"`, `--after <n>` or `--before <n>`, default last), `parallel` (`--agent`, `--group <n>`), `router` (`--agent <triage>`, `--cases BUG=bugs,DOCS=docs`, `--else <agent>`, `--after`), `fan-out` (`--step`, `--each lines\|items\|"rows of <path>"`, `--max <n>`), `loop` (alias `evaluator`: `--step`, `--loop <n>` default 3, `--until <MARKER>` default APPROVED, `--judge "<claim>"` adds `verify: judge:`), `approval` (`--step`; the `!` marker, `approve: true` on a `?` step), `ask` (`--step`, `--question "…"`), `wait` (`--step`, `--wait 30m\|event`), `rescue` (`--step`, `--on-fail <agent>`), `subflow` (`--flow <other>`, `--after`). `--step` is the step's place in the file (1 = the first step line) or the agent it runs; `--off` takes a step pattern back off. Prints the diff, runs the rules `check` runs over the result and refuses — writing nothing — an edit that would add an error; one that was there before does not block it. `--dry-run` shows the diff and writes nothing. In this folder by default; `--to <workspace>` edits the deployed copy through the canvas's own route (`PATCH …/flows/<flow>` with `{ edit }`), and the sha256 of the file it read as `expect`: one edited meanwhile is refused (`409`), nothing written. In this folder it re-reads the file just before writing — after the y/N, after `check` — and refuses the same way, writing nothing, when it changed since it was read |
 | `foldrun flow rm-step <flow> --step <n\|agent>` | delete one step, as the canvas's × does (core's `removeStep`): the step line and its indented options go, the groups after an emptied one renumber, prose and the agent's file are untouched. Says what else changes first (`case:`/`when:` steps that will route on the step before, the renumbering), prints the diff, refuses one `foldrun check` would call a new error, then asks — no terminal needs `--yes`. `--step` is the step's place in the file (1 = the first step line) or the agent it runs. `--dry-run` writes nothing; `--to <workspace>` sends the canvas's `PATCH …/flows/<flow>` with `{ edit: { op: "remove", step } }`, and the sha256 of the file it read as `expect`: one edited meanwhile is refused (`409`), nothing written. In this folder it re-reads the file just before writing — after the y/N, after `check` — and refuses the same way, writing nothing, when it changed since it was read |
 | `foldrun flow dup-step <flow> --step <n\|agent>` | duplicate one step, as the canvas's Duplicate (Cmd/Ctrl+D) does (core's `duplicateStep`): a copy of the step line — its `?`/`!` marker and every indented option — goes directly under it with the same group number, so the copy runs in parallel with the original; nothing else moves. Prints the diff and refuses one `foldrun check` would call a new error; additive, so it does not ask. `--dry-run` writes nothing; `--to <workspace>` sends `PATCH …/flows/<flow>` with `{ edit: { op: "duplicate", step } }`, and the sha256 of the file it read as `expect`: one edited meanwhile is refused (`409`), nothing written. In this folder it re-reads the file just before writing — after the y/N, after `check` — and refuses the same way, writing nothing, when it changed since it was read |
@@ -60,6 +61,8 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun flow copy-step <flow> --step <n\|agent>[,<n>…]` | the canvas's Copy: the steps' markdown — line, marker and every option (core's `stepSource`) — on stdout. Reads only |
 | `foldrun flow paste <flow>` | the canvas's Paste: step markdown from stdin or `--file <path>` goes in as new groups after `--after <g>` (default last), or beside group `--group <g>`, renumbered to fit (core's `pasteSteps`) — `foldrun flow copy-step a --step 2 \| foldrun flow paste b`. Diff, checked, `--dry-run`; `--to` sends `PATCH { edit: { op: "paste" } }` |
 | `foldrun flow draft "<what it should do>"` | **Draft with AI**, on the platform (`--to <workspace>`; `--flow <name>` redrafts an existing flow): `POST …/flows/draft` has a model write the flow and any agent files it needs, checks and repairs once, and the CLI prints the notes, every file as a diff and what the check still finds. Nothing is saved until you say yes — `--yes` on a pipe, `--dry-run` never; on a pipe without `--yes` it saves nothing and exits 1, though the draft call was made and charged; each file goes through `PUT …/source` with `ifMatch`, so one that changed meanwhile is refused. One model call, charged like a step |
+| `foldrun assistant ["<message>"]` | the dashboard's **assistant**, from a terminal (also `foldrun ai`; `--to <workspace>`): `POST …/assistant` answers from the foldrun docs and the deployed workspace's files only, and writes agents, flows, tools and skills as proposals — the CLI prints the reply, the doc sections it read, every proposed file as a diff and what the check finds. Nothing is saved until you say yes — `--yes` on a pipe, `--dry-run` never; on a pipe without `--yes` it saves nothing and exits 1 (a plain question with no files exits 0); each file goes through `PUT …/source` with `ifMatch`, so one that changed meanwhile is refused. It prints the tokens the reply used and what it was charged. A proposed new workspace is created blank on yes (`--yes` on a pipe; never over one that exists); in a conversation the CLI then moves into it and carries on. Every reply is kept; `--conversation <id>` carries one on (its messages and unsaved files come back, and its workspace unless `--to` says another). With no message, in a terminal, it is a conversation: `/save`, `/files`, `/drop <path>`, `/new`, `/quit`. `--json` prints the platform's answer. Each reply is one model call, charged like a step. See [Assistant](assistant) |
+| `foldrun assistant history` | your kept assistant conversations, newest first (`GET /api/assistant/conversations`): id, workspace, when, how many messages and unsaved files, and the first question. `--q <text>` searches them, `--workspace <name>` narrows to one, `--json` prints the answer. `foldrun assistant show <id>` prints one whole; `foldrun assistant rm <id>` deletes it (asks; `--yes`) |
 | `foldrun tool test <name>` | exercise one tool, alone — no model, no run, no flow. The real thing runs: the HTTP request against the declared `base:`, the script with the workspace's secrets in its environment, the MCP handshake. Prints the transport, whether it exited cleanly, how long it took, everything the tool printed, and any secret it needed by NAME and never by value. Its arguments are `key=value` pairs, one per argument the tool declares, and `--path` is an http tool's probe path. It waits five minutes by default, because a tool that crawls takes as long as it takes — `--timeout <seconds>` waits longer, and a test given up on says so rather than claiming the tool failed |
 | `foldrun hook ls` | the hooks in this workspace (`hooks/<name>/`) and the account library (`library/hooks/<name>/`): each one's `on:`, `tool:` and description, read the way a run reads them — a folder that is not a valid hook is listed with the reason and the command exits 1. A workspace hook shadows a library one of the same name. `--json` for a script. `--to <workspace>` lists the DEPLOYED workspace's hooks instead (`GET /api/workspaces/<ws>/hooks`, the dashboard's Hooks panel): who turns each on, and the denies, rewrites and failures they wrote into recent runs — `--runs <n>` reads further back (default 50, up to 500), `--all` shows every decision |
 | `foldrun hook add <name> --on <event>` | a hook folder: `hook.md` (`on:` one of `tool.call`, `tool.result`, `step.start`, `step.end`; `tool:` from `--tool <pattern>` — `Bash`, `Write\|Edit`, `mcp__*` — on the tool events only) and a self-contained `run.mjs` that allows everything, with the whole contract in its comments: the event on stdin, one JSON answer on stdout, exit 2 to deny with stderr as the reason. `--library` writes it in the account library for every workspace; `--to <workspace>` picks one in an account. An agent turns it on with `hooks: [name]`; `hooks:` in a workspace's or the account's AGENTS.md turns it on for every agent under it |
@@ -82,7 +85,8 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun stop <run-id>` | kill a run in flight: the queued job is dropped and the sandbox the current step is spending in is destroyed. It prints which step is running and what has been spent, then asks you to type the run id back unless `--yes`. Finished steps keep their results, and costs already incurred stay on the bill. A run that has already finished is said so, not stopped. With no run id and a filter — `--status running,queued`, `--since 2h`, `--until 1h` (started before then: a span ago, or a date), `--flow <name>` — it stops every run that matches (`POST …/runs/bulk`), in `--to <workspace>` or across the account: it lists what matches first, asks, and then stops exactly the runs it listed, so one that starts in between is not swept up. `--dry-run` lists and touches nothing. The route refuses more than 100 at once |
 | `foldrun answer <run-id> "…"` | answer the question an agent is asking mid-step (`tools: [ask]`). `--option <n>` picks one of the choices it offered; `--question <id>` one of several. The agent is waiting in its sandbox and carries on at once. `foldrun approvals` lists what is being asked |
 | `foldrun message <run-id> "…"` | say something to a running agent. It reaches the model after its next tool call, as context — it changes none of the step's tools. `--step <n>` picks one when a parallel group has several running. Platform only |
-| `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health) |
+| `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health). `--site <domain>` (repeatable, or `a,b`) binds it as it is stored |
+| `foldrun secrets sites NAME [site…]` | bind a secret to the sites it is for: the egress proxy fills it in requests to those sites alone, and it never enters a sandbox ([bound to sites](secrets#bound-to-sites)). No sites prints what it is bound to; `--clear` unbinds. On the platform, or this machine's vault with `--local` |
 | `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable), `service-account` (`--file <key.json>`, `--scopes`), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted). On the platform, or this machine's vault with `--local` |
 | `foldrun secrets clients` | the OAuth clients saved on the platform — what a consent runs from without typing the client again; the client secret is never shown. `clients add <name> --provider google\|github\|microsoft\|linkedin` (or `--authorize-url` / `--token-url`) `--client-id … --scopes …` saves one (secret prompted), `clients rm <name>` removes it |
 | `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--provider google\|github\|microsoft\|linkedin`; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
@@ -192,12 +196,14 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `--step <n>` | `approve`, `reject`: decide one gate, numbered as `report` prints it. Without it, every step of that run which is waiting |
 | `--payload <json\|text\|@file>` | `approve`: release a step waiting on `wait: event` with this body (`POST …/approve` `{ payload }`). JSON is sent as JSON, anything else as text; `@file` reads a file |
 | `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace. `billing credit`: the ledger line's note |
-| `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
-| `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `backups requests`, `status --platform --history`, `team`: the raw document |
+| `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
+| `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `team`: the raw document |
 | `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
 | `--watch` | `invoke`: follow the run's trace here as it happens; the exit code is the run's |
 | `--print` | `open`: print the URL, do not open it |
 | `--value "<text>"` | `secrets set`: skip the prompt — careful with shell history |
+| `--site <domain>`, `--clear` | `secrets set`, `secrets sites`: a site the secret is bound to (repeatable); `--clear` unbinds |
+| `--add <site>`, `--remove <site>` | `agent network`: a site to add to, or take off, the agent's `network:` list (repeatable) |
 | `--account` | `secrets`: account scope rather than this workspace's — the workspace is the folder's name (`--workspace`), local or on the platform alike |
 | `--wait` | `invoke`, `agent run`: hold on and print the result. Asked in 25-second pieces, so a flow that runs for many minutes is never cut by whatever sits in front of the platform; a run parked on a person prints its page and exits 2 |
 | `--from <n>` | `invoke`, `flow run`, `rerun`: start at step n; earlier steps are recorded as skipped. A bulk `rerun` defaults to 1. (One flag, two meanings: a template on `init`, a step everywhere else) |
@@ -224,7 +230,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `--timeout <s>` | how many seconds one request to the platform may take — or `FOLDRUN_TIMEOUT`. Default 30, and 300 for `tool test`, where the tool itself is the thing being waited on |
 | `--local` | `deploy`, `secrets`, `logs`: the installation on this machine, even when signed in |
 | `--quiet` | leave out the dim "acting as …" line a platform command prints on stderr |
-| `--dry-run` | `extract`: list what would move, change nothing. `flow add`, `flow rm-step`, `flow dup-step`, `flow set`, `flow trigger`, `flow move-step`, `flow paste`, `flow draft`, `history restore`, `agent link`/`unlink`: show the diff, write nothing. `restore`: the diff only, restore nothing. A bulk `stop`/`rerun`: list what matches, touch nothing |
+| `--dry-run` | `extract`: list what would move, change nothing. `flow add`, `flow rm-step`, `flow dup-step`, `flow set`, `flow trigger`, `flow move-step`, `flow paste`, `flow draft`, `assistant`, `history restore`, `agent link`/`unlink`, `agent network`: show the diff, write nothing. `restore`: the diff only, restore nothing. A bulk `stop`/`rerun`: list what matches, touch nothing |
 | `--out <file>` | `api spec`: where to write the OpenAPI document (default stdout) |
 | `--file <path>` | `source put`: the file to send. `storage get`, `report get`, `account export`, `billing statement --csv`: where to write — `-` for stdout |
 

package/docs/flows.md

@@ -112,7 +112,7 @@ begins.
 | `ask:` | the same gate carrying a question; the typed answer reaches the prompt (a plain approval with no note reaches it as "approved with no note") |
 | `preview:` | what the gate shows: paths under `storage/` (a `workspace/storage/` prefix is accepted), comma-separated, globs allowed — `draft/*.mdx, draft/images/*.webp`; at most 12 files |
 | `wait:` | `3d` (`s`/`m`/`h`/`d`, capped at 30 days) or `event` — the run page shows the event URL and can release it with a payload, recorded as released by you (approve with `payload`) |
-| `on-fail:` | another agent takes the step over, with the failure as context. The rescuer owes what the step owed: its `verify:` and its `output:` |
+| `on-fail:` | another agent takes the step over, with the failure as context — and, for a gated step, the person's approval and answer, which it acts within. The rescuer owes what the step owed: its `verify:`, its `output:`, and a `loop:` step's `until:` marker (a loop that runs out of cycles goes to its rescuer too). A `verify:` that accepts `BLOCKED` never fails, so it never reaches the rescuer |
 | `delegate:` | the step's agent picks who runs next, from this set |
 
 ### What is retried without a `retry:`

package/docs/network.md

@@ -0,0 +1,158 @@
+# Network
+
+Every step runs in a sandbox of its own, and `network:` says which sites that
+sandbox may reach. An agent that reads the open web may reach any public
+site; every other agent reaches a list of trusted sites plus whatever it
+declares. Least access by default, widened on purpose — the same default
+Anthropic's own cloud sandboxes start from.
+
+```yaml
+---
+name: crm-sync
+tools: [crm_sync]
+network: [api.hubapi.com]        # the trusted list, plus this
+---
+```
+
+## The three levels
+
+| level | the sandbox may reach |
+|---|---|
+| `open` | any public site |
+| `trusted` | the trusted list, the sites you add, and what the step declares |
+| `none` | only the sites you add and what the step declares |
+
+**What the step declares** is always allowed, at every level: the hosts of
+its `apis:`, its remote MCP servers, its web providers (`web: {search: brave}`),
+and the sites its [secrets are bound to](secrets#bound-to-sites). You never list
+those twice.
+
+No level is ever a way into private space: the cluster, the LAN and the
+cloud metadata endpoint are refused whatever `network:` says.
+
+## The default
+
+Unset, the level follows what the agent does:
+
+- an agent with the `web` tool that may **fetch or browse** is `open` — a search
+  result can name any site, and a list would break it;
+- every other agent is `trusted`.
+
+An agent whose `web:` allows only `search` (`web: {actions: [search]}`) is
+`trusted`: it reads results, not pages.
+
+## The trusted list
+
+Package registries, source hosts and cloud SDKs — the domains Anthropic's
+Claude Code cloud environments allow at their default *Trusted* level, plus
+the Debian mirrors the runner image installs `runtime: system:` packages
+from. Among them:
+
+| | |
+|---|---|
+| Anthropic | api.anthropic.com, claude.ai, docs.claude.com, … |
+| Source | github.com, raw.githubusercontent.com, gitlab.com, bitbucket.org, … |
+| Packages | registry.npmjs.org, pypi.org, files.pythonhosted.org, crates.io, rubygems.org, proxy.golang.org, Maven, NuGet, … |
+| Containers | registry-1.docker.io, ghcr.io, gcr.io, public.ecr.aws, … |
+| Cloud | \*.googleapis.com, \*.amazonaws.com, \*.microsoftonline.com, … |
+| Linux | deb.debian.org, security.debian.org, archive.ubuntu.com, … |
+
+The whole list is `TRUSTED_SITES` in `@foldrun/core/network`; `foldrun agent
+network <agent>` says how many sites it holds. It includes wide wildcards
+such as `*.amazonaws.com` because SDKs need them — which means a bucket
+anyone can create is reachable too. An agent handling something sensitive
+can drop the list: `defaults: false`.
+
+## Writing it
+
+```yaml
+network: trusted                                  # a level
+network: [api.example.com, "*.example.org"]       # add sites; the level stays
+network:
+  level: none
+  allow: [api.example.com]
+  defaults: false                                 # trusted without the trusted list
+```
+
+A site is a domain or `*.domain` — no scheme, no path, no port; every port
+of the host is covered. `*.example.com` covers `api.example.com`,
+`a.b.example.com` and `example.com` itself. Quote a wildcard in YAML.
+
+It is read on the agent, in the workspace's `AGENTS.md` and in the account's
+`AGENTS.md`. The level and `defaults` are nearest-wins — the agent's, else the
+workspace's, else the account's. The `allow` lists add up across all three,
+so a site every agent needs is written once, in the account's `AGENTS.md`.
+
+`foldrun check` and every deploy refuse a value they cannot read — a level
+that is not one, a site with `https://` or a path — because it would leave
+the agent on the level above it, wider or narrower than you wrote.
+
+## Changing it
+
+On the agent's page in the dashboard, the **Network** card shows the level a
+run resolves, where it came from, and the sites on it; **Change** sets the
+level and the sites to add. From the terminal:
+
+```sh
+foldrun agent network crm-sync                        # what a run resolves
+foldrun agent network crm-sync --add api.hubapi.com   # add a site
+foldrun agent network crm-sync none --remove a.com    # a level, and take one off
+foldrun agent network crm-sync inherit                # back to the workspace's or the default
+```
+
+Both write the one `network:` line of `agent.md` and nothing else. Over the
+API it is `PATCH /api/workspaces/<ws>/agents/<agent>` with `{ "network": … }`
+(`null` inherits).
+
+## How it is held
+
+Every program in the sandbox reaches the internet through the **egress
+proxy**: the pod's `HTTPS_PROXY` and `HTTP_PROXY` name it, with the step's
+own lease as the password, and `NODE_USE_ENV_PROXY=1` turns that on for Node.
+curl, Python's `requests` and `httpx`, pip, npm, git, apt and the Agent SDK
+all read those variables. The proxy holds the step's list and checks every
+connection against it:
+
+- a site **off the list** is refused — `403`, saying which site and what to
+  add — and the refusal is a line in the run trace;
+- a site **on the list** is a tunnel: the bytes pass through and the proxy
+  never reads them;
+- a site a **secret is bound to** is intercepted, so the secret can be filled
+  in on the way out ([Secrets](secrets#bound-to-sites)).
+
+On a cluster the pod's network policy backs this up. A step whose level is
+`trusted` or `none` runs in a pod that may reach the proxy and DNS and
+nothing else, so a program that ignores the proxy variables finds no route
+instead of going round the list; it cannot reach the account's browser or
+search pods either, which are the world fetched on a run's behalf.
+
+The trace opens with the step's network:
+
+```
+network: trusted (default) — the trusted list (207 sites); added: api.hubapi.com
+egress: CONNECT pypi.org:443 × 3 (840ms total)
+network: example.com is not a site this step may reach (network: trusted). Add it to the agent's network: list — network: [example.com] — or set network: open. Refused.
+```
+
+### Report-only, while an install learns
+
+An install enforces the list when its worker has `FOLDRUN_NETWORK_ENFORCE=1`.
+Until then the proxy only **reports**: a site off the list is allowed, and
+the trace names it once per step —
+
+```
+network: api.example.com would be refused (network: trusted) — allowed, because this install only reports. Add it to the agent's network: list to keep it reachable.
+```
+
+— so the sites your agents really use can be added before anything is
+refused. The trace line `network: … — report only on this install` says
+which mode a step ran in.
+
+### Where it is not held
+
+`foldrun run` on your own machine has no sandbox, and a compose install with
+no egress proxy (no `FOLDRUN_EGRESS_URL`) has no forward door: there,
+`network:` is checked and resolved but not enforced, and the trace says
+`not enforced here`. On the single-container tier the proxy variables are
+set and the proxy holds the list, but the container's network is not walled
+in, so a program that ignores the variables still goes direct.

package/docs/secrets.md

@@ -12,6 +12,7 @@ git — which is what makes a workspace safe to commit.
 ```sh
 foldrun secrets set STRIPE_KEY               # this workspace's; prompted, never echoed
 foldrun secrets set STRIPE_KEY --account     # the account's, shared by every workspace
+foldrun secrets set STRIPE_KEY --site api.stripe.com   # bound: never in a sandbox (below)
 foldrun secrets ls
 ```
 
@@ -112,6 +113,59 @@ land on any worker behind the Service and still find its lease. Without
 a proxy configured (the CLI, a compose install without
 `FOLDRUN_EGRESS_URL`) a step materialises everything, as it always did.
 
+## Bound to sites
+
+A secret can be **bound** to the sites it is for. A bound secret never
+enters a sandbox, whatever the step grants — Bash, a script tool, a browser.
+The sandbox holds `${NAME}`; the [egress proxy](network#how-it-is-held), which
+every program's HTTPS goes through, fills it in requests to those sites and
+no other. This is how Anthropic's cloud sandboxes attach a network secret,
+and it closes the gap above: a step with Bash used to get every declared
+secret's real value.
+
+```sh
+foldrun secrets sites DATAFORSEO_PASSWORD api.dataforseo.com
+foldrun secrets sites DATAFORSEO_PASSWORD             # what it is bound to
+foldrun secrets sites DATAFORSEO_PASSWORD --clear     # unbind it
+```
+
+Or **Bind to sites** under the secret in Settings → Secrets, or over the API:
+
+```sh
+PATCH /api/secrets   { "name": "DATAFORSEO_PASSWORD", "sites": ["api.dataforseo.com"] }
+PUT   /api/secrets   { "name": "…", "value": "…", "sites": ["api.dataforseo.com"] }   # set and bind at once
+```
+
+What a program in the sandbox writes is unchanged; it sends the placeholder
+where the value would go:
+
+```sh
+curl -H "Authorization: Bearer $HUBSPOT_TOKEN" https://api.hubapi.com/crm/v3/objects/contacts
+curl -u "$DATAFORSEO_LOGIN:$DATAFORSEO_PASSWORD" https://api.dataforseo.com/v3/serp/...
+```
+
+The proxy fills `${NAME}` in the request's URL and headers, and inside a
+`Basic` Authorization header (which `curl -u` sends base64'd). To do that
+for a bound site it ends the TLS connection itself, with a certificate from
+the install's **egress CA**, which the sandbox trusts: the pod's start puts
+that CA in a bundle and points `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`,
+`CURL_CA_BUNDLE`, `PIP_CERT`, `GIT_SSL_CAINFO` and `NODE_EXTRA_CA_CERTS` at
+it. Only bound sites are intercepted; every other site is a tunnel the
+proxy cannot read. The CA is derived from the install's key, so every
+worker presents the same one, and rotating the key rotates it.
+
+A bound site is always reachable, at every [network](network) level.
+
+Leave a secret unbound when the program needs the value itself rather than
+in a request: one that signs requests with it (an HMAC, AWS SigV4), puts it
+in a request body, or uses it for something other than HTTP. A file, an ssh
+key or an `api` header set cannot be bound — they are unpacked inside the
+sandbox. The run trace says which way each secret went:
+
+```
+secrets: GA_KEY materialised in the sandbox for bash; DATAFORSEO_PASSWORD bound to sites — filled by the egress proxy, never in the sandbox; api tools and the model key go through the egress proxy
+```
+
 ## Connected accounts
 
 Some third parties are connected rather than pasted — Google, GitHub,

package/docs/security.md

@@ -19,9 +19,14 @@ machine.
 
 ## What the network allows
 
-A run pod may reach the public internet, DNS, the egress proxy where its
-credentials are filled in, and its own account's search and browser pods —
-and nothing else. The policy denies every private range (RFC1918) and the
+A run pod may reach DNS, the egress proxy where its credentials are filled
+in, and — for an agent whose [network](network) is `open` — the public
+internet and its own account's search and browser pods; nothing else. An
+agent that is `trusted` or `none` (the default for one that does not read
+the web) reaches the internet only through the egress proxy, which holds
+its list of sites per connection; on an install that enforces it
+(`FOLDRUN_NETWORK_ENFORCE=1`) its pod has no other route, and no way to the
+account's browser or search pods. The policy denies every private range (RFC1918) and the
 cloud metadata endpoint — the address that, on a cloud host, hands out the
 machine's own credentials. It cannot reach the platform's API, its
 database, its object store, or another account's pods. Workspace files
@@ -65,10 +70,12 @@ On a cluster the value does not enter the sandbox either. The worker keeps
 it and the step sends its API and model requests through a per-step
 **egress proxy** with `${NAME}` placeholders; the proxy fills each one for
 the host it was granted to and forwards. A compromised script in the pod
-reads its environment and finds the name, not the key. The one exception
-is a script tool that needs the value in process (a browser seeding
-cookies), which materialises the step's secrets into the sandbox and says
-so in the trace — see [Secrets](secrets).
+reads its environment and finds the name, not the key. The exception is a
+step whose script tools or Bash need the value in process (a browser seeding
+cookies), which materialises its secrets into the sandbox and says so in the
+trace — unless the secret is [bound to sites](secrets#bound-to-sites): a bound
+secret never enters a sandbox, because the proxy fills it for those sites
+whatever program sent the request.
 
 At rest, each account has its own encryption key; the account keys are
 wrapped by one root key the platform holds. A stolen copy of an account's

package/docs/tools.md

@@ -123,6 +123,12 @@ a `name @ url` is refused, with a line in the log.
 never seen the program, and say when to use the tool in `description` — that
 sentence is what decides whether it gets called at all.
 
+The program gets each argument the agent fills in as a long flag,
+`--<name> <value>`: the tool above runs as
+`run.py --query "SELECT …" --files sales.csv`. An argument left out or empty
+is not passed, so give optional ones a default in the program. What it
+prints, stdout and stderr together, is what the agent reads back.
+
 ## MCP — someone else's tools
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^1.0.0"
+    "@foldrun/core": "^1.1.0"
   },
   "files": [
     "bin",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
-    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts",
+    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts",
     "release": "node scripts/release.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "docs:sync": "node scripts/sync-docs.mjs",
@@ -49,6 +49,6 @@
   "devDependencies": {
     "@types/node": "^26.6.4",
     "gray-matter": "^4.0.3",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   }
 }

package/src/commands.mjs

@@ -889,6 +889,10 @@ async function checkProblems(workspace, flags = {}) {
     const { readAgentsMd } = await core();
     const { readLimits } = await import("@foldrun/core/limits");
     for (const w of readLimits(readAgentsMd(workspace)?.data?.limits).problems) note("error", "AGENTS.md", w);
+    // `network:` here is every agent's default: a value nobody can read
+    // leaves them on the account's, or the platform's.
+    const net = await import("@foldrun/core/network").catch(() => null);
+    for (const w of net ? net.networkProblems(readAgentsMd(workspace)?.data?.network) : []) note("error", "AGENTS.md", w);
   }
 
   const { unopenedFrontmatter } = /** @type {any} */ (await core());
@@ -912,6 +916,9 @@ async function checkProblems(workspace, flags = {}) {
     // written into the file. The run would say so in its trail and carry
     // on; the deploy refuses it; this is where a person hears it first.
     for (const w of a.webProblems ?? []) note("error", `agents/${a.name}`, w);
+    // A network: value that cannot be read leaves the agent on the level
+    // above it — the deploy refuses it, so check says so first.
+    for (const w of a.networkProblems ?? []) note("error", `agents/${a.name}`, w);
     // What works but should change: the old `session:` key, and a pinned
     // user_agent whose Chrome is not the runner image's (the platform's
     // /api/version says which Chrome; FOLDRUN_RUNNER_ENGINES on a server).
@@ -2798,6 +2805,19 @@ async function readStorage(page, origin) {
     .catch(() => empty);
 }
 
+/** Bind on this machine's vault — a core from before site binding says so. */
+async function localSetSites(name, sites, scope) {
+  const k = await core();
+  if (typeof k.setSecretSites !== "function") throw new Error("binding a secret to sites needs @foldrun/core 1.1 or later — update foldrun");
+  return k.setSecretSites("default", name, sites, scope);
+}
+
+/** `--site a.com --site "*.b.org"` or `--site a.com,b.org`, as one list. */
+function siteFlags(flags) {
+  const raw = flags.site === undefined ? [] : Array.isArray(flags.site) ? flags.site : [flags.site];
+  return raw.filter((v) => typeof v === "string").flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean);
+}
+
 async function secretsCmd(positional, flags, layout) {
   // --local: this machine's store even when signed in, the same escape
   // hatch deploy and keys have. Without it, a signed-in laptop sent every
@@ -2828,7 +2848,7 @@ async function secretsCmd(positional, flags, layout) {
     console.log();
     for (const s of entries) {
       console.log(
-        `  ${c.bold(s.name)}  ${c.dim(`${s.scope}${s.shadowed ? " · shadowed" : ""} · ${s.updatedAt ?? ""}`)}`,
+        `  ${c.bold(s.name)}  ${c.dim(`${s.scope}${s.shadowed ? " · shadowed" : ""} · ${s.updatedAt ?? ""}${s.sites?.length ? ` · sent only to ${s.sites.join(", ")}` : ""}`)}`,
       );
     }
     console.log();
@@ -2863,6 +2883,31 @@ async function secretsCmd(positional, flags, layout) {
 
   if (!name) throw new Error(`which secret? try \`foldrun secrets ${verb} NAME\``);
 
+  // A secret bound to sites never enters a sandbox: steps hold `${NAME}` and
+  // the egress proxy fills it in requests to those sites alone.
+  if (verb === "sites") {
+    const given = [...positional.slice(2), ...siteFlags(flags)];
+    if (!given.length && flags.clear !== true) {
+      const entries = url
+        ? (await remoteCall(url, flags, `/api/secrets${scope ? `?workspace=${encodeURIComponent(scope)}` : ""}`)).secrets
+        : (await core()).listSecrets("default", scope);
+      const hit = entries.find((s) => s.name === name);
+      if (!hit) throw new Error(`no secret ${name}${scope ? ` in workspace ${scope}` : " in the account"}`);
+      console.log(hit.sites?.length
+        ? `\n  ${c.bold(name)} is sent only to ${hit.sites.join(", ")} — on the platform it never enters a sandbox\n`
+        : `\n  ${c.bold(name)} is not bound to sites — a step with a script or Bash gets its real value. Bind it: foldrun secrets sites ${name} api.example.com\n`);
+      return 0;
+    }
+    const sites = flags.clear === true ? [] : given;
+    const stored = url
+      ? (await remoteCall(url, flags, "/api/secrets", { method: "PATCH", body: JSON.stringify({ name, sites, workspace: scope }) })).sites
+      : await localSetSites(name, sites, scope);
+    console.log(stored.length
+      ? `\n  ${c.green("✓")} ${name} is sent only to ${stored.join(", ")} — on the platform the egress proxy fills it, and it never enters a sandbox\n`
+      : `\n  ${c.green("✓")} ${name} unbound — a step with a script or Bash gets its real value again\n`);
+    return 0;
+  }
+
   if (verb === "set") {
     // --kind: the other shapes the Connections form stores — a file, an SSH
     // login, API headers, a service account's key, a client-credentials app.
@@ -2898,15 +2943,18 @@ async function secretsCmd(positional, flags, layout) {
     const value =
       typeof flags.value === "string" ? flags.value : await promptHidden(`  value for ${name}: `);
     if (!value) throw new Error("empty value — nothing stored");
+    const sites = siteFlags(flags);
     if (url) {
       await remoteCall(url, flags, "/api/secrets", {
         method: "PUT",
-        body: JSON.stringify({ name, value, workspace: scope }),
+        body: JSON.stringify({ name, value, workspace: scope, ...(sites.length ? { sites } : {}) }),
       });
     } else {
-      (await core()).setSecret("default", name, value, scope);
+      const k = await core();
+      k.setSecret("default", name, value, scope);
+      if (sites.length) await localSetSites(name, sites, scope);
     }
-    console.log(`\n  ${c.green("✓")} ${name} stored — declare it in agent.md under \`secrets:\` to use it\n`);
+    console.log(`\n  ${c.green("✓")} ${name} stored${sites.length ? ` and sent only to ${sites.join(", ")}` : ""} — declare it in agent.md under \`secrets:\` to use it\n`);
     return 0;
   }
 
@@ -7243,6 +7291,84 @@ async function agentLinkCmd(positional, flags, layout) {
   return 0;
 }
 
+/**
+ * `foldrun agent network <agent> [open|trusted|none|inherit] [--add <site>]…
+ * [--remove <site>]…` — which sites the agent's sandbox may reach, its
+ * `network:` line, edited the way the dashboard's Network card edits it
+ * (core network.ts setNetworkSetting: that one line, nothing else). With no
+ * level and no site it prints what a run resolves.
+ */
+async function agentNetworkCmd(positional, flags, layout) {
+  const name = positional[1];
+  const word = positional[2];
+  const usage = "`foldrun agent network <agent> [open|trusted|none|inherit] [--add <site>]… [--remove <site>]…`";
+  if (!name) throw new Error(usage);
+  if (word !== undefined && !["open", "trusted", "none", "inherit"].includes(word)) throw new Error(`${usage} — "${word}" is not a level`);
+  const net = await import("@foldrun/core/network").catch(() => null);
+  if (!net) throw new Error("agent network needs @foldrun/core 1.1 or later — update foldrun");
+  const desk = await openDesk(flags, layout, `agent network ${name}`);
+  const rel = `agents/${name}/agent.md`;
+  if (!desk.files.has(rel)) {
+    const agents = [...desk.files.keys()].map((r) => /^agents\/([^/]+)\/agent\.md$/.exec(r)?.[1]).filter(Boolean);
+    throw new Error(`no agent "${name}" in ${desk.label} — it has ${agents.join(", ") || "none"}`);
+  }
+  const resolve = (files) =>
+    inTree(desk, files, async (dir) => {
+      const { listAgents, readFrontmatter } = await core();
+      return {
+        info: listAgents("default", "workspace").find((a) => a.name === name),
+        own: net.readNetwork(readFrontmatter(path.join(dir, rel)).network).setting,
+      };
+    });
+  const show = (info) => {
+    const p = info?.network;
+    if (!p) return;
+    console.log(`  ${net.networkLine(p, true)}`);
+    if (p.level !== "open") console.log(`  ${c.dim("a run also allows its MCP servers, its web providers and the sites its secrets are bound to")}`);
+  };
+  const raw = desk.files.get(rel);
+  const now = await resolve(desk.files);
+  const list = (v) => (v === undefined ? [] : Array.isArray(v) ? v : [v]).filter((x) => typeof x === "string").flatMap((x) => x.split(",")).map((x) => x.trim().toLowerCase()).filter(Boolean);
+  const adds = list(flags.add);
+  const removes = list(flags.remove);
+  if (word === undefined && !adds.length && !removes.length) {
+    console.log(`\n  ${c.bold(name)} ${c.dim(`· ${desk.label}`)}`);
+    show(now.info);
+    console.log();
+    return 0;
+  }
+  const own = now.own ?? { allow: [] };
+  const level = word === "inherit" ? undefined : word ?? own.level;
+  const allow = [...new Set([...own.allow, ...adds])].filter((x) => !removes.includes(x));
+  const setting = level || allow.length || own.defaults === false
+    ? { ...(level ? { level } : {}), allow, ...(own.defaults === false ? { defaults: false } : {}) }
+    : null;
+  const problems = setting ? net.readNetwork(setting).problems : [];
+  if (problems.length) throw new Error(problems.join(" "));
+  const next = net.setNetworkSetting(raw, setting);
+  if (next === raw) {
+    console.log(`\n  ${c.dim(`${name}'s network: already says that — nothing to change`)}\n`);
+    return 0;
+  }
+  console.log(`\n  ${c.bold(name)} ${c.dim(`· network · ${desk.label}`)}\n`);
+  await printDiff(rel, raw, next);
+  if (flags["dry-run"] === true) {
+    console.log(`\n  ${c.dim("--dry-run: nothing written")}\n`);
+    return 0;
+  }
+  if (desk.platform) {
+    await remoteCall(desk.url, flags, `/api/workspaces/${enc(desk.ws)}/agents/${enc(name)}`, { method: "PATCH", body: JSON.stringify({ network: setting }) });
+  } else {
+    assertUnchanged(desk, rel, raw);
+    writeIfUnchanged(desk, rel, raw, next);
+  }
+  const after = await resolve(new Map([...desk.files, [rel, next]]));
+  console.log();
+  show(after.info);
+  console.log(`\n  ${c.green("✓")} ${rel} ${c.dim(desk.platform ? `in ${desk.ws} — a revision on the platform` : "— `foldrun deploy` ships it")}\n`);
+  return 0;
+}
+
 /**
  * `foldrun flow show <flow>` — the canvas, in a terminal: the trigger, one
  * block per group, each step's chips, the team under its agent, and what
@@ -8855,6 +8981,295 @@ async function flowDraftCmd(positional, flags, layout) {
   return 0;
 }
 
+/** `foldrun assistant history` — your kept conversations, newest first
+ *  (`--q` searches them, `--workspace` narrows to one, `--json`). */
+async function assistantHistoryCmd(url, flags) {
+  const q = new URLSearchParams();
+  if (typeof flags.q === "string" && flags.q.trim()) q.set("q", flags.q.trim());
+  if (typeof flags.workspace === "string") q.set("workspace", flags.workspace);
+  if (typeof flags.limit === "string") q.set("limit", flags.limit);
+  const d = await remoteCall(url, flags, `/api/assistant/conversations${q.size ? `?${q}` : ""}`);
+  const list = d.conversations ?? [];
+  if (flags.json) {
+    console.log(JSON.stringify(d, null, 2));
+    return 0;
+  }
+  if (!list.length) {
+    console.log(`\n  ${c.dim(flags.q ? "nothing matches" : "no conversations yet")}\n`);
+    return 0;
+  }
+  console.log();
+  for (const x of list) {
+    console.log(`  ${c.bold(x.id)}  ${x.workspace}  ${c.dim(`${ago(x.updatedAt)} ago · ${x.messages} message${x.messages === 1 ? "" : "s"}${x.unsaved ? ` · ${x.unsaved} unsaved` : ""}`)}`);
+    console.log(`    ${x.title}`);
+  }
+  console.log(`\n  ${c.dim("foldrun assistant show <id> · foldrun assistant --conversation <id> \"…\" · foldrun assistant rm <id>")}\n`);
+  return 0;
+}
+
+/** `foldrun assistant show <id>` — one kept conversation, whole. */
+async function assistantShowCmd(url, flags, id) {
+  const d = await remoteCall(url, flags, `/api/assistant/conversations/${enc(id)}`);
+  if (flags.json) {
+    console.log(JSON.stringify(d, null, 2));
+    return 0;
+  }
+  console.log(`\n  ${c.bold(d.title)}  ${c.dim(`${d.workspace} · ${ago(d.updatedAt)} ago`)}\n`);
+  for (const m of d.messages ?? []) {
+    console.log(`  ${m.role === "user" ? c.bold("you ›") : c.dim("assistant ›")}`);
+    console.log(`${String(m.content).split("\n").map((l) => `    ${l}`).join("\n")}\n`);
+  }
+  if ((d.files ?? []).length) console.log(`  ${c.dim(`${d.files.length} proposed file${d.files.length === 1 ? "" : "s"} not saved: ${d.files.map((f) => f.path).join(", ")}`)}\n`);
+  return 0;
+}
+
+/** `foldrun assistant rm <id>` — delete one kept conversation (asks; --yes). */
+async function assistantRmCmd(url, flags, id) {
+  if (!(await sureToDelete(flags, "assistant rm", `Delete the conversation ${id}`))) return 0;
+  await remoteCall(url, flags, `/api/assistant/conversations/${enc(id)}`, { method: "DELETE" });
+  console.log(`  ${c.green("✓")} deleted ${id}\n`);
+  return 0;
+}
+
+/**
+ * `foldrun assistant ["<message>"] --to <ws>` (also `foldrun ai`) — the
+ * dashboard's assistant from a terminal: it answers from foldrun's docs and
+ * the deployed workspace's files only, and writes agents, flows, tools and
+ * skills as proposals (POST …/assistant). With a message it answers once;
+ * with none, in a terminal, it is a conversation (/save, /files, /drop
+ * <path>, /new, /quit). Proposals are shown as diffs with what the check
+ * finds and saved only on yes (--yes; --dry-run never), each through
+ * `PUT …/source` with ifMatch, so a file that changed meanwhile is refused.
+ * --json prints the platform's answer as it is.
+ */
+async function assistantCmd(positional, flags, layout) {
+  const url = platformFor(flags, "assistant");
+  // The kept conversations: `history`, `show <id>`, `rm <id>`.
+  const sub = positional[0];
+  if (sub === "history" && positional.length === 1) return assistantHistoryCmd(url, flags);
+  if ((sub === "show" || sub === "rm") && positional.length === 2 && /^c_[a-z0-9]{8,40}$/.test(positional[1])) {
+    return sub === "show" ? assistantShowCmd(url, flags, positional[1]) : assistantRmCmd(url, flags, positional[1]);
+  }
+  // A kept conversation knows its workspace; --to may still say another.
+  let ws = typeof flags.conversation === "string" && typeof flags.to !== "string" ? "" : platformWorkspace(flags, layout, "assistant");
+  const first = positional.join(" ").trim();
+  /** A new workspace the last reply proposed.
+   *  @type {{ name: string, purpose: string } | null} */
+  let proposedWs = null;
+  if (!first && !process.stdin.isTTY) {
+    throw new Error('`foldrun assistant "<question or what to build>" --to <workspace>` — with no message it needs a terminal to talk in');
+  }
+  /** @type {{ role: "user" | "assistant", content: string }[]} */
+  let messages = [];
+  /** @type {{ path: string, content: string, before: string | null, sha256: string | null }[]} */
+  let files = [];
+  /** @type {{ where: string, message: string, level: string }[]} */
+  let issues = [];
+  /** The kept conversation this one continues; null until the first reply. */
+  let conversation = typeof flags.conversation === "string" ? flags.conversation : null;
+  if (conversation) {
+    // Carry a kept one on: its messages and its unsaved files come back.
+    const kept = await remoteCall(url, flags, `/api/assistant/conversations/${enc(conversation)}`);
+    messages = (kept.messages ?? []).map((m) => ({ role: m.role, content: m.content }));
+    files = kept.files ?? [];
+    if (!ws) ws = kept.workspace;
+    if (!flags.json) console.log(`\n  ${c.dim(`carrying on "${kept.title}" in ${kept.workspace} — ${messages.length} message${messages.length === 1 ? "" : "s"}`)}`);
+  }
+
+  const showFiles = async () => {
+    for (const f of files) {
+      console.log(`  ${c.dim(f.before === null ? "new" : "replaces")}`);
+      await printDiff(f.path, f.before ?? "", f.content);
+      console.log();
+    }
+    for (const i of issues) console.log(`  ${i.level === "error" ? c.red("error") : c.amber(" warn")}  ${c.bold(i.where)}  ${i.message}`);
+    if (issues.length) console.log();
+  };
+
+  const ask = async (text) => {
+    messages.push({ role: "user", content: text });
+    if (!flags.json) console.log(`\n  ${c.dim("reading the docs and the workspace — one reply, charged like a step…")}`);
+    let d;
+    try {
+      d = await remoteCall(
+        url,
+        flags,
+        `/api/workspaces/${enc(ws)}/assistant`,
+        { method: "POST", body: JSON.stringify({ messages, files: files.map(({ path: p, content }) => ({ path: p, content })), ...(conversation ? { conversation } : {}) }) },
+        { seconds: Math.max(timeoutSeconds(flags), 300) },
+      );
+    } catch (err) {
+      messages.pop();
+      throw err;
+    }
+    messages.push({ role: "assistant", content: d.reply ?? "" });
+    files = d.files ?? [];
+    issues = d.issues ?? [];
+    proposedWs = d.workspace ?? null;
+    if (typeof d.conversation === "string" && d.conversation) conversation = d.conversation;
+    if (flags.json) {
+      console.log(JSON.stringify(d, null, 2));
+      return;
+    }
+    console.log(`\n${(d.reply ?? "").split("\n").map((l) => `  ${l}`).join("\n")}\n`);
+    if ((d.sources ?? []).length) console.log(`  ${c.dim(`read: ${d.sources.map((s) => `${s.doc} › ${s.section}`).join(" · ")}`)}\n`);
+    if (conversation) console.log(`  ${c.dim(`kept as ${conversation} — carry on with --conversation ${conversation}`)}\n`);
+    if (d.usage) {
+      const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
+      const paid = d.supply === "provider" ? "on your own model key" : typeof d.chargedUsd === "number" ? `$${d.chargedUsd.toFixed(d.chargedUsd > 0 && d.chargedUsd < 0.01 ? 4 : 2)} charged` : "";
+      console.log(`  ${c.dim(`${k(d.usage.inputTokens)} tokens in · ${k(d.usage.outputTokens)} out${paid ? ` · ${paid}` : ""}`)}\n`);
+    }
+    if (proposedWs) console.log(`  ${c.bold("new workspace")} ${proposedWs.name} ${c.dim(`— ${proposedWs.purpose}`)}\n`);
+    await showFiles();
+  };
+
+  /** What the last reply proposed — read through a call, because ask()
+   *  sets it and a type checker narrowing the variable cannot see that. */
+  const proposal = () => proposedWs;
+
+  /** Create the proposed workspace, blank, as the dashboard does — after a
+   *  yes, and never over one that exists (the same POST deploys over it).
+   *  @param {{ name: string, purpose: string }} p */
+  const createProposed = async (p) => {
+    const name = p.name;
+    if (!(await confirmed(flags, "assistant", `Create the workspace ${name}? [y/N] `))) {
+      console.log(`\n  ${c.dim("not created")}\n`);
+      return false;
+    }
+    // ifAbsent: the server refuses a name that exists (409) rather than
+    // deploying over it — atomically, where a list-then-create could race.
+    try {
+      await remoteCall(url, flags, "/api/workspaces", { method: "POST", body: JSON.stringify({ name, template: true, ifAbsent: true }) });
+    } catch (err) {
+      if (err instanceof HttpError && err.status === 409) {
+        console.log(`  ${c.red("✗")} a workspace called ${name} exists — nothing created\n`);
+        return false;
+      }
+      throw err;
+    }
+    console.log(`  ${c.green("✓")} created ${name}\n`);
+    proposedWs = null;
+    return name;
+  };
+
+  const save = async (note) => {
+    if (!files.length) {
+      console.log(`  ${c.dim("nothing proposed to save")}\n`);
+      return true;
+    }
+    if (!(await confirmed(flags, "assistant", `Save ${files.length} file${files.length === 1 ? "" : "s"} to ${ws}${files.some((f) => f.before !== null) ? " (replacing what is there)" : ""}? [y/N] `))) {
+      console.log(`\n  ${c.dim("nothing saved")}\n`);
+      return true;
+    }
+    const message = `written with the assistant: ${note.replace(/\s+/g, " ").slice(0, 80)}`;
+    for (const f of [...files]) {
+      try {
+        await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/source`, { method: "PUT", body: JSON.stringify({ path: f.path, content: f.content, message, ifMatch: f.sha256 ?? null }) });
+        console.log(`  ${c.green("✓")} ${f.path}`);
+        files = files.filter((x) => x.path !== f.path);
+        issues = issues.filter((i) => !(i.where === f.path || i.where.startsWith(`${f.path}:`)));
+      } catch (err) {
+        console.log(`  ${c.red("✗")} ${f.path} — ${err instanceof Error ? err.message : err}`);
+        return false;
+      }
+    }
+    console.log(`\n  ${c.dim(`each is a revision — \`foldrun history --to ${ws}\` · \`foldrun check --to ${ws}\``)}\n`);
+    return true;
+  };
+
+  if (first) {
+    await ask(first);
+    const p = proposal();
+    if (p && !flags.json) {
+      if (flags["dry-run"] === true) {
+        console.log(`  ${c.dim("--dry-run: no workspace created")}\n`);
+        return 0;
+      }
+      if (flags.yes !== true && !process.stdin.isTTY) {
+        console.log(`  ${c.dim(`not a terminal to ask — no workspace created; run it again with --yes, or create it with \`foldrun new ${p.name}\` and deploy`)}\n`);
+        return 1;
+      }
+      const made = await createProposed(p);
+      if (made) console.log(`  ${c.dim(`carry on there: foldrun assistant --to ${made} "<what it should do>"`)}\n`);
+      return made ? 0 : 1;
+    }
+    if (!files.length || flags.json) return 0;
+    if (flags["dry-run"] === true) {
+      console.log(`  ${c.dim("--dry-run: nothing saved")}\n`);
+      return 0;
+    }
+    if (flags.yes !== true && !process.stdin.isTTY) {
+      console.log(`  ${c.dim(`the reply was made (charged like a step), but this is not a terminal to ask — nothing saved — run it again with --yes to save ${files.length === 1 ? "this file" : `these ${files.length} files`}, or save them with \`foldrun source put\``)}\n`);
+      return 1;
+    }
+    return (await save(first)) ? 0 : 1;
+  }
+
+  const { createInterface } = await import("node:readline/promises");
+  console.log(`\n  ${c.bold("foldrun assistant")} ${c.dim(`· ${ws} · answers from the foldrun docs; nothing is saved until you /save`)}`);
+  console.log(`  ${c.dim("/save  /files  /drop <path>  /new  /quit")}\n`);
+  for (;;) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let line;
+    try {
+      line = (await rl.question(`${c.bold("you ›")} `)).trim();
+    } catch {
+      line = "/quit"; // the input closed (Ctrl-D)
+    } finally {
+      rl.close();
+    }
+    if (!line) continue;
+    if (line === "/quit" || line === "/exit") {
+      if (files.length) console.log(`\n  ${c.dim(`${files.length} proposed file${files.length === 1 ? "" : "s"} not saved`)}`);
+      console.log();
+      return 0;
+    }
+    if (line === "/new") {
+      messages = [];
+      files = [];
+      issues = [];
+      conversation = null;
+      console.log(`  ${c.dim("a new conversation")}\n`);
+      continue;
+    }
+    if (line === "/files") {
+      if (files.length) await showFiles();
+      else console.log(`  ${c.dim("nothing proposed")}\n`);
+      continue;
+    }
+    if (line.startsWith("/drop")) {
+      const target = line.slice(5).trim();
+      const before = files.length;
+      files = files.filter((f) => f.path !== target);
+      issues = issues.filter((i) => !(i.where === target || i.where.startsWith(`${target}:`)));
+      console.log(`  ${c.dim(files.length < before ? `dropped ${target}` : `${target || "(no path)"} is not proposed`)}\n`);
+      continue;
+    }
+    if (line === "/save") {
+      await save(messages.find((m) => m.role === "user")?.content ?? "");
+      continue;
+    }
+    try {
+      await ask(line);
+      const p = proposal();
+      if (p) {
+        const made = await createProposed(p);
+        if (made) {
+          // The conversation moves into the new workspace and carries on.
+          ws = made;
+          files = [];
+          issues = [];
+          messages.push({ role: "assistant", content: `Created the workspace \`${made}\`.` });
+          console.log(`  ${c.dim(`now working in ${made}`)}`);
+          await ask(`The workspace "${made}" now exists and you are working in it. Carry on with what I asked for: write its agents, flows, tools and skills.`);
+        }
+      }
+    } catch (err) {
+      console.log(`\n  ${c.red("✗")} ${err instanceof Error ? err.message : err}\n`);
+    }
+  }
+}
+
 /**
  * `foldrun history restore <path> --id <revision> --to <ws>` — the History
  * drawer's "Restore this version": the file is rewritten with that
@@ -9769,11 +10184,15 @@ export async function run(command, positional, flags, workspace, layout) {
       // `new` scaffolds one here; `run` runs one there. The noun is the same
       // thing in both cases, which is why they share a command.
       if (positional[0] === "link" || positional[0] === "unlink") return agentLinkCmd(positional, flags, layout);
+      if (positional[0] === "network") return agentNetworkCmd(positional, flags, layout);
       if (positional[0] === "import") return agentImportCmd(positional, flags, layout);
       if (positional[0] === "ls" || positional[0] === "list") return remoteListCmd("agents", flags, layout);
       return positional[0] === "run"
         ? agentRunCmd(positional, flags, layout)
         : scaffoldCmd("agents", positional, flags, layout);
+    case "assistant":
+    case "ai":
+      return assistantCmd(positional, flags, layout);
     case "flow":
       // `new` scaffolds a file; `add`, `rm-step` and `show` are the canvas; `run` is
       // `invoke`, spelled the way `agent run` is; `rotate-hook` a new URL.

package/src/guide.mjs

@@ -30,7 +30,7 @@ export function agentRulesBlock() {
 
 # Read foldrun's docs before you edit this folder
 
-This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling.
+This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value.
 
 This block is for coding tools. It is written and re-added by the foldrun CLI, and the runtime strips it, so the agents that run here never see it; the rest of this file is the account's own context, which they do read. Committing the block with your work keeps the tree clean.