8000 Rename the walkthrough's first agent from wren to inkie (#34) by simon-inkie · Pull Request #52 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions .specs/34-walkthrough-inkie/SPEC.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# #34: Rename the walkthrough's first agent from wren to inkie

- Issue: #34
- Branch: 34-walkthrough-inkie-5dvzjd
- Started: 2026-10-07

## TL;DR

The walkthrough's first example agent is now `inkie` instead of `wren`, in the
docs, the usage examples in two scripts, and the install-verification rig's
agent-install stage (which asserts the tmux window name and the reply sender).
`INSTALL.md` gains a line saying any lowercase name works.

## Scope

In scope:
- `INSTALL.md`, `packages/base/README.md`.
- Usage comments in `packages/base/bin/boot-agents.sh` and
`packages/base/bin/workspace.sh`.
- `rig/stages/08-install-agents.mjs`, in the same commit as the docs, because
the rig runs the documented commands and asserts the window name.
- One line in `INSTALL.md` noting that any lowercase name works.

Out of scope:
- Test fixtures (`packages/base/test/*`), which keep `wren` on purpose.
- `packages/base/ROSTER.md` (see Follow-ups).

## Acceptance

- A case-sensitive search for `wren` outside `packages/base/test/` finds
nothing.
- The install-verification rig stays green.
- `pnpm typecheck`, `pnpm test` and the check scripts pass.

## Test plan

- `rg wren` shows hits only under `packages/base/test/`, plus the ROSTER entry
noted below.
- Run the repo's checks: `pnpm install --frozen-lockfile`, `pnpm typecheck`,
`pnpm test`, `pnpm check:boundaries`, `pnpm check:leaks`,
`pnpm check:licence`, `pnpm check:lib-version`,
`pnpm -C packages/deck check:dashes`.
- Run the rig self-test if it can run here.

## Decisions log

- Replaced the whole word `wren` with `inkie` mechanically, so the doc, the
scripts and the rig cannot disagree. The `boot-agents.sh` comment about
resuming sessions now reads "inkie" and "inkie-scratch".
- Worded the note as "`inkie` is only an example: any lowercase name works",
matching the name rule in `create-agent.sh` (lowercase letters, digits,
hyphens).
- Left `ROSTER.md` alone. Its `**Wren**` entry is a separate fictional
teammate in a worked roster example, not the walkthrough agent, and the
issue does not list that file.

## Follow-ups

- `packages/base/ROSTER.md` still has a fictional "Wren" persona. Rename it if
the acceptance search is meant to be case-insensitive.

## Results

- `pnpm typecheck`, `check:boundaries`, `check:leaks`, `check:licence`,
`check:lib-version` and `check:dashes` pass. `rig --self-test` passes.
- `pnpm test`: four failures in `packages/base`, identical on `main` before
this change (`create-agent` "no runtime on PATH", `inbox.test.sh`,
`inbox-push.test.sh`, `pane-idle.test.sh`). Not caused by this change.
- The full rig run needs a docker daemon, which this environment lacks, so the
stage 08 change is unexecuted here. CI or a local run should confirm it.
33 changes: 18 additions & 15 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -414,28 +414,31 @@ you get an agent your launcher can see and Deck cannot.
```sh
export AGENTS_HOME=$HOME/agents
export INBOX_ROOT=$HOME/deck/inbox
packages/base/bin/create-agent.sh wren --role "keeps the notes"
packages/base/bin/create-agent.sh inkie --role "keeps the notes"
```

`inkie` is only an example: any lowercase name works (letters, digits and
hyphens).

That writes both, links the `inbox` CLI onto your `PATH`, and then tries to
prove the persona actually reached the model by asking the agent, in one
non-interactive turn, for a boot phrase that exists nowhere but its own
identity file. **With no model CLI installed, that last step cannot run**, and
the script says so and exits 4:

