8000 First-boot polish: day-one first message, focus-events, --model (#35, #36) by simon-inkie · Pull Request #61 · 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
88 changes: 88 additions & 0 deletions .specs/35-36-first-boot-polish/SPEC.md
< 8000 td class="blob-code blob-code-addition js-file-line"> 5. Nits: `.model` validated in both launchers (`agent_model_flag`, C9);
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# First-boot polish (#35, #36)

## TL;DR

A new Claude agent now gets a standard first message on its first launch, so
day-one persona setup no longer depends on what the user types first (#35).
Panes no longer show the tmux focus-events hint, and `create-agent.sh --model`
makes the agent's model an explicit, documented choice (#36).

## Scope

- `claude-session.sh`: `claude_first_boot_prompt`, `agent_model_flag`.
- `boot-agents.sh`, `workspace.sh`: append it to the claude launch command; set
tmux `focus-events on` before any pane starts.
- `create-agent.sh`: `--model <id>` writes `.model`.
- `INSTALL.md`: model cost, first message, focus-events.

## Acceptance

- A fresh agent starts its day-one steps without the user asking, once.
- No focus-events hint on a new pane.
- `create-agent.sh --model` reaches the launch command.

## Test plan

- `boot-agents.test.sh`: C8 (prompt only on a new session, never after a
conversation exists, repeated if no message was recorded); a full-boot case
checking one send, `--session-id`, `--model`, and focus-events ordering.
- `create-agent.test.ts`: `.model` written only when asked; unsafe ids refused.

## Decisions log

- Trigger is claude's positional initial prompt on the `--session-id` branch,
the same branch #23 uses for a new pinned session. That branch alone is not
"once": a pruned transcript or a moved config dir also lands there. So the
message is sent only when the branch is taken, `.first-boot-done` is absent
(written at launch) and `IDENTITY.md` is still the scaffold or missing.
- Limit: the marker is written at launch, not when claude records the message.
A launch that dies first does not retry on its own; delete the marker. This
was chosen over repeating, which risked re-running day one on an established
agent.
- Existing agents with a conversation, or a written `IDENTITY.md`, are untouched.
- A first-boot agent is not sent "arm your monitor" (it is mid first turn);
it prints a note. Arming only happens on a relaunch (a running agent is
skipped), so the user exits the runtime and runs boot-agents.sh again.
- A busy composer after a first boot is treated as ready, as the agent is
working on its first message. Any other readiness failure still reports.
- focus-events is a tmux server option with no per-session form, so it is set
globally, as the scripts already do for mouse. Documented in INSTALL.md.
- `--model` accepts plain ids only, because launchers put `.model` unquoted on
a shell command line. The launchers re-validate (`agent_model_flag`), since
the file can be hand-edited.
- The `create-agent.sh` verification probe uses the chosen model too.

## Follow-ups

- Codex agents get no first message; codex has no equivalent pinned-session path.
- Optional in #35: collect name, pronouns and time zone at install. Not done.
- The unpinned fallback launch (pin cannot be written) sends no first message.

## Review feedback

Opus review of PR 61, round 1 (no blockers):

1. Should-fix: "exactly once" held only while the `--session-id` branch was
taken once; a pruned transcript sent an established agent day one again.
Fixed: `.first-boot-done` marker plus an `IDENTITY.md`-is-scaffold check;
limit documented here and in INSTALL.md. Tests C8.
2. Should-fix: first-boot agents with `.auto-arm-watcher` were sent the arm
prompt mid first turn. Fixed: skipped with a note; fixtures no longer delete
the marker for first-boot, and assert the arm prompt is never typed.
3. Should-fix: test comment claimed a second boot the fixture did not run. Fixed:
added a `first-boot-again` full-boot fixture (resume, no message, arms).
4. Should-fix: opt-out expectation loosened without reason. Restored to the
original label.
focus-events override documented in INSTALL.md; INSTALL.md grammar fixed.

Round 2 (re-review at eb23583, no blockers): one docs should-fix. "Restart it" /
"the next boot arms it" was wrong, since boot-agents.sh skips a running agent.
Reworded in INSTALL.md, the boot-agents.sh note and this SPEC to "exit the
runtime, then run boot-agents.sh again". Nits not taken: a stderr pointer to
`.first-boot-done` on a failed launch, and the workspace.sh marker left behind by
a failed send (same documented trade-off; delete the marker to resend).

Round 3 (maintainer review comment): `agent_model_flag` stripped all whitespace, so
`claude sonnet` became `claudesonnet` and passed. Now takes the first line and
trims the ends only, so an interior space is refused; tests added (C9).
27 changes: 27 additions & 0 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,15 @@ packages/base/bin/create-agent.sh inkie --role "keeps the notes"
`inkie` is only an example: any lowercase name works (letters, digits and
hyphens).

**Choose a model, because it is a cost decision.** Without `--model <id>` the
agent uses your model CLI's own default, which on a paid plan can be a more
expensive model, and several always-on agents add up. Pass
`--model <id>` (for example `--model claude-sonnet-5-5`) to write the agent's
`.model` file; `boot-agents.sh` and `workspace.sh` launch the runtime with
`--model <id>` from it. You can also edit `$AGENTS_HOME/<name>/.model` by
hand at any time. It must be a plain id (letters, digits, dots, colons and
hyphens); the launchers ignore anything else and say so.

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
Expand Down Expand Up @@ -520,6 +529,24 @@ again and an agent whose pane already has its runtime running in it is left
alone; one whose runtime has exited is relaunched, which is what makes this
safe to fire on boot.

On an agent's first launch, `boot-agents.sh` starts a new session and gives it
a first message: do your day-one steps from your persona files, then say hello.
Expect it to fill in `IDENTITY.md` and `SOUL.md`, and it may ask you questions
about itself. The message is sent once per agent: the launcher leaves a
`.first-boot-done` file in the agent's home, and an agent whose `IDENTITY.md`
is already written never gets it. If a launch dies before the agent has
recorded the message, delete `.first-boot-done` to send it again. An agent
armed with `.auto-arm-watcher` is not told to arm its monitor on that first
boot, because it is busy with day one. Once its first turn is done, exit the
agent's runtime and run `boot-agents.sh` again to relaunch and arm it. (Running
it while the runtime is still up leaves the agent alone and arms nothing.)

`boot-agents.sh` and `workspace.sh` also run `tmux set -g focus-events on`
before starting any pane, which stops Claude Code showing its focus-events
hint. It is a tmux server option with no per-session form, so it applies to
the whole tmux server, including any other sessions on it. Add
`tmux set -g focus-events off` after a boot if you want it off.

On first boot, attach to the session and answer any runtime setup prompts
manually. Folder trust defaults to No: do not press Enter while No is
preselected. Choose Yes manually only if you trust the folder. Claude Code
Expand Down
33 changes: 29 additions & 4 deletions packages/base/bin/boot-agents.sh
Original file line number Diff line number Diff line change
Expand Up @@ -626,6 +626,16 @@ existing_readiness() {
return 0
}

# A first boot is launched with its first message, so a busy composer is the
# expected state, not a fault. Anything else wait_for_readiness reports still is.
first_boot_readiness() {
local reason
reason=$(wait_for_readiness "$@") && return 0
[[ "$reason" == "runtime busy" ]] && return 0
printf '%s\n' "$reason"
return 1
}

wait_for_readiness() {
local target="$1" runtime="$2" reason="unconfirmed" attempt pane prompt
local budget="${BOOT_READY_SECS:-45}"
Expand Down Expand Up @@ -697,6 +707,10 @@ if [[ "${BOOT_AGENTS_LIB_ONLY:-0}" == "1" ]]; then
fi

tmux start-server 2>/dev/null || true
# Turn on focus-events before any pane starts, so Claude Code does not show its
# "tmux focus-events off" hint. tmux has no per-session form of this option
# (it is a server option), so it applies to the tmux server these scripts use.
tmux set -g focus-events on 2>/dev/null || true
if ! tmux has-session -t "$SESSION" 2>/dev/null; then
tmux new-session -d -s "$SESSION" -n "${AGENTS[0]}" -c "$AGENTS_HOME/${AGENTS[0]}" || { echo "boot-agents: session creation failed" >&2; exit 1; }
fi
Expand All @@ -712,7 +726,7 @@ launch_agent() {
runtime=$(get_runtime "$a")
# Per-agent model override (selector): $AGENTS_HOME/<a>/.model -> --model flag.
# Absent = no flag = inherit the global default. Applies to all runtimes.
[[ -f "$AGENTS_HOME/$a/.model" ]] && model_flag="--model $(cat "$AGENTS_HOME/$a/.model")"
model_flag="$(agent_model_flag "$AGENTS_HOME/$a")"
if ! tmux list-windows -t "$SESSION" -F '#{window_name}' | grep -qx "$a"; then
tmux new-window -t "$SESSION" -n "$a" -c "$AGENTS_HOME/$a" >/dev/null || return 1
fi
Expand All @@ -736,7 +750,11 @@ launch_agent() {
echo "boot-agents: could not pin a session id for $a; launching an unpinned session" >&2
session_args="-n $(printf '%q' "$a")"
}
tmux send-keys -t "$target" "printf '\033]0;${a}\007'; [ -f $AGENTS_HOME/$a/.env.secrets ] && . $AGENTS_HOME/$a/.env.secrets; claude $session_args $model_flag" Enter || return 1
local first_prompt
first_prompt="$(claude_first_boot_prompt "$session_args" "$AGENTS_HOME/$a")"
tmux send-keys -t "$target" "printf '\033]0;${a}\007'; [ -f $AGENTS_HOME/$a/.env.secrets ] && . $AGENTS_HOME/$a/.env.secrets; claude $session_args $model_flag $first_prompt" Enter || return 1
# The first message is already on its way, so the pane may be busy at once.
[[ -n "$first_prompt" ]] && { echo "launched:first-boot"; return; }
elif [[ "$runtime" == "codex" ]]; then
# codex (Codex CLI runtime). AGENT_NAME/AGENT_ROLE must
# be REAL OS-level env vars set before the codex process starts.
Expand Down Expand Up @@ -785,9 +803,16 @@ for a in "${AGENTS[@]}"; do
if outcome=$(launch_agent "$a"); then
readiness_check=wait_for_readiness
[[ "$outcome" == skipped ]] && readiness_check=existing_readiness
[[ "$outcome" == launched:first-boot ]] && readiness_check=first_boot_readiness
if reason=$("$readiness_check" "$SESSION:$a" "$(get_runtime "$a")"); then
if [[ "$outcome" == "launched" ]]; then
FRESH+=("$a")
if [[ "$outcome" == launched* ]]; then
if [[ "$outcome" == launched:first-boot ]]; then
# Typing "arm your monitor" into a pane busy with its first turn
# would queue it behind day-one setup, so leave it to the next boot.
[[ -f "$AGENTS_HOME/$a/.auto-arm-watcher" ]] && echo "boot-agents: $a monitor not armed on its first boot; after its first turn, exit its runtime and run boot-agents.sh again to arm it" >&2
else
FRESH+=("$a")
fi
LAUNCHED=$((LAUNCHED + 1))
echo "boot-agents: $a launched, ready"
[[ "$STAGGER_SECS" -gt 0 ]] && sleep "$STAGGER_SECS"
Expand Down
55 changes: 55 additions & 0 deletions packages/base/bin/claude-session.sh
Original file line number Diff line number Diff line change
Expand Up @@ -136,3 +136,58 @@ claude_session_args() {
printf '%s\n' "$id" > "$pin" || return 1
printf -- '--session-id %s -n %q\n' "$id" "$a"
}

# claude_first_boot_prompt <session_args> <agent_home> -- print the first message
# to launch the agent with, shell-quoted and ready to append to the claude
# command line, when day one has plausibly not happened. Prints nothing
# otherwise.
#
# WHY. Whether a new agent did its day-one persona work used to depend on what
# the user's first message said: "hello" got it, a test ping did not. Passing
# the message as claude's initial prompt makes the first launch do it, with no
# typing into the pane.
#
# WHEN. All three must hold:
# 1. <session_args> (from claude_session_args) start a new session
# (`--session-id`), so a resume never gets it.
# 2. <agent_home>/.first-boot-done does not exist. It is written here, as the
# message is handed to the launcher, so the message goes out once per
# agent. A pinned transcript that was later pruned (Claude Code expires old
# ones) or a moved CLAUDE_CONFIG_DIR takes the `--session-id` branch again,
# and the marker is what stops an established agent being told it is new.
# 3. IDENTITY.md is still the scaffold (it still carries the "self-author on
# day one" placeholder) or is missing. An agent created before this marker
# existed, whose persona is already written, is therefore left alone too.
#
# LIMIT. The marker is written at launch, not when the message is recorded. If
# the launch dies before claude records the message, day one is not retried
# automatically: delete .first-boot-done to send it again.
claude_first_boot_prompt() {
local args="$1" home="$2"
[[ "$args" == "--session-id "* ]] || return 0
[[ -e "$home/.first-boot-done" ]] && return 0
if [[ -f "$home/IDENTITY.md" ]] && ! grep -qi 'self-author on day one' "$home/IDENTITY.md" 2>/dev/null; then
return 0
fi
: > "$home/.first-boot-done" 2>/dev/null || return 0
printf '%q\n' "This is your first session. Do your day-one steps from your persona files (IDENTITY.md and SOUL.md), then say hello."
}

# agent_model_flag <agent_home> -- print `--model <id>` from <agent_home>/.model,
# or nothing when there is no file. The launchers put the flag on a shell
# command line un 10000 quoted, and .model is a plain file people edit by hand, so an
# id with anything but letters, digits, dots, colons and hyphens is refused with
# a warning instead of being run.
agent_model_flag() {
local file="$1/.model" id
[[ -f "$file" ]] || return 0
# First line only, ends trimmed: an interior space must stay in the id so the
# check below rejects it, rather than being squeezed into a different id.
id="$(head -n 1 "$file" 2>/dev/null | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
[[ -n "$id" ]] || return 0
if [[ "$id" =~ ^[A-Za-z0-9][A-Za-z0-9._:-]*$ ]]; then
printf -- '--model %s\n' "$id"
else
echo "claude-session: ignoring $file: '$id' is not a plain model id" >&2
fi
}
28 changes: 25 additions & 3 deletions packages/base/bin/create-agent.sh
10BC8
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,16 @@
#
# Usage:
# bin/create-agent.sh <name> [--role "<tagline>"] [--runtime <runtime>]
# [--verify | --no-verify] [--inbox-root <path>]
# [--model <id>] [--verify | --no-verify]
# [--inbox-root <path>]
# [--agents-home <path>] [--no-install-path]
# bin/create-agent.sh --verify-only <name>
# bin/create-agent.sh # interactive, prompts for a name
#
# --model <id> write <agent home>/.model, which boot-agents.sh
# and workspace.sh pass as `--model <id>`. Without
# it the agent uses the runtime's own default,
# which may be a costlier model on a paid plan.
# --no-install-path skip the $HOME/.local/bin/inbox symlink that
# makes `inbox` resolve as a bare command name.
#
Expand Down Expand Up @@ -408,12 +413,14 @@ VERIFY_ONLY=0
INBOX_ROOT_ARG=""
AGENTS_HOME_ARG=""
INSTALL_PATH=1
MODEL=""

while [[ $# -gt 0 ]]; do
case "$1" in
-h|--help) usage; exit 0 ;;
--role) [[ $# -ge 2 ]] || die_scaffold "--role needs a value"; ROLE="$2"; shift 2 ;;
--runtime) [[ $# -ge 2 ]] || die_scaffold "--runtime needs a value"; RUNTIME="$2"; shift 2 ;;
--model) [[ $# -ge 2 ]] || die_scaffold "--model needs a value"; MODEL="$2"; shift 2 ;;
--inbox-root) [[ $# -ge 2 ]] || die_scaffold "--inbox-root needs a value"; INBOX_ROOT_ARG="$2"; shift 2 ;;
--agents-home) [[ $# -ge 2 ]] || die_scaffold "--agents-home needs a value"; AGENTS_HOME_ARG="$2"; shift 2 ;;
--no-install-path) INSTALL_PATH=0; shift ;;
Expand Down Expand Up @@ -550,6 +557,15 @@ fi
AGENT_HOME="$AGENTS_HOME/$NAME"
AGENT_INBOX="$INBOX_ROOT/$NAME/inbox"

# The launchers put .model on a shell command line unquoted, so only a plain
# model id is accepted.
if [[ -n "$MODEL" && ! "$MODEL" =~ ^[A-Za-z0-9][A-Za-z0-9._:-]*$ ]]; then
die_scaffold "--model '$MODEL' is not a plain model id" \
"use letters, digits, dots, colons and hyphens, for example claude-sonnet-5-5"
fi
MODEL_ARGS=()
[[ -n "$MODEL" ]] && MODEL_ARGS=(--model "$MODEL")

# ---------------------------------------------------------------------------
# create
# ---------------------------------------------------------------------------
Expand Down Expand Up @@ -623,6 +639,11 @@ else
printf '%s' "$RUNTIME" > "$AGENT_HOME/.runtime" \
|| die_scaffold "could not write $AGENT_HOME/.runtime"

if [[ -n "$MODEL" ]]; then
printf '%s' "$MODEL" > "$AGENT_HOME/.model" \
|| die_scaffold "could not write $AGENT_HOME/.model"
fi

mkdir -p "$AGENT_HOME/.claude" || die_scaffold "could not create $AGENT_HOME/.claude"
CA_SETTINGS="$AGENT_HOME/.claude/settings.json" CA_NAME="$NAME" CA_ROLE="$ROLE" \
CA_INBOX_ROOT="$INBOX_ROOT" merge_settings \
Expand All @@ -643,6 +664,7 @@ else
say " inbox root $INBOX_ROOT [$INBOX_ROOT_SOURCE]"
say " inbox CLI $PATH_INSTALL_REPORT"
say " runtime $RUNTIME"
say " model ${MODEL:-"(runtime default; see INSTALL.md)"}"
say " boot phrase $NONCE"
say
say " IDENTITY.md and SOUL.md are scaffolded, not written. The agent fills"
Expand Down Expand Up @@ -735,10 +757,10 @@ say " one non-interactive turn, from $AGENT_HOME"
# slug of that directory. A probe run from anywhere else verifies a different
# project and tells you nothing about this agent.
if command -v timeout >/dev/null 2>&1; then
( cd "$AGENT_HOME" && timeout "$PROBE_TIMEOUT" claude -p "$PROBE_PROMPT" ) \
( cd "$AGENT_HOME" && timeout "$PROBE_TIMEOUT" claude ${MODEL_ARGS[@]+"${MODEL_ARGS[@]}"} -p "$PROBE_PROMPT" ) \
>"$PROBE_OUT" 2>"$PROBE_ERR"
else
( cd "$AGENT_HOME" && claude -p "$PROBE_PROMPT" ) >"$PROBE_OUT" 2>"$PROBE_ERR"
( cd "$AGENT_HOME" && claude ${MODEL_ARGS[@]+"${MODEL_ARGS[@]}"} -p "$PROBE_PROMPT" ) >"$PROBE_OUT" 2>"$PROBE_ERR"
fi
PROBE_STATUS=$?

Expand Down
7 changes: 5 additions & 2 deletions packages/base/bin/workspace.sh
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ start_agent() {
runtime=$(get_runtime "$agent")
# Per-agent model override (selector): $AGENTS_HOME/<agent>/.model -> --model.
# Absent = no flag = inherit the global default.
[[ -f "$AGENTS_HOME/$agent/.model" ]] && model_flag="--model $(cat "$AGENTS_HOME/$agent/.model")"
model_flag="$(agent_model_flag "$AGENTS_HOME/$agent")"
if [[ "$runtime" == "claude" ]]; then
# Source the agent's gitignored .env.secrets (if any) before claude, so
# anything referencing a live secret via ${VAR} resolves in that shell.
Expand All @@ -85,7 +85,7 @@ start_agent() {
echo "workspace: could not pin a session id for $agent; launching an unpinned session" >&2
session_args="-n $(printf '%q' "$agent")"
}
tmux send-keys -t "$target" "printf '\\033]0;${agent}\\007'; [ -f $AGENTS_HOME/$agent/.env.secrets ] && . $AGENTS_HOME/$agent/.env.secrets; claude $session_args $model_flag" Enter
tmux send-keys -t "$target" "printf '\\033]0;${agent}\\007'; [ -f $AGENTS_HOME/$agent/.env.secrets ] && . $AGENTS_HOME/$agent/.env.secrets; claude $session_args $model_flag $(claude_first_boot_prompt "$session_args" "$AGENTS_HOME/$agent")" Enter
else
# Any other runtime: launch it plainly and let its own config (hooks,
# AGENT_NAME wiring) do the rest. Add a branch here if a given runtime
Expand All @@ -111,6 +111,9 @@ start_watcher() {
}

# Create the base session if it doesn't exist
# Before any pane starts, so Claude Code shows no "focus-events off" hint.
tmux start-server 2>/dev/null || true
tmux set -g focus-events on 2>/dev/null || true
if ! tmux has-session -t "$SESSION" 2>/dev/null; then
FIRST="${AGENTS[0]}"
tmux new-session -d -s "$SESSION" -n "$FIRST" -c "$AGENTS_HOME/$FIRST"
Expand Down
Loading
Loading
0