@linzumi/cli 0.0.17-beta → 0.0.19-beta

package/README.md

@@ -22,12 +22,21 @@
 Copy this into your terminal from the repo you want changed:
 
 ```bash
-codex -- "Get a working hello-world PR from https://linzumi.com/agents.md"
+codex -c sandbox_workspace_write.network_access=true --ask-for-approval never --sandbox workspace-write --add-dir ~/.linzumi --add-dir ~/.kandan --add-dir ~/.npm --add-dir ~/.codex -- 'Follow https://linzumi.com/agents.md to get me up and running'
 ```
 
-That's the launch path: Codex opens the agent instructions, signs up,
-asks you for the emailed code, connects Linzumi to this repo, opens the
-browser editor, and posts the PR or review branch.
+That's the launch path: the first Codex is only the bootstrapper. It
+opens the agent instructions, collects the email up front, asks you for
+the emailed code when it arrives, connects Linzumi to this repo, creates
+the shared support channel, starts a Linzumi Codex session in a work
+thread, and opens the browser editor. The Linzumi Codex session does the
+branch, test, push, and PR work.
+
+The snippet uses Codex's normal workspace sandbox with network access
+enabled, automatic command approval, and explicit writable access to
+Linzumi's persistent local auth/config, editor runtime cache, npm cache,
+and Codex's own local session state. It is intentionally not the dangerous
+sandbox-bypass mode.
 
 Today, your AI coding agent has two homes, both bad.
 
@@ -58,10 +67,14 @@ In three minutes from now you'll have it.
 - **A private support channel with the Linzumi team**, in case
   anything goes sideways.
 
-Two commands. No cloud VM. Your code, your terminal, and your dev
+One pasted command. No cloud VM. Your code, your terminal, and your dev
 server stay on your laptop the whole time.
 
-## Install + start
+## Manual Runner Setup
+
+The agent-first command above is the launch path. Use this manual path
+when you want to connect your laptop yourself before starting work from
+the browser.
 
 You'll need **Node.js 20+**, **Bun 1.2+**, the **Codex CLI**, and a
 Chromium-based browser (Chrome, Edge, Arc, or Brave). Safari mostly
@@ -80,51 +93,63 @@ Here's what the next 30 seconds look like:
 4. Your laptop appears as a runner in your workspace, and
    `~/code/my-app` is added to your trusted-paths list automatically.
 5. Type something in chat — *"Explain this project and tell me how
-   to run it"* — and Codex picks it up on your machine.
+   to run it"* — and Linzumi Codex picks it up on your machine.
 
-That's it. The rest of this README is detail.
+That's it for manual setup. The rest of this README is detail.
 
 ## Agent-first launch path
 
 That one prompt is the launch path. The canonical agent instructions are
 hosted at `https://linzumi.com/agents.md`; `https://linzumi.com/skills.md`
-stays available for compatibility. The agent will ask for your email,
-ask for the emailed code, say hello to `@sean` in the shared support
-channel, start the runner in the current folder, open Codex and the
-browser editor, then post the PR or reviewable branch.
+stays available for compatibility. The bootstrap agent will collect your
+email up front, ask for the emailed code after signup sends it, say
+hello to `@sean` in the shared support channel, start the runner in the
+current folder, start a Linzumi Codex session in a work thread, and open
+the browser editor. The Linzumi Codex session then posts the PR or
+reviewable branch.
 
-Under the hood, the npm package exposes these commands:
+Under the hood, the npm package exposes these commands for the bootstrap
+agent to run. They are not extra human setup steps after the one pasted
+Codex command.
 
 ```bash
 npx -y @linzumi/cli@latest signup --email alice@example.com --agent-name BuildBot
 npx -y @linzumi/cli@latest claim --pending <pending_id> --code <XXXX-XXXX>
+npx -y @linzumi/cli@latest channel post <support_channel_id> "Hello @sean, starting this launch run."
 npx -y @linzumi/cli@latest thread new "Hello world PR" --message "Starting now."
-npx -y @linzumi/cli@latest agent runner "$PWD" --runner-id hello-world-agent
+npx -y @linzumi/cli@latest agent runner "$PWD" \
+  --runner-id hello-world-agent \
+  --allowed-cwd "$PWD" \
+  --sandbox workspace-write \
+  --approval-policy never
 ```
 
 The agent-owned runner reads `~/.linzumi/agent-token.json`, uses the
 workspace/channel scope from the approval flow, trusts only the selected
