@gobius/t3ctl 0.1.0 → 0.2.0

package/README.md

@@ -18,13 +18,19 @@ T3 Code is MIT-licensed open source. **Read the source before guessing at anythi
     t3ctl host add <name> <origin> <token>
     t3ctl project create <title> <workspace-root>
     t3ctl thread create <project> <title> [--model <instance>/<model>] [--branch <b>]
-
-`<project>` resolves by id, title, or workspace root. `--model` defaults to
+    t3ctl thread start <thread> <message...>  [--interaction-mode plan] [--model ...]
+    t3ctl thread interrupt <thread>
+    t3ctl thread settle|archive|unarchive|unpin|delete <thread>
+
+`<project>` resolves by id, title, or workspace root. `<thread>` resolves by id,
+exact title, then unique case-insensitive substring (ambiguous matches are listed,
+not guessed). The five verb commands above are exactly those whose payload is
+`{commandId, threadId}`; `unsettle` carries extra fields and is not among them. `--model` defaults to
 `claudeAgent/claude-opus-5`; `instanceId` is the segment before the first slash
 (opencode models are themselves slashed, e.g. `opencode/github-copilot/gpt-5.4`).
 
 `thread create` creates an *idle* thread with no messages — it does not start the
-agent. The UI never produces this state: it always fires `thread.create` immediately
+agent; use `thread start` for that. The UI never produces this state: it always fires `thread.create` immediately
 followed by `thread.turn.start`, a single command that carries the first message
 inline (`message: {messageId, role, text, attachments}` plus a `titleSeed`).
 `thread.message-sent` and `thread.turn-start-requested` are the resulting *events*,
