@gobius/t3ctl 0.3.0 → 0.4.0

package/README.md

@@ -156,7 +156,7 @@ t3ctl project create t3ctl ~/Code/t3ctl
 ### `t3ctl thread create <project> <title>`
 
 Create a thread. This produces an **idle thread with no messages** — it does not
-start the agent. Use `thread start` for that.
+start the agent. Use `thread send` for that.
 
 ```sh
 t3ctl thread create t3ctl "rewrite the readme for users" --branch docs/readme
@@ -176,13 +176,15 @@ Flags:
 `--model` splits on the **first** slash, so slashed model names work as-is:
 `--model opencode/github-copilot/gpt-5.4`.
 
-### `t3ctl thread start <thread> <message...>`
+### `t3ctl thread send <thread> <message...>`
 
-Send a message and run the agent. Everything after the thread reference is the
+Send a message to a thread and run the agent. This is how you continue a
+conversation — it is the same thing the app does for every message you type,
+first or fiftieth. Aliased as `thread start`, the name it shipped under in 0.2.0. Everything after the thread reference is the
 message — no quoting needed.
 
 ```sh
-t3ctl thread start "rewrite the readme" move the endpoint tables into CONTRIBUTING.md
+t3ctl thread send "rewrite the readme" move the endpoint tables into CONTRIBUTING.md
 ```
 
 ```
@@ -195,13 +197,42 @@ started rewrite the readme for users
 
 Accepts `--model`, `--runtime-mode`, `--interaction-mode`, and `--host`. Unlike
 `thread create`, `--model` has no default here: the thread's existing model is
-reused unless you override it. Use `--interaction-mode plan` to make the agent
-plan instead of edit:
+reused unless you override it.
+
+### `t3ctl thread rename <thread> <new title...>`
+
+Rename a thread. Useful when a thread was created from a script and ended up with
+a title like a filename.
+
+```sh
+t3ctl thread rename "probe well-known" Verify hosts with the environment descriptor
+```
+
+### `t3ctl thread retitle <thread> [--timeout <seconds>]`
+
+Ask the server to derive a title from the thread's own content, instead of
+supplying one.
 
 ```sh
-t3ctl thread start "flaky release workflow" --interaction-mode plan why does the tag job race?
+t3ctl thread retitle "probe well-known"
+```
+
+This is a **request, not a guarantee**. The server records the intent and expects
+something downstream to generate the title; in practice it sometimes clears the
+request a few seconds later without producing one, and reports no error when it
+does. So `retitle` watches the thread afterwards and tells you which happened:
+
+```
+asked the server to retitle Build t3ctl: a CLI for controlling T3 Code hosts  (seq 677390)
+no title was generated — the server cleared the request without producing one.
+  The title is still "Build t3ctl: a CLI for controlling T3 Code hosts". Set one directly:
+    t3ctl thread rename 861645a3-... <title...>
 ```
 
+It exits non-zero when no title appears, so a script can tell. Waits 30s by
+default; `--timeout` changes that. If you need the rename to be certain, use
+`thread rename`, which sets the title directly.
+
 ### `t3ctl thread interrupt <thread>`
 
 Stop the turn that's currently running.