-folder by default, and listens only to the approving human unless
-`--listen-user` is explicitly passed.
+folder, and listens only to the approving human unless `--listen-user` is
+explicitly passed. The bootstrap agent waits for `Runner connected:` before
+starting Codex in the Linzumi thread.
 
-By default, the runner downloads the Kandan-approved `code-server`
+By default, the runner downloads the Linzumi-approved `code-server`
 runtime for your platform and verifies its checksum before enabling the
 browser editor. Linux editor launches are wrapped with `bubblewrap`
 (`bwrap`) for filesystem confinement.
 
-`linzumi claim` also prints `support_channel_url`. That channel is the
-shared onboarding room for the approving human, the claimed agent identity,
-and Linzumi support. Keep repository work in task threads; use the support
-channel when signup, runner, mobile, or browser-editor setup gets stuck.
+`linzumi claim` also prints `login_url`. That one-time link logs the human
+into `#general` in their own email-named workspace. The claim also provisions
+`#linzumi-support`, a shared channel with the Linzumi workspace; the bootstrap
+agent posts a hello there with the printed `support_channel_id`.
+Keep repository work in task threads; use the support channel when signup,
+runner, or browser-editor setup gets stuck.
 
-Once the runner is online, the agent can ask Kandan to start Codex and
-open the browser editor for the same thread and folder:
+Once the runner is online, the bootstrap agent can ask Linzumi to start
+Codex and open the browser editor for the same thread and folder:
 
 ```bash
 npx -y @linzumi/cli@latest codex start <thread_id> \
   --runner hello-world-agent \
   --cwd "$PWD" \
-  --work-description "Make the smallest hello-world change, run the relevant test, open a PR or clearly labeled local-review branch, and post the link."
+  --work-description "You are the Linzumi Codex agent running inside this Linzumi thread on the user's local runner. Create a small hello-world branch in the current repo, make the smallest reviewable change, run the nearest relevant local test or smoke check, push the branch or open a PR, and post the PR URL or exact review branch back in this Linzumi thread. Keep the human updated in the thread. If you are blocked, post the exact blocker instead of pretending the run succeeded."
 
 npx -y @linzumi/cli@latest editor open <thread_id> \
   --runner hello-world-agent \
@@ -155,12 +180,12 @@ You now have:
 ## Three things to try first
 
 1. **Onboard yourself to a new repo.** *"Explain this project and tell
-   me how to run it."* Codex maps the codebase before you've opened
-   a single file. Days saved on day one.
-2. **Make a real change without context-switching.** Codex edits files
-   on your disk. Watch the diff land in chat, or jump into the
-   browser editor (it's VS Code in your browser, pointed at your
-   folder) and shape it yourself.
+   me how to run it."* Linzumi Codex maps the codebase before you've
+   opened a single file. Days saved on day one.
+2. **Make a real change without context-switching.** The Codex session
+   running in Linzumi edits files on your disk. Watch the diff land in
+   chat, or jump into the browser editor (it's VS Code in your browser,
+   pointed at your folder) and shape it yourself.
 3. **Show a teammate something on your screen.** Open the browser
    editor or share your local dev server through a normal HTTPS
    link. No exposing localhost, no copy-pasting IPs, no "screenshare
@@ -181,9 +206,9 @@ alone in a terminal.
   work on, hit start. Linzumi attaches a fresh Codex to that runner
   with the folder and settings you picked.
 
-- **One Codex per thread.** Once a Codex picks up a thread, it owns
-  the thread — no second Codex can step in and trample the work. The
-  lock holds for the life of the thread.
+- **One Codex per thread.** Once a Linzumi Codex session picks up a
+  thread, it owns the thread — no second Codex can step in and trample
+  the work. The lock holds for the life of the thread.
 
 - **Browse what your team's been up to.** Open the runners dropdown
   to see, across every device, the most recently active threads with
@@ -208,9 +233,10 @@ linzumi paths remove ~/code/my-app
 on first use. `linzumi connect` uses the list as-is — or pass
 `--allowed-cwd <paths>` for a one-off comma-separated override.
 
-There's no credential escalation: an agent attached to a trusted
-folder can only read and write inside that folder, with the same
-privileges as your shell. Every action is auditable from the thread.
+There's no credential escalation: Linzumi only asks the runner to start
+Codex or the editor inside trusted folders. Those processes still run
+with your shell's operating-system privileges, so choose trusted folders
+intentionally. Every action is auditable from the thread.
 
 ## When something looks wrong
 
@@ -234,7 +260,7 @@ privileges as your shell. Every action is auditable from the thread.
 ## Pinning a version
 
 ```bash
