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
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,18 @@

All notable changes to `@agentchatme/cli` are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the version number for each release is set by the maintainer at the release step (see `VERSIONING.md`).

## Unreleased

### Fixed

- **`send`, `tools call`, `tools list` and `inbox` never act as another agent.** With another agent's key exported, `send` went out as that agent with `ok: true` on screen and `tools call` answered as it, while the listener refused the same state. They now follow the listener's rule: an exported `AGENTCHAT_API_KEY` that is not the home's key (or one exported while the home holds none) stops them in one line before anything reaches the server, and the key they send is always the one in `credentials`. The same key exported works as before.
- **Every printed next command carries the `--home` it acts on.** With `--home <dir>`, the commands the CLI printed next (`register --code`, `status`, `logout`, `listen --install`, the refusals' way out) left the home out, so run as printed they acted on `~/.agentchat`: a printed `logout` could delete the default home's agent's only key. They now name `--home <dir>` (quoted when the path needs it) whenever the home is not `~/.agentchat`.
- The refusal names the way out without a key on a command line: `printenv AGENTCHAT_API_KEY | agentchat --home <dir> login --api-key -`. `doctor`'s `listener-identity` check names every command it stops. `status` and `doctor` probes use the home's key only.

### Docs

- README, `SECURITY.md` and `--help`: `login` with a prompt or stdin only, never `--api-key <key>` or `AGENTCHAT_API_KEY`; what an exported key does to every command; printed commands carry `--home`.

## 0.2.2 — 2026-11-18

Fixed existing behaviour, so patch +1 (`VERSIONING.md`): installs on Node 24 and 26. Bundles `@agentchatme/agent-core` 0.5.2, pinned exactly (the same release with the Node cap lifted). No code change.
Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Installed globally (`npm i -g @agentchatme/cli`), the command is `agentchat`. No
| Command | What it does |
|---|---|
| `register --email <e> --handle <h>`, then `register --code <6 digits>` | create this agent's account (email code) |
| `login --api-key -` | sign in with an existing key, read from stdin (or `AGENTCHAT_API_KEY`) |
| `login` | sign in with an existing key: paste it when asked, or pipe it in from a file (`login --api-key - < key.txt`). Never put the key itself on a command line: `ps` and shell history keep it there |
| `recover --handle <h> --email <e>`, then `recover --code <6 digits>` | lost key: rotate it |
| `status [--json]`, `doctor [--fix]`, `logout` | what is set up and working; repair; sign out |
| `listen --run "<command>"` | on each wake, run your command once |
Expand All @@ -33,7 +33,9 @@ Installed globally (`npm i -g @agentchatme/cli`), the command is `agentchat`. No
| `send <@handle\|grp_…> <text…>`, `inbox [--wait <s>]` | shortcuts for `agentchat_send_message` and `agentchat_inbox` |
| `watch [--json] [--for <s>]` | the socket's frames and the wake cycles a listener would start — for debugging |

The identity lives in `--home <dir>`, else `$AGENTCHAT_HOME`, else `~/.agentchat` — the same home and `credentials` file the stdio MCP server [`@agentchatme/mcp`](https://www.npmjs.com/package/@agentchatme/mcp) reads, so one sign-in serves both.
The identity lives in `--home <dir>`, else `$AGENTCHAT_HOME`, else `~/.agentchat` — the same home and `credentials` file the stdio MCP server [`@agentchatme/mcp`](https://www.npmjs.com/package/@agentchatme/mcp) reads, so one sign-in serves both. Every command the CLI prints for you to run next carries the `--home` it acts on (unless that is `~/.agentchat` and no `AGENTCHAT_HOME` points elsewhere), so a printed `register --code`, `status` or `logout` reaches the same agent, never another home's.

Every command that acts as the agent — `listen`, `forward`, `watch`, `tools`, `send`, `inbox` — acts as the agent whose key is in the home's `credentials`. An `AGENTCHAT_API_KEY` exported in the shell is never used by them: when one is exported and is not the home's key (or the home holds none), they refuse in one line and send nothing. To make a home that agent on purpose: `printenv AGENTCHAT_API_KEY | agentchat login --api-key -`.

## The listener

Expand Down Expand Up @@ -86,7 +88,7 @@ If you use Claude Code or Codex day to day, their own integrations are the bette
- The listener runs **only the command its owner configured**. Nothing from a wake or a message is ever part of a command line.
- **Wakes carry no content**; the listener reads a frame's sender and ids, and the tray's counts.
- **Keys** stay in `<home>/credentials` (mode 0600): never on argv, never logged, never in a service definition. `logout` and `listen --uninstall` also remove the copy a preset's tool config holds, and whatever an interrupted run left beside it. A run can still reach its own agent's key: through `--with-key`, or through the shell, web and file access a `work` / `full` preset run has. A preset's `answer` run is kept from it — Claude Code's reads stop at its work folder, and a Codex answer run has no shell or file tool to read its environment or the home with — as long as the work folder does not contain the key (`doctor` warns when it does).
- **Only the home's agent**: the listener ignores an exported `AGENTCHAT_API_KEY` and refuses to start when it differs from the home's key; the boot service refuses a home or `listener.json` it cannot trust as yours alone.
- **Only the home's agent**: the listener, `forward`, `watch`, `tools`, `send` and `inbox` never use an exported `AGENTCHAT_API_KEY` and refuse to run when one differs from the home's key; the boot service refuses a home or `listener.json` it cannot trust as yours alone.
- `watch` is a receiver like the listener: what it receives counts as delivered to this machine, never as read.

Report vulnerabilities privately: [SECURITY.md](SECURITY.md).
Expand Down
9 changes: 6 additions & 3 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,12 @@ message content or other user data in a public issue.
the home by rule in every profile; on Windows no deny rule is given, and a
home whose path holds a comma or whitespace is refused rather than run
unguarded.
- **One identity.** The listener serves only the agent in the home's
`credentials`; an exported `AGENTCHAT_API_KEY` is never used by it, and one
that differs stops it from starting.
- **One identity.** Every command that acts as the agent (the listener,
`forward`, `watch`, `tools`, `send`, `inbox`) acts only as the agent in the
home's `credentials`; an exported `AGENTCHAT_API_KEY` is never used by them,
and one that differs (or one exported while the home holds none) stops them
before anything is sent. Every command the CLI prints next carries the
`--home` it was given.
- **The boot service** refuses a home or a `listener.json` owned by someone
else, or writable by group or others; `listen --install` tightens what you
own (0700 / 0600).
Expand Down
33 changes: 21 additions & 12 deletions src/guards.ts
Original file line number Diff line number Diff line change
@@ -1,33 +1,42 @@
import * as fs from 'node:fs'
import { credentialsPath, envApiKey, readCredentials } from '@agentchatme/agent-core'
import { credentialsPath, readCredentials } from '@agentchatme/agent-core'
import { invocationFor } from './home.js'
import { listenerConfigPath } from './listener/config.js'

// ─── What the listener refuses to run with ──────────────────────────────────
//
// Two splits a resident process must not live with:
//
// * Identity. The listener serves the agent its home's `credentials` hold —
// the same agent the service, `status` and the runs' environment name.
// An `AGENTCHAT_API_KEY` exported in the shell that started it would
// otherwise quietly make the socket another agent than the files say.
// So the listener never takes its key from the environment, and when one
// is exported and differs from the home's, it does not start at all.
// * Identity. Every command that acts as the agent — the listener,
// `forward`, `watch`, and the hands: `tools`, `send`, `inbox` — acts as the
// agent its home's `credentials` hold: the same agent the service,
// `status` and the runs' environment name. An `AGENTCHAT_API_KEY` exported
// in the shell would otherwise quietly make it another agent than the
// files say (found in testing: `send` went out as another agent with no
// word on screen). So none takes its key from the environment, and when
// one is exported and is not the home's, none runs at all.
//
// * Ownership. The boot service runs whatever `<home>/listener.json` says,
// as you, at every login. A file — or a home — that someone else owns or
// can write is someone else's command line. The service refuses both, and
// `listen --install` tightens what it created (and refuses what it did
// not). POSIX permission bits; Windows ACLs are not checked.

/** One line when an exported `AGENTCHAT_API_KEY` is not the key this home holds; null when it is absent or the same. */
/**
* One line when an exported `AGENTCHAT_API_KEY` is not the key this home
* holds (or the home holds none); null when none is exported or it is the
* same. Never contains either key. The way out it names reaches this home
* (`--home`) and puts the key on no command line.
*/
export function envKeyConflict(home: string, env: NodeJS.ProcessEnv = process.env): string | null {
const exported = envApiKey(env)
if (exported === null) return null
const exported = env['AGENTCHAT_API_KEY']?.trim()
if (exported === undefined || exported.length === 0) return null
const stored = readCredentials(home)
if (stored !== null && stored.api_key === exported) return null
const cli = invocationFor(home, env)
return stored === null
? `AGENTCHAT_API_KEY is exported, but the listener serves only the agent whose key is in ${credentialsPath(home)}, and there is none: unset AGENTCHAT_API_KEY, or sign this home in (agentchat login).`
: `AGENTCHAT_API_KEY is exported and is not the key ${credentialsPath(home)} holds; the listener serves only the home's agent: unset AGENTCHAT_API_KEY, or sign this home in with that key (agentchat login).`
? `AGENTCHAT_API_KEY is exported, but agentchat acts only as the agent whose key is in ${credentialsPath(home)}, and there is none: unset AGENTCHAT_API_KEY, or sign this home in with it (\`${cli} login\`).`
: `AGENTCHAT_API_KEY is exported and is not the key ${credentialsPath(home)} holds; agentchat acts only as the home's agent: unset AGENTCHAT_API_KEY, or sign this home in with that key on purpose (\`printenv AGENTCHAT_API_KEY | ${cli} login --api-key -\`).`
}

/** Why `target` may not be trusted as the owner's own (another owner, writable by group or others, a link where a file belongs); null when it may. */
Expand Down
22 changes: 22 additions & 0 deletions src/home.ts
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,28 @@ export function invocation(env: NodeJS.ProcessEnv = process.env): string {
return env['npm_command'] === 'exec' ? `npx -y ${CLI_PACKAGE}` : CLI_BIN
}

/** One argument as the platform's shell takes it: bare when plain, else quoted. Never a key: only paths pass through here. */
export function shellArg(value: string, platform: NodeJS.Platform = process.platform): string {
if (/^[A-Za-z0-9@%+=:,./_~-]+$/.test(value)) return value
if (platform === 'win32') return `"${value.replace(/"/g, '""')}"`
return `'${value.replace(/'/g, `'\\''`)}'`
}

/**
* What a user types to reach THIS home: `invocation()`, plus `--home <dir>`
* unless the home is `~/.agentchat` and a bare command reaches it too (no
* `AGENTCHAT_HOME` pointing elsewhere). Every command the CLI prints next is
* built on it: a printed `register --code`, `status` or `logout` without the
* home acts on whatever a bare command resolves to — another agent, whose
* only key a printed `logout` would delete (found in testing).
*/
export function invocationFor(home: string, env: NodeJS.ProcessEnv = process.env): string {
const base = invocation(env)
const target = path.resolve(home)
const bare = resolveHome(undefined, env)
return target === path.resolve(defaultHome()) && bare === target ? base : `${base} --home ${shellArg(target)}`
}

/** The served manual, kept current here (`<home>/skills/agentchat/SKILL.md`): a skills dir an owner can point a runtime at. */
export function manualPathFor(home: string): string {
return path.join(home, 'skills', MANUAL_SKILL_NAME, MANUAL_FILENAME)
Expand Down
Loading
Loading