```text
create-agent: CREATED wren
persona files /home/you/agents/wren
inbox /home/you/deck/inbox/wren/inbox
create-agent: CREATED inkie
persona files /home/you/agents/inkie
inbox /home/you/deck/inbox/inkie/inbox
boot phrase boot-6ed9a08da2961594

create-agent: CANNOT VERIFY wren
create-agent: CANNOT VERIFY inkie
No `claude` on PATH, so there was nothing to ask.
```

Exit 4 means created but unproven, and it is not a pass. Once you have a model
CLI installed and signed in, `packages/base/bin/create-agent.sh --verify-only
wren` re-runs only the proof. It exits 0 only if the phrase comes back, which
inkie` re-runs only the proof. It exits 0 only if the phrase comes back, which
is a stronger statement than any check of the files: a persona that never
reached the model leaves behind exactly the same directory tree as one that
did.
Expand All @@ -460,28 +463,28 @@ tmux list-windows -t agents -F '#{window_name}'
```

```text
wren
inkie
```

The window is real whether or not a model CLI is installed. With none, the
pane holds the shell and the error, which is exactly what you should see at
this point on a machine with no subscription:

```sh
tmux capture-pane -t agents:wren -p | grep -v '^$' | tail -5
tmux capture-pane -t agents:inkie -p | grep -v '^$' | tail -5
```

```text
you@host:~/agents/wren$ printf '\033]0;wren\007'; [ -f /home/you/agents/wren/.env.secrets ] && . /home/you/agents/wren/.env.secrets; claude --session-id 0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d -n wren
you@host:~/agents/inkie$ printf '\033]0;inkie\007'; [ -f /home/you/agents/inkie/.env.secrets ] && . /home/you/agents/inkie/.env.secrets; claude --session-id 0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d -n inkie
-bash: claude: command not found
you@host:~/agents/wren$
you@host:~/agents/inkie$
```

(The blank lines are dropped because a tmux pane is padded to its full height,
and `tail` on the raw capture returns the padding rather than the text.)

Deck reads that pane live. Open the agent's thread and switch to the terminal
view, or `curl -sS "http://localhost:4242/threads/wren?view=tmux"`, and the
view, or `curl -sS "http://localhost:4242/threads/inkie?view=tmux"`, and the
contents of the pane are in the page. That is the one check in this area worth
trusting. Deck's tmux surface is switched on by an environment variable that
defaults to on and never looks for the binary, so the terminal view being
Expand All @@ -494,7 +497,7 @@ From the browser, open the agent's thread and type. Without a browser, this is
the same request the interface makes:

```sh
curl -sS -X POST http://localhost:4242/threads/wren \
curl -sS -X POST http://localhost:4242/threads/inkie \
--data-urlencode 'intent=compose' \
--data-urlencode 'body=Welcome aboard. What do you make of the protocol doc?' \
-o /dev/null -w '%{http_code}\n'
Expand All @@ -504,12 +507,12 @@ curl -sS -X POST http://localhost:4242/threads/wren \
200
```

That writes a block into `$INBOX_ROOT/wren/inbox/<your MC_USER>.md`. An agent
That writes a block into `$INBOX_ROOT/inkie/inbox/<your MC_USER>.md`. An agent
reads and answers with the `inbox` CLI, which is the half of the protocol that
lives in the terminal, where the agent is. Standing in for the agent by hand:

```sh
export AGENT_NAME=wren
export AGENT_NAME=inkie
export INBOX_ROOT=$HOME/deck/inbox
ME=$(sed -n 's/^MC_USER=//p' packages/deck/.env | tail -1)
: "${ME:?is empty. No MC_USER in packages/deck/.env; set it in tier 2 first.}"
Expand Down Expand Up @@ -558,7 +561,7 @@ guess it is willing to make.
The reply is now in the thread, which you can see from Deck:

```sh
curl -sS http://localhost:4242/threads/wren | grep -c 'the whole protocol'
curl -sS http://localhost:4242/threads/inkie | grep -c 'the whole protocol'
```

### What is still missing, and it is the important part
Expand Down
8 changes: 4 additions & 4 deletions packages/base/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ It needs python3, and two environment variables, both required with no
defaults:

```bash
export AGENT_NAME=wren # who you are
export AGENT_NAME=inkie # who you are
export INBOX_ROOT=/path/to/inboxes # absolute path, no tilde

