You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: advanced/context-pruning.md
+19-1Lines changed: 19 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -270,6 +270,24 @@ When context is compacted, the summary now preserves key identifiers — agent I
270
270
271
271
Tool output is now capped at the source before being added to context. Rather than waiting for the pruning pipeline to trim oversized results after the fact, GoClaw limits tool output size at ingestion time. This reduces unnecessary memory pressure and makes the pruning pipeline more predictable.
272
272
273
+
### Dynamic Compaction Summary Budget
274
+
275
+
When session compaction runs, the output-token budget for the summary is no longer a static cap. It is now computed dynamically:
276
+
277
+
```
278
+
max_tokens = clamp(input_tokens / 25, 1024, 8192)
279
+
```
280
+
281
+
Short histories get a smaller budget (floor: 1024 tokens) and long histories get a larger one (cap: 8192 tokens). This replaces any previously documented static 4096-token cap.
282
+
283
+
### Tool-Schema Tokens in OverheadTokens
284
+
285
+
`OverheadTokens` — the token count that ContextStage subtracts from the usable window before pruning — now includes the tokens consumed by all registered tool schemas, in addition to the system prompt. Previously only system-prompt tokens were counted. This means agents with many or large tools will see a higher overhead value and pruning will trigger slightly earlier.
286
+
287
+
### Compaction Overflow Recovery
288
+
289
+
When the context remains over budget even after a compaction sweep (for example, the system prompt and tool schemas alone nearly fill the window), GoClaw performs a secondary recovery sweep before surfacing an error. This overflow recovery path (PR #958) caps retries at one attempt and returns a `context overflow after compaction` error only when the second sweep also fails. In practice this prevents hard failures for agents with large tool schemas or system prompts.
290
+
273
291
---
274
292
275
293
## What's Next
@@ -278,4 +296,4 @@ Tool output is now capped at the source before being added to context. Rather th
278
296
-[Memory System](../core-concepts/memory-system.md) — 3-tier memory architecture and consolidation pipeline
279
297
-[Configuration Reference](/config-reference) — full agent config reference
Copy file name to clipboardExpand all lines: advanced/custom-tools.md
+26-1Lines changed: 26 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -185,6 +185,31 @@ The check runs on the **fully rendered command** after all `{{.param}}` substitu
185
185
| Tool not visible to agent | Wrong `agent_id` or `enabled: false`| Verify agent ID; re-enable if disabled |
186
186
| Execution timeout | Default 60 s too short for the task | Increase `timeout_seconds`|
187
187
188
+
## Built-in Tool: send_file
189
+
190
+
The `send_file` tool delivers an existing file in the workspace as an attachment — it does **not** create or modify files, only deliver them.
191
+
192
+
| Parameter | Required | Description |
193
+
|-----------|----------|-------------|
194
+
|`path`| Yes | File path (relative to workspace or absolute) |
195
+
|`caption`| No | Message to accompany the file |
196
+
197
+
**Example:** An agent has generated a report at `reports/summary.pdf` and then calls:
198
+
199
+
```json
200
+
{ "path": "reports/summary.pdf", "caption": "Here's this week's report" }
201
+
```
202
+
203
+
### DeliveredMedia Cross-Tool Dedup Contract
204
+
205
+
GoClaw maintains a `DeliveredMedia` tracker for the lifetime of an agent run. When the `message` tool sends `MEDIA:<path>`, that path is marked as delivered. If the agent subsequently calls `send_file` on the same path, the call is a **no-op** — the file is not sent again.
206
+
207
+
This prevents duplicate delivery in the common pattern where an agent reflexively calls both `write_file(deliver=true)` (which auto-sends via `message`) and `send_file` on the same file.
In addition to custom shell tools, GoClaw includes built-in vault tools for knowledge management. These are always available when the vault store is enabled.
@@ -225,4 +250,4 @@ Returns all documents that link to the specified path. Respects team boundaries
225
250
-[Exec Approval](/exec-approval) — require human approval before commands run
226
251
-[Sandbox](/sandbox) — run commands inside Docker for extra isolation
2. Adds composite index `idx_vault_docs_team_chat` on `(team_id, chat_id) WHERE team_id IS NOT NULL`
111
+
3. Drops the `vault_documents_scope_consistency` constraint before running backfill UPDATEs — the constraint was added as `NOT VALID` in migration 055, meaning it skipped existing rows but still re-checked every UPDATE. Legacy data (pre-M46/M43) often violated the invariant, causing the backfill to abort and leaving migration 056 in a dirty state (issue #1035, fixed in v3.11.2). The constraint is re-added at the end of the migration with `NOT VALID`.
112
+
113
+
**Backfill logic:**
114
+
115
+
Migration 056 backfills `chat_id` for two groups:
116
+
117
+
-**Team-scoped docs** (`scope='team'`): extracts the chat segment from the path (`teams/<uuid>/<chat>/...` or `tenants/<slug>/teams/<uuid>/<chat>/...`). Segments starting with `.` (config dirs such as `.goclaw`) are skipped.
118
+
-**Legacy docs** (`team_id IS NULL`): a broader regex covers **all channel integrations**: `telegram`, `discord`, `zalo`, `feishu`, `lark`, `whatsapp`, `slack`, `line`, `messenger`, `wechat`, `viber`, `ws`, `delegate`, `api` — not just telegram/discord as in older releases.
119
+
120
+
**Related search parameters:**
121
+
122
+
| Parameter | Type | Notes |
123
+
|-----------|------|-------|
124
+
|`ChatID`|*string | Pointer to the chat ID to filter by; nil = no filter |
Codex and OpenAI-compatible providers support **native** image generation — an `image_generation` tool object is attached directly to the LLM request rather than going through the `create_image` provider chain.
89
+
90
+
### Tri-Level Gate
91
+
92
+
All three conditions must be satisfied for `image_generation` to activate:
93
+
94
+
| Gate | Source | Default |
95
+
|------|--------|---------|
96
+
| Provider capability (`ProviderCapabilities.ImageGeneration`) | Auto-set `true` for Codex and OpenAI-compat | — |
97
+
|`AgentConfig.AllowImageGeneration`|`other_config.allow_image_generation` in agent config |`true`|
98
+
| Header opt-out | Client sends `x-goclaw-no-image-gen` to disable per-request | not sent = allowed |
99
+
100
+
To disable native image generation for a specific agent:
101
+
102
+
```json
103
+
{
104
+
"other_config": {
105
+
"allow_image_generation": false
106
+
}
107
+
}
108
+
```
109
+
110
+
To opt out per-request, the client sends the header:
111
+
112
+
```
113
+
x-goclaw-no-image-gen: 1
114
+
```
115
+
116
+
### Partial-Image Streaming
117
+
118
+
During image generation, Codex emits `response.image_generation_call.partial_image` events over the SSE stream. GoClaw surfaces these events so clients can display incremental previews before the final image is complete.
119
+
120
+
### Storage and Metadata
121
+
122
+
Image files are saved to `{workspace}/media/{sha256}.{ext}` (e.g. `media/a3f7bc12.png`). For PNG files, GoClaw embeds a tEXt metadata chunk immediately before IEND:
123
+
124
+
| Chunk key | Value |
125
+
|-----------|-------|
126
+
|`Description`| User prompt |
127
+
|`Software`|`goclaw`|
128
+
129
+
This metadata supports audit and prompt traceability directly from the image file.
130
+
131
+
### Codex Pool Routing
132
+
133
+
When a Codex pool is configured, image generation requests go through the `create_image` chain with a **per-modality round-robin counter** — the chat counter and image counter operate independently. This prevents image generation from skewing the chat load distribution.
| Container not cleaned up after session | Pruner not running or `idle_hours` too high | Lower `idle_hours`; check `sandbox pruning started` in logs |
241
241
| Write fails inside container |`workspace_access: ro` or `read_only_root: true` with no tmpfs | Switch to `rw` or add a tmpfs mount for the target path |
242
242
243
+
## Team-Root Workspace Boundaries
244
+
245
+
When an agent runs in team-root mode (part of an agent team), it has **read access** to peer-chat workspaces across the team. However, read-allowed and write-allowed paths are kept separate:
246
+
247
+
| Operation | Path set used |
248
+
|---|---|
249
+
|`read_file`, `list_files`| Read-allowed — includes team root and peer-chat workspaces |
250
+
|`write_file`, `edit`| Write-allowed — restricted to the agent's own chat workspace only |
251
+
|`exec` / `shell`| Write-allowed — cwd resolution uses the more restrictive write-allowed prefixes |
252
+
253
+
This asymmetry prevents a team-root agent from mutating peer-chat workspaces even though it can read them. Absolute paths in shell commands are also bounded by the write-allowed prefix set, closing the path that allowed cross-chat mutations via `cd` or absolute argument injection.
254
+
255
+
> **Note:** This workspace boundary applies regardless of sandbox mode. Sandbox mode controls whether commands run inside Docker; team-root path restrictions are enforced at the tool layer before Docker is involved.
256
+
243
257
## What's Next
244
258
245
259
-[Custom Tools](/custom-tools) — define shell tools that also benefit from sandbox isolation
246
260
-[Exec Approval](/exec-approval) — require human approval before any command runs, sandboxed or not
247
261
-[Scheduling & Cron](/scheduling-cron) — run sandboxed agent turns on a schedule
@@ -284,6 +284,7 @@ Categories: Emotion, Pacing, Effect, Voice quality. Full tag list is in the fron
284
284
|`ErrInvalidVoice`| Voice ID not in the 30 prebuilt set |
285
285
|`ErrSpeakerLimit`| More than 2 speakers in multi-speaker mode |
286
286
|`ErrInvalidModel`| Model ID not in the allowed list |
287
+
|`MsgTtsGeminiTextOnly`| Text-only response after auto-retry (see troubleshooting) |
287
288
288
289
---
289
290
@@ -347,6 +348,14 @@ Keys outside this allow-list are rejected at write time. The adapter runs per-at
347
348
348
349
When the primary provider fails, GoClaw automatically tries the other registered providers.
349
350
351
+
### Tenant Synthesis Timeout
352
+
353
+
The synthesis deadline is controlled by the `tts.timeout_ms` key in `system_configs` (tenant admin → Config → Audio → TTS). Default is **120000 ms (120 s)**. Set a higher value for slower providers or long-form audio; the gateway enforces a per-request context deadline equal to this value.
354
+
355
+
```
356
+
tts.timeout_ms = 120000 # default; increase for slow providers
357
+
```
358
+
350
359
---
351
360
352
361
## Voices API
@@ -535,6 +544,7 @@ The `stt` builtin tool (seeded by migration 050) enables agents to transcribe vo
535
544
| Text cut off with `...`| Over `max_length`| Increase `max_length` in config |
536
545
| Gemini 422 `ErrInvalidVoice`| Voice not in 30 prebuilt set | Use a valid voice ID from the table above |
537
546
| Gemini 422 `ErrSpeakerLimit`| More than 2 speakers | Reduce to ≤ 2 speakers in Voice Picker |
547
+
| Gemini 422 `MsgTtsGeminiTextOnly`| Gemini returned text instead of audio after auto-retry | GoClaw retries once with an inline audio prefix; if Gemini still refuses, the error surfaces as HTTP 422. Shorten the text, remove translation/commentary, or switch model. |
538
548
|`tts_params` key rejected | Key not in allow-list | Use only `speed`, `emotion`, `style`|
539
549
540
550
---
@@ -544,4 +554,4 @@ The `stt` builtin tool (seeded by migration 050) enables agents to transcribe vo
544
554
-[Scheduling & Cron](/scheduling-cron) — trigger agents on a schedule
545
555
-[Extended Thinking](/extended-thinking) — deeper reasoning for complex replies
Copy file name to clipboardExpand all lines: channels/discord.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -94,6 +94,10 @@ Media files (images, video, audio) sent in group conversations are tracked in me
94
94
95
95
On startup, the bot fetches its own user ID via `@me` endpoint to avoid responding to its own messages.
96
96
97
+
### Allowlist and Pairing Policy
98
+
99
+
`dm_policy` and `group_policy` work as documented — `pairing`, `allowlist`, and `open` modes are handled exclusively by the policy evaluation layer. There is no additional allowlist gate after the policy check, so paired users are not wrongly rejected when an `allow_from` list is also configured. If a user is paired but also listed in `allow_from`, both conditions are satisfied and the message proceeds normally.
100
+
97
101
### Group File Writer Management
98
102
99
103
Discord supports slash-command-based management of group file writers (similar to Telegram's writer restriction). In server channels, write-sensitive operations can be restricted to designated writers:
@@ -135,4 +139,4 @@ Per-guild/channel overrides are not yet supported in the Discord channel impleme
135
139
-[Larksuite](/channel-feishu) — Larksuite integration with streaming cards
0 commit comments