-npm install -g @linzumi/cli@0.0.17-beta
+npm install -g @linzumi/cli@0.0.19-beta
 linzumi --version
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.17-beta",
+  "version": "0.0.19-beta",
   "description": "Linzumi CLI — point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
   "type": "module",
   "bin": {

package/src/agentBootstrap.ts

@@ -35,6 +35,13 @@ type AgentCommand =
       readonly message: string;
       readonly tokenFile: string;
     }
+  | {
+      readonly kind: "channelPost";
+      readonly apiUrl: string;
+      readonly channelId: string;
+      readonly body: string;
+      readonly tokenFile: string;
+    }
   | {
       readonly kind: "post";
       readonly apiUrl: string;
@@ -87,7 +94,9 @@ export type AgentTokenFile = {
   readonly workspaceId: string;
   readonly channelId: string | undefined;
   readonly ownerUsername: string | undefined;
-  readonly dmUrl: string;
+  readonly channelUrl: string;
+  readonly loginUrl: string;
+  readonly supportChannelId: string;
   readonly supportChannelUrl: string | undefined;
   readonly savedAt: string;
   readonly cursors: Record<string, string>;
@@ -124,6 +133,9 @@ export async function runAgentCliCommand(
     case "threadNew":
       await runThreadNew(command, deps);
       return;
+    case "channelPost":
+      await runChannelPost(command, deps);
+      return;
     case "post":
       await runPost(command, deps);
       return;
@@ -196,6 +208,36 @@ function parseAgentCommand(args: readonly string[]): AgentCommand {
         tokenFile: agentTokenFile(parsed.flags),
       };
     }
+    case "channel": {
+      const [subcommand, ...subcommandArgs] = rest;
+
+      if (subcommand !== "post") {
+        throw new Error("linzumi channel supports: post");
+      }
+
+      const parsed = parseAgentArgs(subcommandArgs);
+      const [channelId, body, ...extra] = parsed.positionals;
+
+      if (channelId === undefined || channelId.trim() === "") {
+        throw new Error("missing channel id");
+      }
+
+      if (body === undefined || body.trim() === "") {
+        throw new Error("missing message body");
+      }
+
+      if (extra.length > 0) {
+        throw new Error("linzumi channel post accepts channel id and one message body");
+      }
+
+      return {
+        kind: "channelPost",
+        apiUrl: agentApiUrl(parsed.flags),
+        channelId,
+        body,
+        tokenFile: agentTokenFile(parsed.flags),
+      };
+    }
     case "post": {
       const parsed = parseAgentArgs(rest);
       const [threadId, body, ...extra] = parsed.positionals;
@@ -426,7 +468,9 @@ async function runClaim(
     workspaceId: requiredString(response, "workspace_id"),
     channelId: stringValue(response.channel_id),
     ownerUsername: stringValue(response.owner_username),
-    dmUrl: requiredString(response, "dm_url"),
+    channelUrl: requiredString(response, "channel_url"),
+    loginUrl: requiredString(response, "login_url"),
+    supportChannelId: requiredString(response, "support_channel_id"),
     supportChannelUrl: requiredString(response, "support_channel_url"),
     savedAt: new Date().toISOString(),
     cursors: {},
@@ -434,6 +478,9 @@ async function runClaim(
 
   writeTokenFile(command.tokenFile, tokenFile, deps.writeTextFile);
   deps.stdout.write(`Logged in as agent ${tokenFile.agentId}\n`);
+  deps.stdout.write(`login_url: ${tokenFile.loginUrl}\n`);
+  deps.stdout.write(`channel_url: ${tokenFile.channelUrl}\n`);
+  deps.stdout.write(`support_channel_id: ${tokenFile.supportChannelId}\n`);
   deps.stdout.write(`support_channel_url: ${tokenFile.supportChannelUrl}\n`);
 }
 
@@ -457,6 +504,22 @@ async function runThreadNew(
   deps.stdout.write(`thread_url: ${requiredString(response, "thread_url")}\n`);
 }
 
+async function runChannelPost(
+  command: Extract<AgentCommand, { readonly kind: "channelPost" }>,
+  deps: AgentCliDeps,
+): Promise<void> {
+  const tokenFile = readTokenFile(command.tokenFile, deps.readTextFile);
+  const response = await postJson(
+    command.apiUrl,
+    `/agent/channels/${encodeURIComponent(command.channelId)}/messages`,
+    { body: command.body },
+    tokenFile.agentToken,
+    deps.fetchImpl,
+  );
+
+  deps.stdout.write(`message_id: ${requiredString(response, "message_id")}\n`);
+}
+
 async function runPost(
   command: Extract<AgentCommand, { readonly kind: "post" }>,
   deps: AgentCliDeps,
@@ -761,7 +824,9 @@ export function readStoredAgentTokenFile(
     workspaceId: requiredString(parsed, "workspaceId"),
     channelId: stringValue(parsed.channelId),
     ownerUsername: stringValue(parsed.ownerUsername),
-    dmUrl: requiredString(parsed, "dmUrl"),
+    channelUrl: requiredString(parsed, "channelUrl"),
+    loginUrl: requiredString(parsed, "loginUrl"),
+    supportChannelId: requiredString(parsed, "supportChannelId"),
     supportChannelUrl: stringValue(parsed.supportChannelUrl),
     savedAt: requiredString(parsed, "savedAt"),
     cursors,
@@ -790,6 +855,7 @@ Usage:
   linzumi signup --email <email> --agent-name <name> [--api-url <url>]
   linzumi claim --pending <pending_id> --code <XXXX-XXXX> [--api-url <url>]
   linzumi thread new <title> --message <message> [--api-url <url>]
+  linzumi channel post <channel_id> <message> [--api-url <url>]
   linzumi post <thread_id> <message> [--kind progress|question]
   linzumi inbox <thread_id> --since-last
   linzumi done <thread_id> --message <message>

package/src/index.ts

@@ -121,7 +121,7 @@ async function main(args: readonly string[]): Promise<void> {
       process.stdout.write(connectGuideText());
       return;
     case "version":
-      process.stdout.write("linzumi 0.0.17-beta\n");
+      process.stdout.write("linzumi 0.0.19-beta\n");
       return;
     case "auth":
       await runAuthCommand(parsed.args);
@@ -614,7 +614,7 @@ export async function parseRunnerArgs(
   }
 
   if (values.get("version") === true) {
-    process.stdout.write("linzumi 0.0.17-beta\n");
+    process.stdout.write("linzumi 0.0.19-beta\n");
     process.exit(0);
   }