@@ -87,6 +93,53 @@ Most-urgent-first: `running` (`session.activeTurnId` or `session.status==="runni
   `.../environment-link-challenges`, `.../devices`. Not implemented here yet; see
   `docs/internals/t3-connect.md` and `packages/contracts/src/relay.ts`.
 
+## Releasing
+
+Publishing runs in CI via **npm trusted publishing (OIDC)**. There is no `NPM_TOKEN`
+anywhere — not in the workflow, not in repo secrets. CI proves its identity with a
+short-lived OIDC token that npm verifies against a configured trusted publisher, so
+there is no long-lived credential to leak, rotate, or exfiltrate. npm also attaches a
+provenance attestation linking the tarball to the exact commit and workflow run.
+
+To cut a release:
+
+    npm version minor          # or patch/major; commits and tags
+    git push origin main --follow-tags
+
+The `v*` tag triggers `.github/workflows/release.yml`, which **stages** the release.
+CI cannot make a version public: the trusted publisher is configured stage-only, so
+a maintainer must promote it with 2FA. Either:
+
+- **npmjs.com** → the package → **Staged Packages** tab → **Approve**, or
+- `npm stage list @gobius/t3ctl` then `npm stage approve <stage-id>`
+
+2FA is required either way. `npm stage view <id>` and `npm stage download <id>` let
+you inspect the exact tarball before approving. Prereleases (`1.2.3-beta.0`) target
+the `next` dist-tag; everything else `latest`.
+
+Trust boundaries, deliberately:
+
+- **Staged, not published.** CI stages with provenance; a human promotes with 2FA.
+  A compromised workflow cannot ship anything to users. This is npm's own hardened
+  recommendation, and the stage subcommands can't use OIDC tokens by design.
+- **Tag-triggered, not push-to-main.** Merging never publishes.
+- **`environment: release`.** The OIDC subject npm checks includes the environment,
+  so a workflow running outside it cannot publish even from this repo. Add required
+  reviewers to that environment in GitHub settings to gate releases on a human.
+- **`permissions: {}` at the top**, with the job opting into only `contents: read`
+  and `id-token: write`.
+- **Actions pinned to full commit SHAs**, so a moved tag cannot swap the code.
+- **`persist-credentials: false`**, so the job's token isn't left in `.git/config`.
+- **`--ignore-scripts`** on publish, and the package has zero dependencies, so no
+  third-party code executes in the release job.
+- **Tag/version agreement is enforced** before publishing, not after.
+
+One-time setup on npmjs.com (package → Settings → Trusted Publisher):
+organization/user `Goobles`, repository `t3ctl`, workflow `release.yml`,
+environment `release`. Grant it `npm stage publish` only — not `npm publish`.
+Once that works, consider disallowing token-based publishes for the package entirely
+so this pipeline becomes the only path in.
+
 ## Caveats
 
 - Unofficial client. Built against T3 Code Nightly; pin to `snapshot` + `dispatch`.

package/package.json

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

package/t3ctl.mjs

@@ -171,6 +171,63 @@ const resolveProject = (snap, ref) =>
   snap.projects.find((p) => !p.deletedAt && p.title === ref) ??
   snap.projects.find((p) => !p.deletedAt && p.workspaceRoot === path.resolve(ref.replace(/^~/, os.homedir())));
 
+
+// Commands whose entire payload is {commandId, threadId}. Verified against
+// packages/contracts/src/orchestration.ts — note `unsettle` is NOT one of
+// these (it carries extra fields), so it is deliberately absent.
+const SIMPLE_THREAD_COMMANDS = ['settle', 'archive', 'unarchive', 'unpin', 'delete'];
+
+const resolveThread = (snap, ref) => {
+  const live = snap.threads.filter((t) => !t.deletedAt);
+  const byId = live.find((t) => t.id === ref);
+  if (byId) return byId;
+  const exact = live.filter((t) => t.title === ref);
+  if (exact.length === 1) return exact[0];
+  const fuzzy = live.filter((t) => (t.title ?? '').toLowerCase().includes(ref.toLowerCase()));
+  if (fuzzy.length === 1) return fuzzy[0];
+  if (fuzzy.length > 1) {
+    throw new Error(`"${ref}" matches ${fuzzy.length} threads:\n` +
+      fuzzy.slice(0, 8).map((t) => `  ${t.id}  ${t.title}`).join('\n'));
+  }
+  throw new Error(`no thread matching "${ref}"`);
+};
+
+
+// thread.turn.start is ONE command carrying the first message inline — this is
+// what the UI fires immediately after thread.create, which is why a thread with
+// no messages is a state the UI never produces. The client-side schema requires
+// runtimeMode/interactionMode explicitly (the server-side one defaults them).
+const cmdThreadStart = async (thread, host, text, flags) => {
+  const command = {
+    type: 'thread.turn.start',
+    commandId: crypto.randomUUID(),
+    threadId: thread.id,
+    message: { messageId: crypto.randomUUID(), role: 'user', text, attachments: [] },
+    runtimeMode: flags['runtime-mode'] ?? thread.runtimeMode ?? 'full-access',
+    interactionMode: flags['interaction-mode'] ?? 'default',
+    createdAt: new Date().toISOString(),
+  };
+  if (flags.model) {
+    const slash = flags.model.indexOf('/');
+    if (slash < 1) throw new Error(`--model must be <instance>/<model>, got "${flags.model}"`);
+    command.modelSelection = { instanceId: flags.model.slice(0, slash), model: flags.model.slice(slash + 1) };
+  } else if (thread.modelSelection) {
+    command.modelSelection = thread.modelSelection;
+  }
+  const { sequence } = await dispatch(host, command);
+  const m = command.modelSelection;
+  console.log(`started ${bold(thread.title || thread.id)}\n  id    ${thread.id}` +
+    (m ? `\n  model ${m.instanceId}/${m.model}` : '') +
+    `\n  mode  ${command.runtimeMode} / ${command.interactionMode}\n  seq   ${sequence}`);
+};
+
+const cmdThreadInterrupt = async (thread, host) => {
+  const { sequence } = await dispatch(host, {
+    type: 'thread.turn.interrupt', commandId: crypto.randomUUID(), threadId: thread.id,
+  });
+  console.log(`interrupted ${bold(thread.title || thread.id)}\n  seq ${sequence}`);
+};
+
 const cmdProject = async (args) => {
   const [sub, ...rest] = args;
   const { flags, pos } = parseArgs(rest);
@@ -191,7 +248,26 @@ const cmdProject = async (args) => {
 const cmdThread = async (args) => {
   const [sub, ...rest] = args;
   const { flags, pos } = parseArgs(rest);
-  if (sub !== 'create') return console.error('usage: t3ctl thread create <project> <title> [--model <instance>/<model>] [--branch <b>] [--host <name>]');
+  if (sub === 'start' || sub === 'interrupt') {
+    const host = pickHost(flags);
+    const [ref, ...rest2] = pos;
+    if (!ref) return console.error(`usage: t3ctl thread ${sub} <thread>` + (sub === 'start' ? ' <message...>' : ''));
+    const thread = resolveThread(await snapshot(host), ref);
+    if (sub === 'interrupt') return cmdThreadInterrupt(thread, host);
+    const text = rest2.join(' ');
+    if (!text) return console.error('usage: t3ctl thread start <thread> <message...>');
+    return cmdThreadStart(thread, host, text, flags);
+  }
+  if (SIMPLE_THREAD_COMMANDS.includes(sub)) {
+    const host = pickHost(flags);
+    const thread = resolveThread(await snapshot(host), pos.join(' '));
+    const { sequence } = await dispatch(host, {
+      type: `thread.${sub}`, commandId: crypto.randomUUID(), threadId: thread.id,
+    });
+    console.log(`${sub}d ${bold(thread.title || thread.id)}\n  id  ${thread.id}\n  seq ${sequence}`);
+    return;
+  }
+  if (sub !== 'create') return console.error('usage: t3ctl thread create <project> <title> [--model <instance>/<model>] [--branch <b>] [--host <name>]\n       t3ctl thread <settle|archive|unarchive|unpin|delete> <thread>');
   const [projectRef, ...titleParts] = pos;
   const title = titleParts.join(' ');
   if (!projectRef || !title) return console.error('usage: t3ctl thread create <project> <title> [--model <instance>/<model>] [--branch <b>] [--host <name>]');
@@ -231,7 +307,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)`);
+                                                --branch, --host)
+  t3ctl thread start <thread> <message...>      send a message and run the agent
+  t3ctl thread interrupt <thread>               stop the running turn
+  t3ctl thread settle <thread>                  settle a thread (also: archive,
+                                                unarchive, unpin, delete)`);
   process.exit(cmd ? 1 : 0);
 }
 await commands[cmd](rest);