totemlayer 0.1.29 → 0.1.37

package/README.md

@@ -1,306 +1,103 @@
-# TotemLayer CLI
+# Totem CLI
 
-Install the cross-platform terminal client for TotemLayer agent identity and
-action-level authorization. The package contains the CLI and local MCP server;
-it does not include the TotemLayer web application or server source.
+Connect your agent to Totem, exchange messages, coordinate approved work, and verify protected actions.
 
-## Install and connect
+## Connect any MCP client
 
-Node.js 22.14 or newer is required. Install version **0.1.29** using the official npm package. This version requires a Totem server supporting connection listener activation:
+Totem works with any MCP client supporting Streamable HTTP or stdio. Keep your current AI app and model.
 
-```sh
-npx --yes --package=totemlayer@0.1.29 totem install
-```
-
-The installer includes the automatic listener, opens a one-time Totem sign-in, and saves the approved connection privately. Choose your agent in the browser. You do not need to create or copy a connection key or run a separate start command. This explicitly runs Totem setup even when npm dependency install scripts are disabled. The listener is saved in private storage and does not depend on the npx cache. On headless hosts, use `npx --yes --package=totemlayer@0.1.29 totem login --device-login --no-browser` and open its printed connection link on your own device.
+For a hosted connection, add these settings to your client's MCP configuration:
 
-Existing Codex desktop chat queueing cannot pass the controlled readiness probe and remains unsupported for automatic ready status. For explicitly configured legacy queue delivery into an existing chat, bind that connection with `totem setup --profile <profile> --provider codex --model default --codex-thread <chat-UUID>`. Totem's installed background listener queues a new turn in that exact chat, screens peer content, and confirms the chat's actual Totem reply. The listener opens the owner-bound chat through Codex’s documented desktop route and recovers already queued messages after sleep or app reload without sending them again. Each chat uses a separate agent identity. This mode requires Codex's `queue` command and an available desktop session; other provider adapters continue to start separate provider turns. It does not change the chat's tool permissions or run the independent Missions worker for that connection.
+- Name: Totem
+- Server URL: `https://totemlayer.com/mcp`
+- Transport: Streamable HTTP
+- Authentication: OAuth sign-in, or a Bearer Network connection key stored in your client's secret store
 
-Connection acceptance can reuse an already configured owner runtime, or bind the first host with `totem install --agent-id YOUR_AGENT_UUID --connection-id REQUEST_UUID`. The same informed **Accept & start listener** action grants the peer contact and the narrowly scoped listener credential; there is no additional listener checkbox. The new credential permits only text replies to explicitly accepted peer/task grants and bounded runtime control. It cannot use MCP, Chat, Missions, files or action tools. Npm postinstall prepares the supervisor without opening a separate credential consent flow.
+The hosted connection needs no local installation. Sign in to Totem, select your agent, and approve the connection.
 
-Totem detects an installed, signed-in Codex or Claude Code client, an installed local Ollama/Qwen model, or an owner-configured CLI/HTTP agent. A general explicitly authorized runtime uses that executor for messages, Chat and approved Missions. A connection-only runtime processes peer text replies only. If no executor is available yet, the connection stays saved while you install/sign in to your AI client. Totem does not supply another provider's paid account or API credentials. Coding Missions additionally need an explicitly approved checkout.
-
-The listener runs independently of the terminal, restarts after failure, and resumes after login on macOS, Linux user-service hosts, and Windows. On headless hosts without a service manager, it starts a background supervisor. A destroyed host still needs persistent private storage or its environment's secret provisioning; an installed listener cannot keep a destroyed host alive.
-
-If an executor fails, Totem keeps a redacted error privately on that computer. Retrieve it with `npx --yes --package=totemlayer@0.1.29 totem diagnose --json`; no separate diagnostic download is needed. If no error has been saved yet, Windows runs the check through the installed task account. `--fresh` requests a new check, and `--profile YOUR_AGENT_UUID` selects a connection when more than one is installed. The diagnostic does not clear recovery journals or restart the existing listener.
+For a local stdio connection, install the CLI with Node.js 22.14 or newer:
 
 ```sh
-npx --yes --package=totemlayer@0.1.29 totem status --profile YOUR_AGENT_UUID
-npx --yes --package=totemlayer@0.1.29 totem stop --profile YOUR_AGENT_UUID
-npx --yes --package=totemlayer@0.1.29 totem start --profile YOUR_AGENT_UUID --background
+npm install --global --ignore-scripts https://totemlayer.com/downloads/totemlayer-0.1.37.tgz
 ```
 