@@ -249,7 +280,7 @@ Write commands act on one host. With a single host registered, that one is
 implied. With more than one, pass `--host`:
 
 ```sh
-t3ctl thread start --host desktop "api rate limits" pick this back up
+t3ctl thread send --host desktop "api rate limits" pick this back up
 ```
 
 Otherwise you get `multiple hosts; pass --host <laptop|desktop>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobius/t3ctl",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Controller CLI for T3 Code hosts — list and drive threads across machines",
   "keywords": [

package/t3ctl.mjs

@@ -364,15 +364,88 @@ const cmdProject = async (args) => {
   console.log(`created project ${bold(title)} on ${host.name}\n  id   ${projectId}\n  root ${workspaceRoot}\n  seq  ${sequence}`);
 };
 
+
+// thread.meta.update also accepts regenerateTitle:true, which asks the server to
+// derive a title from the thread's own content instead of taking one from us.
+const cmdThreadRename = async (thread, host, title) => {
+  const { sequence } = await dispatch(host, {
+    type: 'thread.meta.update', commandId: crypto.randomUUID(), threadId: thread.id, title,
+  });
+  console.log(`renamed ${dim(thread.title || thread.id)} -> ${bold(title)}\n  seq ${sequence}`);
+};
+
+// Lighter than the full snapshot; retitle polls this so it does not refetch every
+// thread's history once a second.
+const threadDetail = async (host, threadId) => {
+  const res = await fetch(`${host.origin}/api/orchestration/threads/${threadId}?turnLimit=1`, {
+    headers: { authorization: `Bearer ${host.token}` },
+    signal: AbortSignal.timeout(host.timeoutMs ?? 15000),
+  });
+  if (!res.ok) throw new Error(`${host.name}: HTTP ${res.status}`);
+  return (await res.json()).thread;
+};
+
+// `regenerateTitle` does NOT rename anything by itself. The server records an
+// intent marker (`titleRegeneration: {requestId, startedAt}`) and expects something
+// downstream to generate a title and write it back. Observed on a live server: the
+// marker is sometimes cleared a few seconds later with the title untouched, and no
+// error is reported anywhere — not in the event, the command receipt, or the server
+// trace. So we dispatch, then watch, and say what actually happened.
+const cmdThreadRetitle = async (thread, host, timeoutSeconds) => {
+  const before = thread.title;
+  const { sequence } = await dispatch(host, {
+    type: 'thread.meta.update', commandId: crypto.randomUUID(), threadId: thread.id,
+    regenerateTitle: true,
+  });
+  console.log(`asked the server to retitle ${bold(before || thread.id)}${dim(`  (seq ${sequence})`)}`);
+
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let sawMarker = false;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 1500));
+    const current = await threadDetail(host, thread.id);
+    if (current.title && current.title !== before) {
+      console.log(`retitled -> ${bold(current.title)}`);
+      return;
+    }
+    if (current.titleRegeneration) { sawMarker = true; continue; }
+    if (sawMarker) break; // marker appeared and was cleared, title unchanged
+  }
+
+  console.error(
+    `\x1b[33mno title was generated\x1b[0m — the server ${sawMarker ? 'cleared the request without producing one' : `did not act on it within ${timeoutSeconds}s`}.\n` +
+    `  The title is still "${before}". Set one directly:\n` +
+    `    t3ctl thread rename ${thread.id} <title...>`,
+  );
+  process.exitCode = 1;
+};
+
 const cmdThread = async (args) => {
   const [sub, ...rest] = args;
   const { flags, pos } = parseArgs(rest);
-  if (sub === 'start' || sub === 'interrupt') {
+  // `send` is the accurate name: thread.turn.start posts a message to a thread and
+  // runs a turn, which is exactly what the UI does for every message, first or not.
+  // `start` stays as an alias because it shipped in 0.2.0.
+  const isSend = sub === 'send' || sub === 'start';
+
+  if (sub === 'rename' || sub === 'retitle') {
+    const [ref, ...titleParts] = pos;
+    if (!ref) return usage(`usage: t3ctl thread ${sub} <thread>` + (sub === 'rename' ? ' <new title...>' : ''));
+    const title = titleParts.join(' ');
+    if (sub === 'rename' && !title) return usage('usage: t3ctl thread rename <thread> <new title...>');
+    const host = pickHost(flags);
+    const target = resolveThread(await snapshot(host), ref);
+    return sub === 'retitle'
+      ? cmdThreadRetitle(target, host, Number(flags.timeout) > 0 ? Number(flags.timeout) : 30)
+      : cmdThreadRename(target, host, title);
+  }
+
+  if (isSend || sub === 'interrupt') {
     // Validate arguments before touching the host registry, so `t3ctl thread
-    // start` with no args prints usage instead of "no hosts registered".
+    // send` with no args prints usage instead of "no hosts registered".
     const [ref, ...rest2] = pos;
-    if (!ref) return usage(`usage: t3ctl thread ${sub} <thread>` + (sub === 'start' ? ' <message...>' : ''));
-    if (sub === 'start' && rest2.length === 0) return usage('usage: t3ctl thread start <thread> <message...>');
+    if (!ref) return usage(`usage: t3ctl thread ${sub} <thread>` + (isSend ? ' <message...>' : ''));
+    if (isSend && rest2.length === 0) return usage(`usage: t3ctl thread ${sub} <thread> <message...>`);
     const host = pickHost(flags);
     const thread = resolveThread(await snapshot(host), ref);
     if (sub === 'interrupt') return cmdThreadInterrupt(thread, host);
@@ -429,7 +502,11 @@ if (!commands[cmd]) {
   t3ctl project create <title> <root>           create a project for an existing dir
   t3ctl thread create <project> <title>         start a thread (--model inst/model,
                                                 --branch, --host)
-  t3ctl thread start <thread> <message...>      send a message and run the agent
+  t3ctl thread send <thread> <message...>       send a message and run the agent
+                                                (alias: start)
+  t3ctl thread rename <thread> <title...>       rename a thread
+  t3ctl thread retitle <thread> [--timeout n]   ask the server to derive a title
+                                                (warns if it produces none)
   t3ctl thread interrupt <thread>               stop the running turn
   t3ctl thread settle <thread>                  settle a thread (also: archive,
                                                 unarchive, unpin, delete)`);