packages/base/bin/inbox unread
Expand Down Expand Up @@ -139,8 +139,8 @@ export ACTIVITY_ROOT=~/.the-vault/activity

packages/base/bin/activity-sweep.sh # produce (put this on a timer)
packages/base/bin/activity status --all # every agent, one line each
packages/base/bin/activity status wren # one agent, in detail
packages/base/bin/activity pin wren ~/repos/site # override the worktree guess
packages/base/bin/activity status inkie # one agent, in detail
packages/base/bin/activity pin inkie ~/repos/site # override the worktree guess
```

Every output leads with how old the data is, and says so loudly past
Expand Down Expand Up @@ -239,7 +239,7 @@ git clone <this-repo-url>

# Starting a new agent from scratch:
AGENTS_HOME=/path/to/agents INBOX_ROOT=/path/to/inboxes \
packages/base/bin/create-agent.sh wren --role "keeps the notes"
packages/base/bin/create-agent.sh inkie --role "keeps the notes"
```

That writes the persona files, the inbox, and the runtime settings (including
Expand Down
4 changes: 2 additions & 2 deletions packages/base/bin/boot-agents.sh
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
# Usage:
# bin/boot-agents.sh # resume + arm all agents, stay headless
# bin/boot-agents.sh --attach # same, then attach to the session
# bin/boot-agents.sh wren basalt # only the named agents
# bin/boot-agents.sh inkie basalt # only the named agents
#
# After a headless run, view the agents with: tmux attach -t agents
#
Expand Down Expand Up @@ -137,7 +137,7 @@ get_runtime() {
# session, which are not the conversation anyone wants resumed.
# - cwd == "$AGENTS_HOME/<agent>", matched THROUGH the closing quote, so a
# shorter agent name can never match a longer one that starts with it
# (agent "wren" must not resume a session belonging to "wren-scratch").
# (agent "inkie" must not resume a session belonging to "inkie-scratch").
#
# The id comes from the parsed payload, not from string-stripping the filename,
# so a change to Codex's filename format cannot quietly start yielding wrong
Expand Down
4 changes: 2 additions & 2 deletions packages/base/bin/workspace.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
# Launch the agent workspace: one tmux window per agent, ready to go.
# Usage: bin/workspace.sh [--windowed] [agent1 agent2 ...]
# No args = all agents. Pass names to launch a subset.
# bin/workspace.sh wren basalt # tmux windows in current terminal
# bin/workspace.sh --windowed wren basalt # spawn each in its own Windows Terminal
# bin/workspace.sh inkie basalt # tmux windows in current terminal
# bin/workspace.sh --windowed inkie basalt # spawn each in its own Windows Terminal
# bin/workspace.sh # everyone, current terminal
#
# Assumes the persona layout from templates/: each agent's home is
Expand Down
4 changes: 2 additions & 2 deletions rig/stages/08-install-agents.mjs
Original fi 8DF9 le line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ import { selectInDocumentOrder } from "../lib/fenced.mjs";
import { execIn, fetchOutside, removeContainer, runBlocks, startContainer, waitForHttp } from "../lib/docrun.mjs";
import { EXPECTED_EXITS, LONG_RUNNING, RUNS } from "../install-plan.mjs";

const AGENT = "wren";
const AGENT = "inkie";
/** The reply the document's own block sends, which must survive the round trip. */
const REPLY_MARKER = "the whole protocol";
/** The block that stands in for the agent, and the one this tier's fresh-terminal control re-runs. */
Expand Down Expand Up @@ -249,7 +249,7 @@ export default {
ok:
section("THREAD").includes(REPLY_MARKER) &&
/from: \S+ - status: read/.test(section("THREAD")) &&
/from: wren - status: \S+ - subject: re: welcome/.test(section("THREAD")),
/from: inkie - status: \S+ - subject: re: welcome/.test(section("THREAD")),
detail: oneLine(section("THREAD")),
}),
probe({
Expand Down
Loading
0