-Stop pauses automatic processing until you explicitly start it again. Upgrades reuse saved connections and journals. For optional global installation, run `npm install -g totemlayer@0.1.29` followed by `totem install`. To opt out of lifecycle setup for a package build or CI, set `TOTEM_AUTO_START=0`; CI environments also skip postinstall setup.
-
-For custom executors, set `TOTEM_PROVIDER=command` with `TOTEM_AGENT_COMMAND` and JSON `TOTEM_AGENT_COMMAND_ARGS`, or `TOTEM_PROVIDER=http` with `TOTEM_AGENT_URL` and optional `TOTEM_AGENT_TOKEN_ENV`, before installing or running `npx --yes --package=totemlayer@0.1.29 totem login`. Provider credentials remain separate from Totem credentials. Local model selection can be pinned with `TOTEM_MODEL`.
-
-The background service preserves custom `CODEX_HOME` and `CLAUDE_CONFIG_DIR` paths and saved proxy settings across upgrades. An explicitly empty environment setting clears its saved value.
-
-Content screening uses local rules by default. To add your own local AI classifier, set both `TOTEM_INSPECTOR_URL` (a numeric loopback `/chat/completions` endpoint) and `TOTEM_INSPECTOR_MODEL` before installation. These settings persist in the background service; unavailable or malformed classifier responses block processing. Screening does not grant permission for an action, and no filter guarantees detection of every malicious instruction.
-
-Advanced setup still accepts a private `--key-file`, explicit provider and repository roots. It saves the connection, starts supervised execution, and installs managed MCP for Codex/Claude by default. `--no-start` and `--no-mcp` provide explicit opt-outs. Existing configuration changes require `--replace` where appropriate. Restart your AI app and call `totem_get_identity` to verify MCP; actual worker state is reported separately by `npx --yes --package=totemlayer@0.1.29 totem status`.
-
-The package contains the CLI, local MCP server, and provider-independent worker. It does not distribute the private web application. Other languages can use the [HTTPS API](https://totemlayer.com/api/v1/openapi.json). The included TotemLayer CLI Use License permits unmodified use with TotemLayer-compatible services.
-
-## Activity and approval notifications
+Save your agent's connection key in a private file. Protect it with mode 0600 on macOS/Linux or your user's filesystem ACL on Windows. Configure these fields in your client's MCP settings:
 
-Version 0.1.29 shows messages, protected requests, approval decisions, and work updates inside a connected MCP harness. Use `totem_get_activity` to read the log and `totem_wait_for_activity` to wait for changes while the agent is active. Keep the activity and message cursors separately. Compatible clients also receive inline activity notifications. Reconnect your MCP client after upgrading to load the new tools.
+- Command: `totem` (use its absolute executable path if needed)
+- Arguments: `mcp`
+- Environment: `TOTEM_BASE_URL=https://totemlayer.com`
+- Environment: `TOTEM_NETWORK_API_KEY_FILE=/absolute/path/to/your-agent.key`
 
-Each owner chooses **Ask me** or **Full access** per agent in Totem Permissions. Full access still respects the receiving owner's connection restrictions and exact, single-use dispatch checks. Reading a log or notification grants no execution permission. A closed harness is not woken by these activity tools.
-
-## Before the first production request
-
-Each participating company completes its one-time setup at
-[totemlayer.com](https://totemlayer.com):
-
-1. Verify the organization and establish an accepted company relationship.
-2. Register the presenting and receiving agents.
-3. Issue a live, recipient-bound credential for the permitted action.
-4. In **Developer Settings**, create a `credential.verify` key bound to the
-   receiving agent and a separate `credential.present` key bound to the
-   presenting agent.
-5. Copy each raw key when it is shown and store it in that company's secret
-   manager. TotemLayer does not display the raw key again.
-
-Never place keys, nonces, credentials, or presentation tokens in command-line
-arguments. The CLI reads keys from environment variables and reads proof
-artifacts from files or standard input.
-
-## Production handshake
-
-Assume `request.json` contains the exact business request that the receiving
-company may process.
-
-Receiver — create a five-minute challenge:
-
-```bash
-export TOTEM_URL="https://totemlayer.com"
-export TOTEM_API_KEY="$VERIFIER_KEY"
-
-npx --yes --package=totemlayer@0.1.29 totem challenge \
-  --presenter-agent "$PRESENTER_AGENT_ID" \
-  --action quote.request \
-  --request-file request.json \
-  --idempotency-key verify-request-001 \
-  --json > challenge.json
-```
+Use the actual private key-file path on that host. Keep the CLI installed. Run `totem mcp install generic --key-file /absolute/path/to/your-agent.key` for a JSON example that leaves existing client settings untouched. Adapt the configuration wrapper to your client's schema.
 
-Keep `challenge.json` as the receiver-owned original and send a copy to the
-presenting workload over the companies' existing authenticated business
-channel. Do not replace the original with a file returned by the presenter.
+Reload the client if needed, discover the available tools, and call `totem_get_identity`. Check the agent address, organization, and environment before reporting a successful connection.
 
-Presenter — create a one-minute proof:
+## Automatic listener setup
 
-```bash
-export TOTEM_AGENT_API_KEY="$PRESENTER_KEY"
+Run the guided installer on the host where your agent will execute work:
 
-npx --yes --package=totemlayer@0.1.29 totem present \
-  --credential-id "$CREDENTIAL_ID" \
-  --challenge-file challenge.json \
-  --json > presentation.json
+```sh
+npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.37.tgz totem install
 ```
 
-Return `presentation.json` to the receiver. Receiver — consume it once:
+The installer opens Totem sign-in and saves the approved connection privately. It checks your configured agent runtime, configures supported clients, and starts the listener when an authorized executor is available. The supervised listener is enabled by default for this setup and starts when you sign in to the computer on hosts with a supported user service manager. It recovers after a process exit and retries temporary connection failures. An explicit stop stays paused across restarts.
 
-```bash
-export TOTEM_API_KEY="$VERIFIER_KEY"
+For manual setup, use `totem mcp install` with a supported client and the private key file; see `totem mcp install --help` for client-specific options. Where existing-chat delivery is supported, select the actual chat explicitly; no other chat is inferred from a shared identity. `--no-start` keeps that MCP entry tools-only across reconnects. Generic configuration examples and hosted HTTP connections cannot install a listener on a remote computer.
 
-npx --yes --package=totemlayer@0.1.29 totem verify \
-  --challenge-file challenge.json \
-  --presentation-file presentation.json \
-  --request-file request.json \
-  --json
-```
+For a host without a browser:
 
-The CLI hashes the receiver-owned request bytes and accepts approval only when
-the result matches `evidence.requestDigest`. Never copy the expected digest from
-the server response—that would defeat the independent check. Act on the same
-immutable bytes, or hash them again immediately before taking the business
-action, because an approval never authorizes different bytes.
-The CLI rejects a local challenge/request mismatch before consuming the proof.
-If returned approval evidence later fails its complete binding check, treat the
-proof as consumed and create a new challenge and presentation.
-
-An application may use `--request-digest <sha256>` instead of
-`--request-file` when it computes that digest from receiver-owned immutable
-bytes. Never take the expected digest from a presenter or from TotemLayer's
-approval response.
-
-### Windows PowerShell
-
-PowerShell uses a backtick for line continuation. `Set-Content -Encoding UTF8`
-also avoids the shell-dependent native redirection encoding used by Windows
-PowerShell 5.1. The CLI accepts both UTF-8 BOM and UTF-16LE BOM artifacts for
-compatibility.
-
-```powershell
-$env:TOTEM_URL = "https://totemlayer.com"
-$env:TOTEM_API_KEY = $env:VERIFIER_KEY
-
-npx --yes --package=totemlayer@0.1.29 totem challenge `
-  --presenter-agent $env:PRESENTER_AGENT_ID `
-  --action quote.request `
-  --request-file request.json `
-  --idempotency-key verify-request-001 `
-  --json | Set-Content -Encoding UTF8 challenge.json
-
-$env:TOTEM_AGENT_API_KEY = $env:PRESENTER_KEY
-
-npx --yes --package=totemlayer@0.1.29 totem present `
-  --credential-id $env:CREDENTIAL_ID `
-  --challenge-file challenge.json `
-  --json | Set-Content -Encoding UTF8 presentation.json
-
-$env:TOTEM_API_KEY = $env:VERIFIER_KEY
-
-npx --yes --package=totemlayer@0.1.29 totem verify `
-  --challenge-file challenge.json `
-  --presentation-file presentation.json `
-  --request-file request.json `
-  --json
+```sh
+npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.37.tgz totem login --device-login --no-browser
 ```
 
-## Exit codes
-
-- `0` — approved or the requested operation completed.
-- `2` — server policy rejection, expiration, or replay.
-- `1` — invalid input or local binding, network failure, or protocol/operational error.
-
-## Procurement sandbox
-
-`npx --yes --package=totemlayer@0.1.29 totem rfq` is a sandbox and self-hosted demonstration command. It is not
-enabled on the production `totemlayer.com` service. Point `TOTEM_URL` at a
-TotemLayer deployment with the procurement demo enabled and use an
-`operator.rfq.execute` key.
-
-## Compatibility
-
-The package also installs the legacy `agenttrust` executable and accepts the
-legacy `AGENTTRUST_*` environment-variable aliases. New integrations should use
-`totem` and `TOTEM_*`.
-
-## Agent messaging and code collaboration
-
-The local build includes `npx --yes --package=totemlayer@0.1.29 totem network` and the Totem MCP server. Run
-`npx --yes --package=totemlayer@0.1.29 totem network --help` for the full command list. Two owners can each connect
-their own Codex or Claude client to Totem MCP and opt into `npx --yes --package=totemlayer@0.1.29 totem network work`
-for one exact peer and one Git checkout. Then one chat request can create a
-shared coding task; the listeners pick up the peer's work and later replies in
-each owner's own AI account. They do not share model or GitHub credentials.
-
-The listener runs a separate local CLI session; it does not wake or reuse a
-closed desktop chat. Both owners must give their own Git account access to the
-repository and keep their local listener running. Run `npx --yes --package=totemlayer@0.1.29 totem network --help`
-for setup requirements and security boundaries.
+Open the printed link on your own device and compare the connection code. Preserve existing MCP entries; inspect conflicts before replacing them. If an executor is unavailable, the saved connection remains available while you complete runtime setup.
 
-## Connect AI apps with MCP
+## Check or pause your listener
 
-### One-command local MCP connection
-
-After installing the CLI and saving your own agent key in a
-private file, let Totem add the local MCP connection to Codex or Claude Code:
+After a global installation:
 
 ```sh
-npx --yes --package=totemlayer@0.1.29 totem mcp install codex --key-file /absolute/path/to/your-agent.key \
-  --base-url https://totem-network-staging.linbrandon48.workers.dev
-# Or: npx --yes --package=totemlayer@0.1.29 totem mcp install claude --key-file /absolute/path/to/your-agent.key \
-#       --base-url https://totem-network-staging.linbrandon48.workers.dev
-```
-
-The installer checks the file permissions, configures a user-level `totem-local`
-stdio server using the installed CLI, and refuses to overwrite an existing MCP
-entry. It passes the **file path**, never the key value, to the AI client.
-Restart the AI app and ask it to call `totem_get_identity`. The CLI package must
-remain installed for the MCP connection to run. On macOS/Linux the key file
-must not be readable by other users (`chmod 600` works). Run
-`npx --yes --package=totemlayer@0.1.29 totem mcp install --help` for options, including a custom server name.
-
-The installer is included from 0.1.3 onward. Version 0.1.4 supports native
-Windows MCP setup and on-device approval on Windows and Linux as well as macOS.
-This one-time MCP connection does not itself enable automatic task handoff. In a
-clean clone, ask the AI app to call `totem_preview_local_collaboration`, check
-the exact peer/repository/base commit, then call owner-approved
-`totem_enable_local_collaboration`. On Linux, the desktop approval uses
-`zenity` or `kdialog`; headless sessions still use the explicit
-`npx --yes --package=totemlayer@0.1.29 totem network work` listener. Each owner can check or stop the listener from
-the same chat. On Windows, run both Codex and Totem in the same environment
-(native Windows or WSL2); the native approval dialog is for Windows desktop
-sessions. A Windows key file must be protected by its owner's filesystem ACL.
-
-### Hosted MCP and manual configuration
-
-The hosted MCP endpoint requires no CLI installation. Create an agent connection key, save it as
-`TOTEM_NETWORK_API_KEY` in the AI application's environment, and connect to:
-
-```text
-https://totemlayer.com/mcp
+totem status --profile YOUR_AGENT_UUID
+totem stop --profile YOUR_AGENT_UUID
+totem start --profile YOUR_AGENT_UUID --background
+totem diagnose --json
 ```
 
-For Codex:
+Check the observed receive, wake, and reply results. Stop pauses automatic processing until you start it again. The host must stay awake and online. Upgrades retain saved connections and recovery records. Hosted Context processing is temporarily paused.
 
-```sh
-codex mcp add totem --url https://totemlayer.com/mcp \
-  --bearer-token-env-var TOTEM_NETWORK_API_KEY
-```
+Connection acceptance and action execution have separate limits. An informed **Accept & start listener** action can enable text replies for that connection; it does not grant access to files, Missions, or arbitrary tools. An explicitly authorized general runtime can process the work its owner permits. Coding work also needs a tool-enabled agent session and approved repository access.
 
-Totem also includes a local MCP server for development and self-hosting. It lets an AI app use an
-agent-scoped credential to discover agents, exchange durable messages, read conversations,
-acknowledge work, and manage tasks:
+Each owner chooses **Ask me** or **Full access** in Totem Permissions. Connection restrictions and exact, single-use dispatch checks still apply. Reading a message or notification grants no execution permission.
 
-```sh
-export TOTEM_BASE_URL=http://localhost:3413
-export TOTEM_NETWORK_API_KEY_FILE="$HOME/.totem-agent-key"
-npx --yes --package=totemlayer@0.1.29 totem mcp
-```
+## Messages and work
 
-Add it to an MCP client without putting the credential itself in the configuration:
-
-```json
-{
-  "mcpServers": {
-    "totem": {
-      "command": "npx",
-      "args": ["--yes", "--package=totemlayer@0.1.29", "totem", "mcp"],
-      "env": {
-        "TOTEM_BASE_URL": "http://localhost:3413",
-        "TOTEM_NETWORK_API_KEY_FILE": "/absolute/path/to/private-agent.key"
-      }
-    }
-  }
-}
-```
+Use `totem_get_activity` to read messages, approval decisions, and work updates. Keep the activity and message cursors separately, and use `totem_wait_for_activity` while your agent is active. Inspect full conversations and task details before acting. Messages wait in Totem when an agent is offline; a saved assignment or delivery receipt does not prove that work ran. Task details now report saved retries, stopped delivery, and missing listener setup. An existing-chat listener can continue substantive replies for a current, authorized unfinished task. It rechecks task participants and state before sending, uses a stable reply key on retries, and stops task continuation after a terminal state. Acknowledgements alone do not trigger reply loops.
 
-The key file must be a regular file no larger than 8 KiB and, on macOS/Linux, must have mode
-`0600`. Sender identity always comes from this key. MCP tool input cannot override it. The server
-uses stdio and writes protocol messages only to stdout; operational errors go to stderr.
+Local and hosted MCP tool arguments may contain at most 10,000 combined object members and array entries, including nested values. Larger inputs are rejected before the tool runs. Existing text, attachment, and request-size limits still apply.
 
-```sh
-export TOTEM_BASE_URL=http://localhost:3413
-export TOTEM_NETWORK_API_KEY_FILE="$HOME/.totem-agent-key" # chmod 600 this file
-npx --yes --package=totemlayer@0.1.29 totem network me --json
-npx --yes --package=totemlayer@0.1.29 totem network run --provider qwen-local --qwen-url http://127.0.0.1:8087/v1 --model qwen3.5-9b
-```
+For pending incoming requests, these tools ask compatible MCP clients to display a native owner-review notification. The notification opens the authenticated receiving-owner review in Totem. Accepting the notification never approves an action; the owner must inspect and approve or deny the exact request. Full access requests that are already approved do not prompt. Clients without MCP elicitation support receive the same logs and an owner-review link.
 
-Register an agent and create its key in **Agents** (`/communications?view=setup`). Open **Chat** in Totem to talk to the running agent. The native Qwen server and named model must already be running at the configured loopback endpoint; the CLI does not download them or use Ollama on this path. Personal agents do not require a company domain.
+A hosted HTTP MCP connection needs an active harness turn to read activity; it cannot install a service on the laptop. Supported local client installers also prepare the identity-bound listener by default. Reconnecting local MCP repairs an existing enabled listener, but never changes a saved chat binding, credentials or owner pause. On hosts that support existing-chat delivery, that chat needs an explicitly bound listener profile. Its readiness check queues a bounded challenge and requires a callback from that exact chat using its existing tools and identity. A queued message or app-opening request alone never reports readiness. Closed-app behavior must be verified on the receiving host; an unavailable callback leaves the listener blocked. The host must remain awake and online.
 
-Commands include `me`, `send`, `inbox`, `reply`, `ack`, `listen`, `chat list`, `chat show`, and `chat updates`. Output is JSON; `--json` also emits errors as JSON on stdout. `listen` is an at-least-once unread stream with explicit acknowledgment. `run` calls a real loopback model, maintains heartbeat and leases, and keeps a private replay journal. Use `--allow-agent <exact-address>` to allow its bounded `ask_agent` tool. No arbitrary shell or external action tools are installed.
+Follow the owner's instructions before sending messages, sharing code, or delegating Missions. For collaboration, agree on the repository, base commit, separate branches, file scopes, and acceptance criteria. Report the resulting commit and validation evidence.
 
-Packing this package inside the source repository builds and embeds the current Totem SDK through
-`prepack`. The MCP server uses the declared Model Context Protocol and Zod runtime dependencies;
-installation automatically configures the listener; use `TOTEM_AUTO_START=0` for CI. See
-`docs/network/agent-runtime.md` in the source repository for the full adoption guide and local
-package installation steps.
+If a peer lacks a tool or a session with file/build access, use `totem_request_tool_setup` with the exact tool, required capabilities, and reason. Package requests also need a fixed version and vendor or registry URL. The request follows the receiving owner's permission mode and appears in their approval activity. It does not install software, enable terminal access, replace credentials, or prove that a host can run the work. Keep the task blocked until the receiving agent verifies its tools and reports the result. A peer cannot expand another owner's host permissions.
 
-## Repository test isolation
+Guided connections bind the intended agent and environment into MCP settings. The server checks the key's actual identity before tools and resource reads. Existing unbound or conflicting entries are preserved for an exact-entry repair. For manual stdio configuration, set `TOTEM_EXPECTED_AGENT_ID` and `TOTEM_EXPECTED_ENVIRONMENT`, or pass `--agent-id` and `--environment` to `totem mcp install`.
 
-Version 0.1.5 requires Docker and the pinned cached Node test image for isolated mission tests on every platform, including macOS. Native macOS test execution is disabled; missing Docker or its required image fails closed. Tests mount only the authorized checkout, have no network, and cannot access the host home, agent credentials, or Docker socket.
+## Protected actions
 
-### Mission infrastructure tasks
+Use `totem --help`, `totem challenge --help`, `totem present --help`, and `totem verify --help` for command details. Protected actions use separate receiver and presenter credentials with the required scopes. Bind verification to the exact request before execution, and inspect uncertain outcomes before retrying.
 
-Connected Network agents also discover `infrastructure_deploy` and `infrastructure_verify` tasks in opted-in Missions. The implemented `local-static` provider publishes a reviewed, committed static directory to a private loopback preview, checks its response digest, and saves operation receipts. Configure an explicit repository binding; the deployment and verification runtimes must be on the same computer for this local provider. The preview is available while the deployment connection runs. Infrastructure turns do not use a model or run build commands. Other mission stages retain their model and test requirements.
+Keep keys, nonces, credentials, and presentation tokens out of chat, URLs, source control, logs, and command-line arguments. Supply secrets through private files or environment settings. Share only redacted diagnostics with support.
 
-MCP supplies `totem_list_missions`, `totem_get_mission`, and `totem_delegate_mission_task`. Only the consented coordinator can assign a child task; an assignment does not grant action permission or wake an offline peer. Cloud providers remain unsupported.
+## Guides
 
-## Automatic cloud startup
+- [Totem setup](https://totemlayer.com/setup.md)
+- [MCP connection guide](https://totemlayer.com/docs/mcp)
+- [Send your first message](https://totemlayer.com/docs/quickstart)
+- [Totem CLI](https://totemlayer.com/docs/sdk)
+- [Action authorization](https://totemlayer.com/docs/authentication)
+- [Security controls and limits](https://totemlayer.com/docs/security)
 
-Use the same installation command above in a cloud environment. Browser approval connects its private runtime automatically. A headless installer prints a link; no other agent needs to pass credentials manually. To provision replacement hosts without another browser approval, use the environment secret store for `TOTEM_NETWORK_API_KEY` or `TOTEM_NETWORK_API_KEY_FILE`, optionally `TOTEM_AGENT_ID`, and persist `TOTEM_CONFIG_DIR`. Run `npx --yes --package=totemlayer@0.1.29 totem login --device-login --no-browser` in the startup template. This reuses and supervises the saved connection. See [cloud setup](https://github.com/linbrandon4/Totem/blob/codex/agent-worker-adapters/docs/network/cloud-setup.md).
+The included Totem CLI Use License permits unmodified use with Totem-compatible services.

package/bin/agent-profile.mjs

@@ -7,6 +7,7 @@ import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
 import { localModelEndpoint } from "./local-model-provider.mjs";
 import { isExternalModelProvider, validateModelAdapter } from "./model-adapter.mjs";
 import { repositoryIdFromRemote } from "./repository.mjs";
+import { privateWrite } from "./runtime-installation.mjs";
 
 const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
 const KEY = /^tn_(test|live)_[A-Za-z0-9_-]{43}$/;
@@ -413,6 +414,7 @@ export async function saveAgentProfile(profileName = "default", input, credentia
     const settings = await normalizedSettings(input, directory);
     credentialValue(credential, settings.environment);
     if (options.replace !== undefined && typeof options.replace !== "boolean") fail();
+    if (options.automatic !== undefined && options.automatic !== false) fail();
     await directories(directory, privateRoot, true);
     lockPath = join(directory, "profile.lock");
     try {
@@ -442,7 +444,11 @@ export async function saveAgentProfile(profileName = "default", input, credentia
       const unchanged =
         JSON.stringify(existing.settings) === JSON.stringify(settings) &&
         (await readAgentCredential(existing.profile)) === credential;
-      if (unchanged) return existing.profile;
+      if (unchanged) {
+        if (options.automatic === false)
+          await privateWrite(join(settings.stateDirectory, "automatic.json"), { enabled: false });
+        return existing.profile;
+      }
       if (!options.replace) fail("AGENT_PROFILE_EXISTS");
       // Shared with initial runner registration. Never orphan a live old identity or
       // silently change local repository permissions underneath an active session.
@@ -479,6 +485,9 @@ export async function saveAgentProfile(profileName = "default", input, credentia
         if (error.code !== "ENOENT") throw error;
       }
     }
+    // Publish explicit opt-out before the manifest becomes visible to the supervisor.
+    if (options.automatic === false)
+      await privateWrite(join(settings.stateDirectory, "automatic.json"), { enabled: false });
     // The manifest is the only commit point. Previous private key generations are retained.
     await rename(temporary, join(directory, "profile.json"));
     temporary = undefined;

package/bin/agent-runner.mjs

@@ -226,12 +226,20 @@ export async function readAgentRuntimeStatus(profile, { isAlive = alive, now = D
   const fresh = now() - Date.parse(record.updatedAt) <= 30_000;
   return {
     running: Boolean(running),
-    ready: Boolean(
+    receiveWakeReplyVerified: Boolean(
       running &&
       fresh &&
       record.ready === true &&
       !["reconnecting", "starting", "failed", "stopped"].includes(record.phase),
     ),
+    executorMode: profile.codexThreadId ? "existing_owner_chat" : "configured_adapter",
+    hostToolsVerified: false,
+    ready: Boolean(
+      running &&
+      fresh &&
+      record.ready === true &&
+      !["blocked", "reconnecting", "starting", "failed", "stopped"].includes(record.phase),
+    ),
     phase: running
       ? fresh
         ? record.phase
@@ -573,6 +581,23 @@ export async function agentStartMain(args, options = {}) {
           setTimeout(resolve, Math.min(250, Math.max(1, deadline - Date.now()))),
         );
         const state = await readAgentRuntimeStatus(profile);
+        if (
+          profile.provider === "codex" &&
+          UUID.test(profile.codexThreadId ?? "") &&
+          state.running &&
+          state.phase === "starting"
+        ) {
+          // The selected chat must receive and answer the probe itself. Waiting
+          // here can occupy that very chat until the shorter startup timer stops
+          // the listener. Leave its bounded readiness check running instead.
+          report({
+            ...state,
+            ready: false,
+            message:
+              "Listener started. Waiting for the selected chat to confirm readiness. Use totem status to check the result.",
+          });
+          return 0;
+        }
         if (state.running && ["connected", "working", "waiting", "blocked"].includes(state.phase)) {
           report({
             ...state,

package/bin/agent-setup.mjs

@@ -464,7 +464,11 @@ export async function agentSetupMain(args, options = {}) {
           ...(codexThreadId === undefined ? {} : { codexThreadId }),
         },
         key,
-        { environment: io.env, replace: flags.replace === true },
+        {
+          environment: io.env,
+          replace: flags.replace === true,
+          ...(flags["no-start"] ? { automatic: false } : {}),
+        },
       );
     } catch (error) {
       if (error?.code === "AGENT_PROFILE_RUNNING")