mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-18 04:09:33 +01:00
docs: finish dropping the stripped-newline rule from the input docs
The first commit left the old rule standing in places: the gotchas list in extending-codeman.md still said newlines were stripped and that "echo A\necho B\r" ran `echo Aecho B`, and so did both READMEs and the skill's big-input section. Those now describe the paste. Newlines are only kept on the mux path, so the docs that describe the paste say "with useMux": without it a multi-line body is not a plain prompt and is written straight into the pane. Cron keeps rejecting multi-line prompts, but its docs and the code comments in cron-service.ts, schemas.ts and respawn-controller.ts gave a reason this change removes (writeViaMux joining lines, a newline submitting in Ink). The reason that remains is the submit check, which cannot recognise a multi-line paste in the composer, and for cron's paste mode the newlines reaching the CLI as keys. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
e3de354461
commit
fe10cad83f
14 files changed
+58
-48
No files matched your search
@@ -851,7 +851,7 @@ When a CLI runs in a Codeman-managed session, these environment variables are se
|
||||
|
||||
### Rules of the road (read before you POST)
|
||||
|
||||
1. **Single-line input, ending in `\r`.** Programmatic input is sent as literal text, and Enter fires **only when the input contains a carriage return**: `{"input":"run tests\r"}`. Without the `\r` the text sits on the session's prompt unsubmitted (and a combined `wait` runs its full timeout on a turn that never started). Embedded newlines are stripped rather than rejected, so `"echo A\necho B\r"` runs the joined command `echo Aecho B`: send one line per call.
|
||||
1. **Input must end in `\r`.** Programmatic input is sent as literal text, and Enter fires **only when the input contains a carriage return**: `{"input":"run tests\r"}`. Without the `\r` the text sits on the session's prompt unsubmitted (and a combined `wait` runs its full timeout on a turn that never started). With `useMux`, embedded newlines are kept and the lines go in as one paste, so `"echo A\necho B\r"` runs both commands in a shell; the check that re-presses a stranded Enter cannot reliably recognise a multi-line paste, so put long multi-line content in a file the agent is told to read.
|
||||
2. **Make input idempotent.** Include a stable `clientId` and a monotonic per-session `seq` on `POST …/input`. The server de-duplicates, so a retry after a dropped connection can't double-deliver a prompt.
|
||||
3. **Auth.** If `CODEMAN_PASSWORD` is set, send HTTP Basic auth (user `admin` or `CODEMAN_USERNAME`) or a `codeman_session` cookie. The default loopback install is passwordless. A missing `Origin` header is allowed, so plain `curl` works; cross-site browser origins are rejected (CSRF guard). ⚠️ A `401` replies with the bare string `Unauthorized`, **not** the JSON envelope, so piping it into `jq` throws a parse error instead of showing the failure: check the status before parsing.
|
||||
4. **Response envelope.** Most endpoints return `{ "success": true, "data": … }` (errors: `{ "success": false, "error", "errorCode" }`). A few legacy GETs return bare bodies — **handle both** (`body.data ?? body`).
|
||||
|
||||
+1
-1
@@ -853,7 +853,7 @@ deleted 9f2d8e5f, aff9c691, be9f1f15 标签消失
|
||||
|
||||
### 行路规则(POST 之前先读)
|
||||
|
||||
1. **只发单行输入,而且必须以 `\r` 结尾。** 编程输入按字面文本发送,**只有当输入里含回车符时才会触发 Enter**:`{"input":"run tests\r"}`。少了 `\r`,文本就停在会话的输入框里不被提交(同一次调用里的 `wait` 还会在一个压根没开始的回合上耗满整个超时)。内嵌的换行会被剥掉而不是报错,因此 `"echo A\necho B\r"` 执行的是拼起来的 `echo Aecho B`:一次调用只发一行。
|
||||
1. **输入必须以 `\r` 结尾。** 编程输入按字面文本发送,**只有当输入里含回车符时才会触发 Enter**:`{"input":"run tests\r"}`。少了 `\r`,文本就停在会话的输入框里不被提交(同一次调用里的 `wait` 还会在一个压根没开始的回合上耗满整个超时)。使用 `useMux` 时内嵌的换行会保留,各行作为一次粘贴送入,因此 `"echo A\necho B\r"` 在 shell 里会执行两条命令;但重新按下滞留 Enter 的检查无法可靠识别多行粘贴,所以较长的多行内容最好写进文件,让 agent 自己去读。
|
||||
2. **让输入幂等。** 在 `POST …/input` 上带上稳定的 `clientId` 和按会话单调递增的 `seq`。服务端会去重,因此连接中断后的重试不会重复投递提示。
|
||||
3. **认证。** 若设置了 `CODEMAN_PASSWORD`,发送 HTTP Basic 认证(用户 `admin` 或 `CODEMAN_USERNAME`)或 `codeman_session` cookie。默认的环回安装无密码。缺失的 `Origin` 头被允许,因此普通 `curl` 可用;跨站的浏览器 origin 会被拒绝(CSRF 防护)。⚠️ `401` 回的是裸字符串 `Unauthorized`,**不是** JSON 信封,直接喂给 `jq` 只会抛解析错误而看不到真正的失败原因:先看状态码,再解析。
|
||||
4. **响应信封。** 多数端点返回 `{ "success": true, "data": … }`(错误:`{ "success": false, "error", "errorCode" }`)。少数遗留 GET 返回裸响应体 —— **两种都要处理**(`body.data ?? body`)。
|
||||
|
||||
+4
-3
@@ -207,9 +207,10 @@ trailing carriage return:
|
||||
| `typed` | `session.writeViaMux()` — the text as a tmux bracketed paste + Enter (a single character is typed, so a dialog answer selects) | Default; like a human pasting the prompt and pressing Enter. |
|
||||
| `paste` | `session.write()` — writes directly to the PTY/mux | Bulk paste-style delivery. |
|
||||
|
||||
> ⚠️ **Single-line only — enforced.** Like all programmatic input in Codeman,
|
||||
> multi-line delivery would be silently corrupted (Ink-based TUIs treat a
|
||||
> newline as submit; typed mode fuses lines). So newlines are **rejected**: the
|
||||
> ⚠️ **Single-line only — enforced.** A job fires unattended, and the submit
|
||||
> check that re-presses an ignored Enter cannot recognise a multi-line paste in
|
||||
> the composer, so a stranded prompt would go unnoticed (in paste mode the
|
||||
> newlines reach the CLI as keys). So newlines are **rejected**: the
|
||||
> schema and the form refuse a multi-line `promptText`, and at fire time a
|
||||
> prompt file whose content is multi-line (after stripping trailing newlines)
|
||||
> fails the run with a clear `errorMessage`. Put multi-line instructions in a
|
||||
|
||||
+12
-10
@@ -294,8 +294,8 @@ if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
|
||||
fi
|
||||
|
||||
# 3. Send the prompt AND register the wait in one call, so the answer cannot be
|
||||
# the previous turn's idle state. Single line only, ending in \r (otherwise
|
||||
# Enter is never sent and this wait times out on a turn that never started).
|
||||
# the previous turn's idle state. It must end in \r (otherwise Enter is never
|
||||
# sent and this wait times out on a turn that never started).
|
||||
W=$("${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"input":"Run the test suite and summarize the failures\r","useMux":true,
|
||||
@@ -414,14 +414,16 @@ Every one of these has cost somebody real time.
|
||||
shipped bugs more than once.
|
||||
- **`text/plain` bodies stay raw.** Auto-parsing them as JSON enabled
|
||||
simple-request CSRF, so it is deliberate. Send `application/json`.
|
||||
- **Prompts are single-line and must end with `\r`.** The server splits your text
|
||||
and Enter into two separate tmux writes (Ink needs them apart), but it sends the
|
||||
Enter **only when the input contains a carriage return**. Without it your text
|
||||
sits on the prompt unsubmitted, which is the single most common "the wait
|
||||
endpoints don't work" report: the wait runs its full timeout on a turn that never
|
||||
started. Newlines inside the string are stripped rather than rejected, so
|
||||
`"echo A\necho B\r"` runs the single joined command `echo Aecho B`: send one line
|
||||
per call.
|
||||
- **Prompts must end with `\r`.** The server splits your text and Enter into two
|
||||
separate tmux writes (Ink needs them apart), but it sends the Enter **only when
|
||||
the input contains a carriage return**. Without it your text sits on the prompt
|
||||
unsubmitted, which is the single most common "the wait endpoints don't work"
|
||||
report: the wait runs its full timeout on a turn that never started. With
|
||||
`useMux`, newlines inside the string are kept: the text goes in as one paste and
|
||||
the Enter after it submits all of it, so `"echo A\necho B\r"` runs both commands
|
||||
in a shell. The check that re-presses a stranded Enter cannot reliably recognise
|
||||
a multi-line paste, so a long multi-line prompt to a just-started agent is still
|
||||
safer in a file it is told to read.
|
||||
- **`wait-output`'s `from=now` is not "printed after you asked".** tmux repaints
|
||||
the visible screen on attach, on resize, and on any TUI redraw, and a repaint
|
||||
arrives as ordinary output, so text already on screen can satisfy a fresh wait.
|
||||
|
||||
@@ -51,10 +51,11 @@ or a server restart shifts later runs slightly. That drift is accepted rather th
|
||||
|
||||
## Prompts are single line
|
||||
|
||||
This is the rule people trip over. Programmatic input into an agent session is single line
|
||||
everywhere in Codeman, because the terminal UIs these CLIs use treat a newline as submit. A
|
||||
multi-line prompt would be silently mangled, so it is **rejected** instead: the form refuses
|
||||
it, and a prompt file whose contents are multi-line fails the run with a clear message.
|
||||
This is the rule people trip over. A cron job fires with nobody watching, and the check that
|
||||
re-presses an Enter the agent ignored cannot recognise a multi-line paste in the composer, so
|
||||
a multi-line prompt could sit there unsent. In `paste` mode the newlines would reach the agent
|
||||
as keys. So a multi-line prompt is **rejected**: the form refuses it, and a prompt file whose
|
||||
contents are multi-line fails the run with a clear message.
|
||||
|
||||
For anything longer than a sentence, put the instructions in a file and make the prompt tell
|
||||
the agent to read it:
|
||||
|
||||
@@ -127,11 +127,12 @@ Read these before writing any code. Each one has cost somebody an afternoon.
|
||||
|
||||
1. **Input must end with `\r`.** Enter fires only when the payload contains a carriage
|
||||
return. Without it the text sits unsubmitted on the prompt, the request still succeeds,
|
||||
and a combined wait burns its full timeout on a turn that never started. Embedded
|
||||
newlines are kept: the text goes in as one paste and the Enter after it submits all of
|
||||
it, so `"echo A\necho B\r"` runs both commands in a shell. The check that re-presses a
|
||||
stranded Enter cannot reliably recognise a multi-line paste, so a long multi-line
|
||||
prompt to a just-started agent is still safer in a file it is told to read.
|
||||
and a combined wait burns its full timeout on a turn that never started. With
|
||||
`useMux`, embedded newlines are kept: the text goes in as one paste and the Enter after
|
||||
it submits all of it, so `"echo A\necho B\r"` runs both commands in a shell. The check
|
||||
that re-presses a stranded Enter cannot reliably recognise a multi-line paste, so a
|
||||
long multi-line prompt to a just-started agent is still safer in a file it is told to
|
||||
read.
|
||||
2. **Make input idempotent.** Send a stable `clientId` and a monotonic per-session `seq`. The
|
||||
server deduplicates, so a retry after a dropped connection cannot double-deliver.
|
||||
3. **Auth.** With `CODEMAN_PASSWORD` set, use HTTP Basic or the session cookie. A missing
|
||||
|
||||
@@ -125,9 +125,9 @@ Sending prompts over the API has one rule that catches everyone: **the payload m
|
||||
`\r`** or Enter is never sent. The request still succeeds, the text sits unsubmitted in the
|
||||
composer, and any wait burns its whole timeout on a turn that never started.
|
||||
|
||||
Embedded newlines are kept: multi-line input goes in as one paste and the Enter after it
|
||||
submits all of it, so `"echo A\necho B\r"` runs both commands in a shell. The check that
|
||||
re-presses a stranded Enter cannot reliably recognise a multi-line paste, so long
|
||||
With `useMux`, embedded newlines are kept: multi-line input goes in as one paste and the
|
||||
Enter after it submits all of it, so `"echo A\necho B\r"` runs both commands in a shell. The
|
||||
check that re-presses a stranded Enter cannot reliably recognise a multi-line paste, so long
|
||||
multi-line content is still safer in a file the agent is told to read.
|
||||
|
||||
See [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent).
|
||||
|
||||
@@ -420,8 +420,9 @@ callers send no body at all.
|
||||
**or Enter is never sent**: the text is typed onto the worker's prompt and sits
|
||||
there unsubmitted. This is [symptom 1](#1-deliveredtrue-then-every-wait-times-out),
|
||||
the number-one silent failure.
|
||||
- Newlines in `input` are kept: the text goes in as one bracketed paste and the `\r`
|
||||
submits all lines. To send a bare Enter (confirm a dialog), send `{"input":"\r"}`.
|
||||
- With `useMux`, newlines in `input` are kept: the text goes in as one bracketed paste
|
||||
and the `\r` submits all lines (without `useMux`, multi-line input is written straight
|
||||
into the pane). To send a bare Enter (confirm a dialog), send `{"input":"\r"}`.
|
||||
- `input` is capped at **65536** characters. ⚠️ **Two caps disagree and the smaller one
|
||||
is the real one**: the Zod schema allows 100000 (`schemas.ts:1035`), so a 65537-to-100000
|
||||
character body passes validation and *then* 400s at the route against
|
||||
|
||||
@@ -303,10 +303,11 @@ duplicate resend costs nothing.
|
||||
Codeman types the text and sends Enter **only when the input contains a carriage
|
||||
return**; without it your command sits unsubmitted on the worker's prompt and
|
||||
everything downstream times out. No response field catches this: `delivered:true`
|
||||
means "written to the pane", **not** "submitted". Newlines are kept: the text goes in
|
||||
as one paste, and the `\r` submits all of it. Build the body with `jq -n` for any prompt you did not
|
||||
author as a literal, because the inline `-d '{"input":"'"$P"'\r"}'` pattern breaks on
|
||||
the first double quote, backslash or `$` in a real prompt:
|
||||
means "written to the pane", **not** "submitted". With `useMux`, newlines are kept: the
|
||||
text goes in as one paste, and the `\r` submits all of it. Build the body with `jq -n`
|
||||
for any prompt you did not author as a literal, because the inline
|
||||
`-d '{"input":"'"$P"'\r"}'` pattern breaks on the first double quote, backslash or `$`
|
||||
in a real prompt:
|
||||
|
||||
```bash
|
||||
BODY=$(jq -n --arg p "$PROMPT" '{input:($p+"\r"),useMux:true,clientId:"agent-1",seq:1,wait:true,waitTimeout:60000}')
|
||||
@@ -587,9 +588,9 @@ allowlist in §4.
|
||||
|
||||
### 5.9 Big input via the workspace
|
||||
|
||||
The composer is a single line capped at 65536 characters with newlines stripped, which
|
||||
makes it a bad channel for a spec, a diff or a file list. The workspace is the good
|
||||
one, and for a local or docker case you are on the same filesystem as the worker.
|
||||
The composer is capped at 65536 characters, and a multi-line paste cannot be confirmed
|
||||
as submitted, which makes it a bad channel for a spec, a diff or a file list. The
|
||||
workspace is the good one, and for a local or docker case you are on the same filesystem as the worker.
|
||||
|
||||
1. Write `TASK.md` into the worker's workspace with your own file tools. The path is
|
||||
`.data.casePath` from `quick-start`, or the `workingDir` you passed to
|
||||
|
||||
@@ -420,8 +420,9 @@ callers send no body at all.
|
||||
**or Enter is never sent**: the text is typed onto the worker's prompt and sits
|
||||
there unsubmitted. This is [symptom 1](#1-deliveredtrue-then-every-wait-times-out),
|
||||
the number-one silent failure.
|
||||
- Newlines in `input` are kept: the text goes in as one bracketed paste and the `\r`
|
||||
submits all lines. To send a bare Enter (confirm a dialog), send `{"input":"\r"}`.
|
||||
- With `useMux`, newlines in `input` are kept: the text goes in as one bracketed paste
|
||||
and the `\r` submits all lines (without `useMux`, multi-line input is written straight
|
||||
into the pane). To send a bare Enter (confirm a dialog), send `{"input":"\r"}`.
|
||||
- `input` is capped at **65536** characters. ⚠️ **Two caps disagree and the smaller one
|
||||
is the real one**: the Zod schema allows 100000 (`schemas.ts:1035`), so a 65537-to-100000
|
||||
character body passes validation and *then* 400s at the route against
|
||||
|
||||
@@ -303,10 +303,11 @@ duplicate resend costs nothing.
|
||||
Codeman types the text and sends Enter **only when the input contains a carriage
|
||||
return**; without it your command sits unsubmitted on the worker's prompt and
|
||||
everything downstream times out. No response field catches this: `delivered:true`
|
||||
means "written to the pane", **not** "submitted". Newlines are kept: the text goes in
|
||||
as one paste, and the `\r` submits all of it. Build the body with `jq -n` for any prompt you did not
|
||||
author as a literal, because the inline `-d '{"input":"'"$P"'\r"}'` pattern breaks on
|
||||
the first double quote, backslash or `$` in a real prompt:
|
||||
means "written to the pane", **not** "submitted". With `useMux`, newlines are kept: the
|
||||
text goes in as one paste, and the `\r` submits all of it. Build the body with `jq -n`
|
||||
for any prompt you did not author as a literal, because the inline
|
||||
`-d '{"input":"'"$P"'\r"}'` pattern breaks on the first double quote, backslash or `$`
|
||||
in a real prompt:
|
||||
|
||||
```bash
|
||||
BODY=$(jq -n --arg p "$PROMPT" '{input:($p+"\r"),useMux:true,clientId:"agent-1",seq:1,wait:true,waitTimeout:60000}')
|
||||
@@ -587,9 +588,9 @@ allowlist in §4.
|
||||
|
||||
### 5.9 Big input via the workspace
|
||||
|
||||
The composer is a single line capped at 65536 characters with newlines stripped, which
|
||||
makes it a bad channel for a spec, a diff or a file list. The workspace is the good
|
||||
one, and for a local or docker case you are on the same filesystem as the worker.
|
||||
The composer is capped at 65536 characters, and a multi-line paste cannot be confirmed
|
||||
as submitted, which makes it a bad channel for a spec, a diff or a file list. The
|
||||
workspace is the good one, and for a local or docker case you are on the same filesystem as the worker.
|
||||
|
||||
1. Write `TASK.md` into the worker's workspace with your own file tools. The path is
|
||||
`.data.casePath` from `quick-start`, or the `workingDir` you passed to
|
||||
|
||||
@@ -97,7 +97,7 @@ const CRON_PSEUDO_FS_TREES: readonly string[] = ['/proc', '/sys', '/dev'];
|
||||
/** Sync blocklist for the create/update workingDir gate (no settings extras). */
|
||||
const CRON_WORKING_DIR_BLOCKED_TREES: readonly string[] = [...DEFAULT_BLOCKED_TREES, ...CRON_PSEUDO_FS_TREES];
|
||||
|
||||
/** Prompt delivery is single-line only (writeViaMux/Ink constraint). */
|
||||
/** Prompt delivery is single-line only: the submit check cannot recognise a multi-line paste. */
|
||||
const HAS_NEWLINE = /[\r\n]/;
|
||||
|
||||
/** The three session calls prompt delivery needs, so it can be tested without a PTY. */
|
||||
|
||||
@@ -2829,7 +2829,8 @@ export class RespawnController extends EventEmitter {
|
||||
let updatePrompt = this.config.updatePrompt;
|
||||
|
||||
if (statusBlock?.recommendation) {
|
||||
// Append RECOMMENDATION to the update prompt (single-line — writeViaMux breaks on newlines)
|
||||
// Append RECOMMENDATION to the update prompt (single-line: the submit check cannot
|
||||
// recognise a multi-line paste in the composer)
|
||||
const rec = statusBlock.recommendation.replace(/\n/g, ' ').substring(0, 200);
|
||||
updatePrompt = `${this.config.updatePrompt} (Claude's last recommendation: ${rec})`;
|
||||
this.logAction('ralph', `Using RECOMMENDATION: ${rec.substring(0, 50)}...`);
|
||||
|
||||
+1
-1
@@ -1905,7 +1905,7 @@ export const ScheduledRunSchema = z.object({
|
||||
/** 'HH:MM' 24-hour time. */
|
||||
const hhmmSchema = z.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, 'Time must be HH:MM (24-hour)');
|
||||
|
||||
/** Prompt delivery is single-line only (writeViaMux/Ink constraint) — reject newlines outright. */
|
||||
/** Prompt delivery is single-line only (the submit check cannot see a multi-line paste) — reject newlines outright. */
|
||||
const noNewlines = (v: string) => !/[\r\n]/.test(v);
|
||||
|
||||
/** Shared field shape for creating/updating a scheduled job. */
|
||||
|
||||
Reference in new issue
Block a user