@tianshu-ai/tianshu 0.3.0

package/packages/server/builtinConfig/plugins/microsandbox/templates/task-runner.yaml

@@ -0,0 +1,80 @@
+# Task runner Sandboxfile.
+#
+# Recommended snapshot for the per-task sandbox pool (PR #141): a
+# Node 22 + Python 3.12 environment with the tools agent tasks
+# typically reach for, but WITHOUT the GUI / browser stack from
+# `browser.yaml`. Faster to boot, smaller RAM footprint, plenty
+# fast for code generation / data analysis / shell scripting
+# tasks that don't need a chromium of their own.
+#
+# Use this as the default Task snapshot in the admin UI; pick
+# `browser.yaml` instead when the workload needs to pilot a
+# chromium (visual scraping, JS-heavy SPAs, screenshots, etc).
+# Anything beyond those two cases — a custom base image, an
+# air-gapped install, etc — means writing your own Sandboxfile
+# and uploading it through the admin UI.
+#
+# Includes vs `browser.yaml`:
+#   shared: sudo, curl, ca-certs, fontconfig + CJK + emoji fonts,
+#           libreoffice (so docx/xlsx/pptx round-trips work),
+#           Node 22 (base image), Python 3.12 + pip + venv
+#   added : git, jq, build-essential, less, vim-tiny, zip/unzip
+#   added : pip pre-installs so common one-shot tasks don't pay
+#           the install latency on every cold start:
+#           - data:    pandas, numpy, matplotlib, openpyxl
+#           - web:     requests, beautifulsoup4, lxml, pyyaml
+#           - office:  python-docx, python-pptx, pypdf, reportlab,
+#                      markitdown (universal-converter)
+#   omitted: chromium, xvfb, x11vnc, fluxbox, supervisor, noVNC,
+#           wmctrl, x11-xserver-utils, all the X11/GUI client libs
+#           (libnss3, libatk*, libcups2, libgbm1, libxss1,
+#           libasound2, libxshmfence1, libxkbcommon0, libpango,
+#           libxcomposite1, libxdamage1, libxrandr2)
+#
+# Total image is ~600 MB compressed vs `browser.yaml`'s ~3.2 GB.
+# Use `browser.yaml` instead when the workload genuinely needs to
+# pilot a browser (visual scraping, JS-heavy SPA rendering, etc).
+
+image: node:22-slim
+cpus: 4
+memory_mib: 4096
+
+exec:
+  # APT mirror (China-mainland speed-up; harmless elsewhere — the
+  # debian.sources file replacement is a no-op when the original
+  # entries are already mirrored at the alibaba endpoint).
+  - sed -i 's|deb.debian.org|mirrors.aliyun.com|g; s|security.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources
+  - apt-get update -qq
+
+  # One apt install. node:22-slim already ships ca-certificates +
+  # xz-utils, so we don't repeat them here. Order roughly: shell
+  # essentials, dev tools, fonts, libreoffice, python.
+  - DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends curl sudo git jq build-essential less vim-tiny zip unzip fontconfig fonts-noto-cjk fonts-noto-color-emoji libreoffice-writer libreoffice-calc libreoffice-impress python3 python3-pip python3-venv
+  - rm -rf /var/lib/apt/lists/*
+
+  # Mirror npm + pip to local CDNs. Same rationale as the apt
+  # mirror — no-op outside CN, big speed-up inside.
+  - npm config set registry https://registry.npmmirror.com
+  - pip3 config --global set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
+
+  # Pre-install common pip libs so one-shot data tasks don't pay
+  # cold-start install latency. Three groups:
+  #   data:    pandas, numpy, matplotlib, openpyxl  (xlsx via pandas)
+  #   web:     requests, beautifulsoup4, lxml, pyyaml
+  #   office:  python-docx (docx), python-pptx (pptx), pypdf
+  #            (PDF read), reportlab (PDF write), markitdown
+  #            (universal converter — docx/xlsx/pptx/pdf/html/csv
+  #            → markdown)
+  # ~250 MB combined; reasonable for the value vs always installing
+  # on demand.
+  - pip3 install --no-cache-dir --break-system-packages pandas numpy matplotlib requests pyyaml lxml beautifulsoup4 openpyxl python-docx python-pptx pypdf reportlab markitdown
+
+  # Refresh font cache so matplotlib/PIL render CJK on first call.
+  - fc-cache -fv
+
+  # === Verify ============================================================
+  - bash -c "node --version && npm --version && python3 --version && pip3 --version"
+  - bash -c "git --version && jq --version | head -1"
+  - bash -c "python3 -c 'import pandas, numpy, matplotlib, requests, openpyxl, docx, pptx, pypdf, reportlab; import markitdown; print(\"py-libs ok\")'"
+  - bash -c "soffice --version | head -1"
+  - echo OK

package/packages/server/builtinConfig/plugins/web-search/manifest.json

@@ -0,0 +1,65 @@
+{
+  "id": "web-search",
+  "version": "0.1.0",
+  "displayName": "Web Search",
+  "description": "Web search via Tavily and Brave Search APIs. One tool, two providers, automatic fallback. Set API keys in Settings → Plugins.",
+  "author": "tianshu-ai",
+  "license": "Apache-2.0",
+  "permissions": ["network.external"],
+  "server": { "entry": "@tianshu-builtin/plugin-web-search/server" },
+  "contributes": {
+    "tools": [
+      { "id": "web_search", "module": "WebSearchTool" }
+    ],
+    "skills": [
+      {
+        "id": "web-search-howto",
+        "path": "skills/web-search-howto.md"
+      }
+    ],
+    "apiRoutes": [
+      { "method": "GET", "path": "/health", "handler": "getHealth" },
+      { "method": "POST", "path": "/health/reset", "handler": "resetHealth" }
+    ]
+  },
+  "configSchema": {
+    "fields": [
+      {
+        "key": "tavilyApiKey",
+        "label": "Tavily API key",
+        "kind": "secret",
+        "placeholder": "tvly-...",
+        "description": "Sign up at tavily.com (free tier 1000 searches/month). Stored under <tenant>/secrets/, never returned to the browser."
+      },
+      {
+        "key": "braveApiKey",
+        "label": "Brave Search API key",
+        "kind": "secret",
+        "placeholder": "BSA...",
+        "description": "Optional. Get a free key at api-dashboard.search.brave.com (2000/month). Used as fallback when Tavily fails or returns nothing."
+      },
+      {
+        "key": "preferredProvider",
+        "label": "Preferred provider",
+        "kind": "select",
+        "default": "tavily",
+        "options": [
+          { "label": "Tavily", "value": "tavily" },
+          { "label": "Brave", "value": "brave" }
+        ],
+        "description": "Tried first when both keys are set. The other provider is used as automatic fallback only on transient errors (network / 5xx / 429). Auth failures (401 / 403) park the bad key in the health cache; clear it from Settings after fixing the key."
+      },
+      {
+        "key": "timeoutMs",
+        "label": "Per-request timeout",
+        "kind": "number",
+        "unit": "ms",
+        "min": 1000,
+        "max": 60000,
+        "step": 500,
+        "default": 8000,
+        "description": "Network timeout for each provider call. Increase if you hit timeouts on slow networks."
+      }
+    ]
+  }
+}

package/packages/server/builtinConfig/plugins/web-search/skills/web-search-howto.md

@@ -0,0 +1,69 @@
+---
+name: web-search-howto
+description: How to use the `web_search` tool for tasks that need fresh information from the open web — current events, recent docs, prices, release notes, anything not in your training set or in the user's local files.
+scope: worker
+---
+
+# Web search
+
+`web_search` returns a JSON array of `{title, url, content,
+publishedDate}` objects from Tavily or Brave Search (whichever
+the host has an API key for; you don't have to pick).
+
+## Basic call
+
+```
+web_search({ query: "anthropic claude 4.7 release notes" })
+```
+
+Returns up to 5 results. Read titles + snippets first, only
+fetch the URL with `read_file`-style web fetchers when the
+snippet is insufficient.
+
+## Tuning
+
+- `count` (1-20, default 5): more results when you're sweeping
+  ("recent papers on retrieval-augmented generation"); fewer
+  when you know there's a canonical source ("python 3.13
+  release date").
+- `freshness`: `"day" | "week" | "month" | "year"`. Use this
+  for "what happened this week / this month" — without it,
+  search ranks by relevance over the whole web, which buries
+  recent news under older authoritative pages.
+- `language`: ISO 639-1 or locale, e.g. `"zh-CN"`, `"en"`.
+  Biases engines toward language-specific sources. Skip this
+  for technical English-language queries; technical content is
+  usually English regardless of locale.
+- `provider`: force `"tavily"` or `"brave"` if you want a
+  specific source. Default is "host's preferred provider with
+  fallback".
+
+## Anti-patterns
+
+- **Don't loop tiny searches.** Five searches with one keyword
+  each is worse than one search with the keywords combined.
+  `web_search({query: "claude 4.7 anthropic 2026 benchmark"})`
+  beats five separate searches.
+- **Don't ask `web_search` to summarise.** It doesn't. Read the
+  snippets, fetch the page if you need the full text, then
+  summarise yourself.
+- **Don't dump all results into the final answer.** Pick the
+  one or two most authoritative URLs, quote the relevant line,
+  cite. Agents who paste 10 result blocks turn answers into
+  noise.
+
+## When the snippet isn't enough
+
+`content` is 1-3 sentences. For the actual page body, fetch
+the URL through whatever HTTP fetcher you have available
+(`read_file` on a previously-saved page, the browser tools,
+etc.). `web_search` itself does not return page bodies; that's
+intentional — fetching only the URLs you actually need keeps
+the tool fast and cheap.
+
+## Citing sources
+
+When you use a result in a final answer, cite it with the
+title and URL. The agent who reads your output (the user, or
+the next worker in the chain) shouldn't have to retrieve it
+themselves to verify your claim.

package/packages/server/builtinConfig/plugins/workboard/agent-seeds/echo-demo/agent.json

@@ -0,0 +1,7 @@
+{
+  "kind": "echo",
+  "displayName": "Echo demo",
+  "description": "Sleeps, then echoes the task title. Ships with the workboard plugin.",
+  "enabled": true,
+  "source": "builtin"
+}

package/packages/server/builtinConfig/plugins/workboard/agent-seeds/llm-default/SOUL.md

@@ -0,0 +1,53 @@
+You are a workboard worker agent.
+
+You were started because the orchestrator dropped a task on the
+kanban for you. Each invocation handles ONE task end-to-end and
+then exits.
+
+## Your job
+
+- Read the task title and description carefully. The user (the
+  asking agent) wrote them; treat them as the spec.
+- Use whatever tools you need to do the work. The host's standard
+  tool set is available unless the orchestrator restricted you.
+- Write deliverables under the user's workspace (./projects/<slug>/
+  for finished output, ./tmp/ for scratch).
+
+## Exit contract (important)
+
+When you're done — or if the task is impossible and you've
+decided to give up — call the `task_complete` tool with a
+one-line `summary` of what you produced (or, on failure, why
+you couldn't). Optionally include `files` for paths you wrote.
+
+The orchestrator only sees the summary you pass to task_complete
+— prose alone won't reach it. If you finish without calling this
+tool, the pool counts the run as stalled and will retry.
+
+Do NOT ask the user clarifying questions: there's no human in
+your loop. If the spec is ambiguous, make a reasonable choice,
+proceed, and explain the choice in the task_complete summary.
+
+Reply concisely. Don't narrate every tool call — just do the
+work.
+
+## Reading skills before you act
+
+You have an `<available_skills>` block in your system prompt.
+Before starting any task, scan it. If a skill clearly applies,
+read its SKILL.md (use `tenant_config_read` for tenant skills
+or `read_file` for host/plugin skills) before doing anything
+else. Common triggers:
+
+- The task asks you to read ≥ 2 non-trivial files OR produce a
+  large output (long HTML / md / generated code) → you almost
+  certainly want to read **large-input-large-output** first.
+  The default failure mode is to batch-read all sources in one
+  turn and then try to emit the whole output in one
+  `write_file`; that runs you out of context or output budget
+  and the run aborts mid-call. The skill spells out the
+  read-then-summarise / skeleton-then-fill / batch-edit
+  patterns that avoid this.
+- The task involves running code → see `microsandbox-exec-howto`.
+
+One skill up front max. If none clearly applies, read none.

package/packages/server/builtinConfig/plugins/workboard/agent-seeds/llm-default/agent.json

@@ -0,0 +1,7 @@
+{
+  "kind": "llm",
+  "displayName": "Default LLM",
+  "description": "Default LLM worker. Picks up tasks tagged with worker_role=llm (or unrouted) and runs them to task_complete.",
+  "enabled": true,
+  "source": "builtin"
+}

package/packages/server/builtinConfig/plugins/workboard/manifest.json

@@ -0,0 +1,180 @@
+{
+  "id": "workboard",
+  "version": "0.1.0",
+  "displayName": "Workboard",
+  "description": "Kanban task board with a worker pool. The orchestrator drops tasks onto the board; workers pick them up, run them, and report back. v0.2 ships an echo worker so the full ready→in-progress→done loop is visible end-to-end; real worker runtimes (qianliyan / luban / xihe / nvwa) land in follow-up PRs as separate plugins.",
+  "author": "tianshu-ai",
+  "license": "Apache-2.0",
+  "permissions": ["workspace.read", "tenant.db"],
+  "requires": ["host.agentLoop", "host.sessionInbox", "host.toolCatalog", "host.skillCatalog", "host.modelCatalog"],
+  "client": { "entry": "@tianshu-builtin/plugin-workboard/client" },
+  "server": { "entry": "@tianshu-builtin/plugin-workboard/server" },
+  "contributes": {
+    "topBarButtons": [
+      {
+        "id": "toggle",
+        "icon": "Kanban",
+        "tooltip": "Task board",
+        "opensPanel": "workboard.main",
+        "order": 200
+      }
+    ],
+    "rightPanels": [
+      {
+        "id": "main",
+        "displayName": "Tasks",
+        "component": "WorkboardPanel"
+      }
+    ],
+    "sidebarSections": [
+      {
+        "id": "workers",
+        "displayName": "Workers",
+        "component": "WorkersSidebarSection",
+        "after": "workers",
+        "order": 100
+      }
+    ],
+    "adminPages": [
+      {
+        "id": "agents",
+        "displayName": "Worker agents",
+        "icon": "Bot",
+        "component": "WorkerAgentsPage",
+        "order": 10
+      }
+    ],
+    "tools": [
+      { "id": "task_list",                "module": "TaskListTool"               },
+      { "id": "task_create",              "module": "TaskCreateTool"             },
+      { "id": "task_update",              "module": "TaskUpdateTool"             },
+      { "id": "task_move",                "module": "TaskMoveTool"               },
+      { "id": "task_delete",              "module": "TaskDeleteTool"             },
+      { "id": "task_get_history",         "module": "TaskGetHistoryTool"         },
+      { "id": "task_complete",            "module": "TaskCompleteTool"           },
+      { "id": "task_continue",            "module": "TaskContinueTool"           },
+      { "id": "task_retry_fresh",         "module": "TaskRetryFreshTool"         },
+      { "id": "task_extend_timeout",      "module": "TaskExtendTimeoutTool"      },
+      { "id": "task_abort",               "module": "TaskAbortTool"              },
+      { "id": "model_list",               "module": "ModelListTool"              }
+    ],
+    "skills": [
+      { "id": "workboard-howto",          "path": "skills/workboard-howto.md"          },
+      { "id": "worker-creator",           "path": "skills/worker-creator.md"           },
+      { "id": "worker-fleet",             "path": "skills/worker-fleet.md"             },
+      { "id": "large-input-large-output", "path": "skills/large-input-large-output.md" }
+    ],
+    "agentSeeds": [
+      { "id": "echo-demo",   "path": "agent-seeds/echo-demo"   },
+      { "id": "llm-default", "path": "agent-seeds/llm-default" }
+    ],
+    "systemPromptFragments": [
+      {
+        "id": "prefer-delegation",
+        "text": "The workboard is active in this tenant. For any non-trivial user request — anything that takes more than a few minutes, fans out into multiple steps, or has clearly separable roles (design / build / test, research / write, etc.) — your default is to DELEGATE to worker agents via `task_create` rather than execute it yourself. The `worker-fleet` skill covers task decomposition (plan / design / build / verify phases), task sizing (avoiding max_tokens stalls on monolithic tasks), worker selection (matching by capability), and brief authoring (each task description is the worker's only view of the work) — read it before designing the task graph. Reuse existing workers (run `tenant_config_list({path:\"workers\"})` first); the `worker-creator` skill covers authoring agent.json + SOUL.md when no existing worker fits. Do the work yourself directly only when (a) the user explicitly says so, (b) the request is trivial (single tool call, one-line answer, quick lookup), or (c) the user wants a synchronous reply. When in doubt, ack the plan and give the user a chance to override."
+      },
+      {
+        "id": "summarize-on-completion",
+        "text": "When the workboard tasks you delegated for the user's current request have all finished, your job isn't done — you owe the user a synthesised reply. Steps: (1) Call `task_list({status:\"done\"})` (or filter by labels/ids you tracked) to confirm every task you created in this turn has actually completed; if any are still running, wait or fetch their status before composing. (2) For each completed task, call `task_get_history({id})` and READ the worker's actual output — don't trust `resultSummary` alone; workers sometimes write a one-liner that hides nuance, errors, or important findings. Skim the final assistant message + any tool results that produced files. (3) Compose ONE coherent reply to the user that: covers the original goal, integrates the per-task findings into a narrative (not a bulleted dump of resultSummaries), explicitly cites every output file the workers produced (use the file's path, and where the tenant has the `files` plugin enabled use the standard file-reference markup the user's chat client understands so they can click through), and surfaces any failures / partial results honestly. (4) If a task ended in awaiting-intervention, do NOT just report the failure — either resolve it yourself (task_continue / task_retry_fresh / task_extend_timeout / task_abort) before replying, or include in the reply a concrete suggestion for what the user should choose. Keep the synthesis honest: if outputs contradict each other or a worker punted, say so; don't paper over with cheerful language."
+      }
+    ],
+    "apiRoutes": [
+      { "method": "GET",    "path": "/tasks",              "handler": "listTasks"     },
+      { "method": "POST",   "path": "/tasks",              "handler": "createTask"    },
+      { "method": "POST",   "path": "/tasks/delete",       "handler": "deleteTask"    },
+      { "method": "PATCH",  "path": "/tasks/:id",          "handler": "patchTask"     },
+      { "method": "GET",    "path": "/tasks/:id/history",  "handler": "taskHistory"   },
+      { "method": "GET",    "path": "/projects",           "handler": "listProjects"  },
+      { "method": "GET",    "path": "/workers/status",     "handler": "workerStatus"  },
+      { "method": "POST",   "path": "/workers/restart",    "handler": "workerRestart" },
+      { "method": "GET",    "path": "/agents",             "handler": "listAgents"    },
+      { "method": "PATCH",  "path": "/agents/:slug/enabled", "handler": "setAgentEnabled" }
+    ]
+  },
+  "configSchema": {
+    "fields": [
+      {
+        "key": "echo.enabled",
+        "label": "Enabled",
+        "kind": "boolean",
+        "default": true,
+        "group": {
+          "id": "worker-type-echo",
+          "label": "echo",
+          "badge": "worker type"
+        }
+      },
+      {
+        "key": "echo.delayMs",
+        "label": "Simulated execution delay",
+        "description": "How long an echo worker pretends to be busy on each task before marking it done. 0 makes tasks complete instantly.",
+        "kind": "number",
+        "default": 30000,
+        "min": 0,
+        "step": 1000,
+        "unit": "ms",
+        "group": {
+          "id": "worker-type-echo",
+          "label": "echo",
+          "badge": "worker type"
+        }
+      },
+      {
+        "key": "llm.enabled",
+        "label": "Enabled",
+        "kind": "boolean",
+        "default": true,
+        "group": {
+          "id": "worker-type-llm",
+          "label": "llm",
+          "badge": "worker type"
+        }
+      },
+      {
+        "key": "llm.firstResponseSec",
+        "label": "First-response timeout",
+        "description": "Hard cap on how long the LLM has to start streaming the very first event of the run. Catches connection-hung scenarios. Set to 0 to disable.",
+        "kind": "number",
+        "default": 300,
+        "min": 0,
+        "step": 30,
+        "unit": "s",
+        "group": {
+          "id": "worker-type-llm",
+          "label": "llm",
+          "badge": "worker type"
+        }
+      },
+      {
+        "key": "llm.idleSec",
+        "label": "Idle timeout",
+        "description": "Mid-stream silence cap: if the LLM goes this long without emitting any event, abort the run as stuck. Long enough to allow large `write_file` arguments to stream through.",
+        "kind": "number",
+        "default": 600,
+        "min": 0,
+        "step": 60,
+        "unit": "s",
+        "group": {
+          "id": "worker-type-llm",
+          "label": "llm",
+          "badge": "worker type"
+        }
+      },
+      {
+        "key": "llm.maxRunSec",
+        "label": "Max run time",
+        "description": "Total wall-clock cap for one task run, across all turns. Protects against runaway loops.",
+        "kind": "number",
+        "default": 1800,
+        "min": 0,
+        "step": 60,
+        "unit": "s",
+        "group": {
+          "id": "worker-type-llm",
+          "label": "llm",
+          "badge": "worker type"
+        }
+      }
+    ]
+  }
+}

package/packages/server/builtinConfig/plugins/workboard/skills/large-input-large-output.md

@@ -0,0 +1,185 @@
+---
+name: large-input-large-output
+description: How to handle tasks that read many large files OR produce a large structured output (long HTML, long markdown report, long codegen). Read this when a task description asks you to ingest more than two non-trivial files at once, or to write more than ~500 lines in one shot, or both. Covers the read-then-summarise pattern, skeleton-then-fill pattern, and the spill-to-file escape hatch.
+scope: worker
+---
+
+# Reading lots, writing lots
+
+The default failure mode for a task like *"read these 5 markdown
+notes and produce one HTML report"* is:
+
+1. You issue 5 parallel `read_file` calls in one assistant turn.
+2. Five tool results, each tens of KB, all land in the next
+   prompt as raw text.
+3. You try to emit the whole HTML in one tool call.
+4. The LLM call truncates / returns empty / the run aborts as
+   `no_completion`.
+
+The orchestrator can't see this from outside — to it the task
+just stalled. From the inside the cause is obvious: you carried
+too much state in the prompt and asked for too much output in
+one shot.
+
+This skill is the recipe for not doing that.
+
+## When this applies
+
+Read this skill at the top of any task description that:
+
+- names ≥ 2 source files you have to read in detail, OR
+- asks for an output > ~500 lines (long HTML / long md / long
+  code), OR
+- bundles "read material A, B, C, ... and synthesise into D"
+  (the canonical multi-input synthesis shape).
+
+If the task is a small one-off ("read README.md, summarise",
+"write a 50-line script"), this skill is overkill. Skip it.
+
+## Pattern 1 — Read-then-summarise per file
+
+Cardinal rule: **what you keep in the prompt should be what you
+need for the next step, not what you originally read.**
+
+Sequence:
+
+1. Read file 1.
+2. **Immediately** write a structured summary to disk:
+   ```
+   write_file({
+     path: "/tmp/<task-slug>/summary-01.md",
+     content: "<2-3 paragraphs covering the bits that matter
+       for the final output: claims, citations, headings,
+       any quote you'll want verbatim>"
+   })
+   ```
+3. Repeat for file 2, file 3, ... — **one file per turn**, not
+   five files in one batched read.
+4. When you start composing the output, read the **summary**
+   files, not the originals. The summaries fit comfortably; the
+   originals don't.
+5. If you discover the summary is missing a fact mid-composition,
+   targeted re-read the original (`read_file` with `offset` and
+   `limit`) — don't load the whole thing again.
+
+Why per-turn matters: tool results from a single turn all stay
+in the next prompt. Five 30 KB files in one turn = 150 KB you
+never wanted to keep. One file per turn lets auto-compact (which
+fires after each turn_end) trim earlier turns away once you've
+written the summary file.
+
+## Pattern 2 — Long output: write iteratively, not in one shot
+
+When the deliverable is big (long HTML, multi-section markdown,
+a 1500-line generated file), the failure mode you want to avoid
+is **emitting the whole thing in one tool call.** Two reasons:
+
+- The provider's tool_use input stream truncates large strings,
+  so a `write_file` carrying thousands of lines of `content`
+  often fails with `content` missing entirely.
+- Even if the call lands, the next agent / human reading the
+  task has nothing to follow until the giant blob arrives. A
+  partial run leaves nothing on disk.
+
+Do this instead:
+
+1. Decide the structure of the output up front (TOC, section
+   list, what each section contains). Write that as a short
+   plan in the task description — you'll reference it as you go.
+2. Write the file in pieces. The shape that works depends on
+   the deliverable:
+   - **Markdown / prose / HTML report:** use `write_file` for
+     the first chunk (front matter / TOC / first section), then
+     `read_file` and `edit_file` to append each subsequent
+     section. Each `edit_file` call can target the end-of-file
+     marker (e.g. "</body>") and replace it with `new_section +
+     marker`.
+   - **Generated code:** `write_file` the file once with the
+     real content; if the result is so big the call is
+     truncating, the file is too big for one LLM run regardless
+     of tool shape — split the deliverable into separate files
+     (one module per file is the right shape anyway).
+3. After each chunk: keep the chunk size small enough that the
+   tool_use args don't get truncated. There's no fixed line
+   count — watch for the truncation hint in the tool result.
+
+This pattern's side benefits:
+
+- The output file exists after the first call, so a partial
+  run still leaves something on disk.
+- The agent can `read_file` what it just wrote when composing
+  later sections, keeping coherence without re-loading sources.
+
+What *not* to do:
+
+- Do not write a "skeleton" full of `<!-- TODO: section X -->`
+  placeholders and then try to fill them all in one
+  `edit_file({edits: [...]})` batch. The combined batch JSON
+  ends up larger than the original write would have been and
+  trips the same truncation it was meant to avoid. (This
+  recipe used to be in this skill; it didn't work.)
+
+## Pattern 3 — Spill to file (escape hatch)
+
+If you absolutely must work with the raw text of a large source
+mid-composition (e.g. exact quote attribution), **don't paste
+the whole file into your reasoning**. Instead:
+
+1. Read the file once, write its content to
+   `/tmp/<task-slug>/source-<n>.md` (you can also just leave it
+   at its original path).
+2. Use `read_file` with `offset` + `limit` to pull the exact
+   slice you need.
+3. Throw the slice into your output and move on. Don't keep the
+   full file's content in your reasoning across turns.
+
+`tenant_config_read` (for skills / config) and `read_file` (for
+workspace) both support `offset` + `limit`. Use them.
+
+## Anti-patterns — don't do these
+
+- **Five `read_file` calls in one assistant turn.** This is
+  the most common offender. Even if every file is "small", the
+  combined tool result will dominate the next prompt.
+- **Asking the LLM to "now generate the whole HTML"** after
+  loading five sources. Either you trim sources first (pattern
+  1) or you write iteratively (pattern 2) or both.
+- **Re-reading a file you've already summarised.** If you wrote
+  a summary, trust it. If you don't, write a better summary next
+  time.
+- **Treating `task_complete` as the moment the deliverable is
+  produced.** It's the moment you announce the deliverable is
+  done. The file should already exist on disk before you call
+  task_complete.
+- **One giant `write_file` for a 2000-line HTML report.** Even
+  if the model can produce it without truncating, the next
+  agent / human reading the work has nothing to follow until
+  the whole thing lands. Write the file in chunks (Pattern 2).
+- **One `edit_file` call per tiny edit** when you're making
+  several adjacent changes — the `edits[]` batch is atomic
+  and saves round-trips. (This is the right reason to use
+  `edits[]`; it's not a workaround for tool-arg truncation.)
+
+## When you're stuck mid-task
+
+If you find yourself in the failure mode this skill describes —
+you've loaded too much, the next call is failing, you're not
+sure how to proceed:
+
+1. Stop trying to emit the deliverable.
+2. Write `/tmp/<task-slug>/state.md` capturing what you've done
+   so far and what's left.
+3. **Then** call `task_complete` with summary
+   `"partial: section 1/4 written. See state.md for remaining
+   work."` — including the fact that it's partial in the
+   summary.
+4. The orchestrator can read state.md and either continue this
+   task or split the rest into a follow-up task. That's
+   recoverable; a `no_completion` stall is not.
+
+## See also
+
+- `workboard-howto` — task lifecycle, task_complete contract,
+  how the orchestrator reads your output.
+- `microsandbox-exec-howto` — for tasks that compile / run code
+  rather than read / write large text.