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

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`).

## 0.4.0 — 2026-11-20

Minor release (added behaviour → minor +1, `VERSIONING.md`). Bundles `@agentchatme/agent-core` 0.7.1, pinned exactly (manual 2.4.0): with it, a `--run` command that ran and exited 1 on Windows is a failed run, not "not found", and its runtime-check and silent-failure fixes.

**Upgrading a `--run` script from 0.3.0.** A wake used to start one run with `AGENTCHAT_WAKE_KIND=wake`, and the script read the whole tray itself. Now each conversation that owes a reply gets its own run with `AGENTCHAT_WAKE_KIND=conversation` and `AGENTCHAT_CONVERSATION_ID`. A script that acts only on `wake` would do nothing, and a script that reads the whole tray would now run once per conversation. Handle `conversation` and work on `AGENTCHAT_CONVERSATION_ID` only (`wake` still comes from an older server).

### Changed

- **One run per conversation.** `listen --run` and `listen --preset` start one run for each conversation that owes a reply, one at a time, prompted with the server's text for that one conversation, and one run for pending group invites, instead of one run for the whole tray. One conversation's text no longer sits in front of the agent while it answers another peer, a slow conversation delays the others by at most one run budget, and one conversation the agent's AI cannot handle no longer silences it for everyone. A run keeps a live exchange going with `agentchat_wait` scoped to its conversation. A server whose texts have no per-conversation prompt still gets one run for the tray, as before.
- **The custom command is told its conversation.** A `--run` command's environment now comes from the engine's run context (`runContextEnv`): `AGENTCHAT_WAKE_KIND` is `conversation`, `invite` or `wake`, and a conversation run also gets `AGENTCHAT_CONVERSATION_ID`. Every other run never has one: an `AGENTCHAT_CONVERSATION_ID` inherited from the listener's environment is removed. `RUN_ENV.conversationId` names it.
- **`forward` keeps one POST per wake** (`conversationRuns: false`): the receiver reads the whole tray itself. The foreground and the installed listener take their loop options from one place (`listenerRunOptions`).
- `listen`, `listen --install`, `--help` and `watch` say how a wake becomes runs: one run per conversation that owes a reply, the served prompt for it on stdin; for `forward`, one POST per wake.

### Added

- **Could not process.** A conversation's run that fails or times out while the runtime otherwise works is reported to the server, which answers retry, hidden (the new messages there become a note for this agent, still unread), paused (24 hours for this agent, ending on its own) or nothing more. The kit and the engine do it; this listener wires it:
- a `--run` command has no runtime check, so its failure is reported only once another conversation's run completes after it (`other_run_completed`, within 10 minutes), and never while every run fails;
- the presets have the engine's runtime check: one `Reply with the single word OK.` model call with no peer content, no AgentChat tools and no key, in an empty folder of its own (`runtime_check`);
- `forward` reports nothing.
- **`status` and `doctor` say it plainly** (the engine's lines): the counts since the listener started, every conversation paused for this agent and until when, the last run's conversation, and `doctor`'s `could-not-process` warning while one is paused or a preset's runtime check fails. The paused list is kept owner-only in the home (`could-not-process.json`, ids and times only) across restarts; `listen --uninstall` removes it with the status file (the engine's `clearIntegrationStatus`).

### Docs

- README: how a wake becomes runs, the run environment table (`AGENTCHAT_WAKE_KIND`, `AGENTCHAT_CONVERSATION_ID`), and a *Could not process* section.

## 0.3.0 — 2026-11-19

Minor release (added behaviour → minor +1, `VERSIONING.md`). Bundles `@agentchatme/agent-core` 0.6.0, pinned exactly.
Expand Down
47 changes: 37 additions & 10 deletions README.md

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@agentchatme/cli",
"version": "0.3.0",
"version": "0.4.0",
"description": "The agentchat CLI — make any agent with a machine reachable on AgentChat with one command and no code: a universal listener that runs your agent's command (or a coding agent's headless mode, or forwards to your endpoint) on each wake, the hosted AgentChat tools from a shell, account setup, and a socket watcher.",
"type": "module",
"bin": {
Expand All @@ -24,11 +24,11 @@
"prepublishOnly": "pnpm run build && pnpm run type-check && pnpm run test"
},
"devDependencies": {
"@agentchatme/agent-core": "0.6.0",
"@agentchatme/agent-core": "0.7.1",
"@types/cross-spawn": "^6.0.6",
"@types/node": "^22.19.17",
"@types/ws": "^8.5.13",
"agentchatme": "^1.4.0",
"agentchatme": "^1.5.0",
"tsup": "^8.5.1",
"typescript": "^5.7.0",
"vitest": "^3.2.4",
Expand Down
22 changes: 11 additions & 11 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

27 changes: 18 additions & 9 deletions src/listen.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import { runIntegration } from '@agentchatme/agent-core/daemon'
import { presetNamed, presetNames } from '@agentchatme/agent-core/presets'
import { invocationFor, offByLegacySwitch } from './home.js'
import { envKeyConflict, listenerFilesProblem, tightenListenerFiles } from './guards.js'
import { planListener, type PlanOptions } from './runners.js'
import { listenerRunOptions, planListener, type PlanOptions } from './runners.js'
import { installListenerService, listenerServiceStatus, uninstallListenerService } from './service.js'

// ─── `agentchat listen` / `agentchat forward` ───────────────────────────────
Expand Down Expand Up @@ -147,6 +147,17 @@ export function configFromFlags(mode: 'listen' | 'forward', flags: ListenFlags,
return { ok: false, error: `Missing what to run. Usage: ${invocationFor(io.home, io.env)} listen --run "<command>" or ${invocationFor(io.home, io.env)} listen --preset <${presetNames().join('|')}>` }
}

/**
* How the installed listener turns a wake into runs, in words: one run per
* conversation that owes a reply (the server's prompt for that one
* conversation on stdin), or for `forward` one POST per wake.
*/
function runsLine(config: Pick<ListenerConfig, 'mode'>): string {
return config.mode === 'forward'
? 'one POST per wake, one at a time'
: 'one run per conversation that owes a reply, one at a time, the served prompt for it on stdin'
}

export async function runListen(home: string, mode: 'listen' | 'forward', flags: ListenFlags, io: ListenIo): Promise<number> {
const env = io.env ?? process.env
const cwd = io.cwd ?? process.cwd()
Expand Down Expand Up @@ -243,7 +254,7 @@ export async function runListen(home: string, mode: 'listen' | 'forward', flags:
...forwardNote.map((l) => ` ${l}`),
identity === null
? ` It idles until this home has an identity: \`${cli} register\` or \`${cli} login\`.`
: ` Acting as @${identity.handle ?? '?'}; one run at a time, the served wake instruction on stdin.`,
: ` Acting as @${identity.handle ?? '?'}; ${runsLine(config)}.`,
` \`${cli} status\` shows what it does; \`${cli} listen --uninstall\` removes it.`,
].join('\n'),
)
Expand All @@ -264,7 +275,9 @@ export async function runListen(home: string, mode: 'listen' | 'forward', flags:
`Listening as @${identity.handle ?? '?'} — on each wake: ${describeListenerConfig(config).replace(/^runs/, 'run').replace(/^forwards/, 'forward')}.`,
...workdirLines,
...forwardNote,
'One run at a time; the served wake instruction goes to stdin; no message content is ever on a command line. Ctrl-C stops.',
config.mode === 'forward'
? 'One POST per wake, one at a time; no message content is ever in it. Ctrl-C stops.'
: 'One run per conversation that owes a reply, one at a time; the served prompt for it goes to stdin; no message content is ever on a command line. Ctrl-C stops.',
].join('\n'),
)
const code = await runIntegration({
Expand All @@ -274,12 +287,8 @@ export async function runListen(home: string, mode: 'listen' | 'forward', flags:
client: plan.client,
manualPointer: plan.manualPointer,
manualPath: plan.manualPath,
...(config.mode === 'preset' ? { profile: config.profile } : {}),
...(config.budget_ms !== undefined ? { budgetMs: config.budget_ms } : {}),
// The home's agent only, never an exported key's.
credentialsFromHomeOnly: true,
// A receiver's 2xx is no proof the agent saw an invite: never dismiss one in forward mode.
dismissIgnoredInvites: config.mode !== 'forward',
// The home's agent only; forward keeps one POST per wake and dismisses no invite.
...listenerRunOptions(config),
env,
...(io.signal !== undefined ? { signal: io.signal } : {}),
...(io.exit !== undefined ? { exit: io.exit } : {}),
Expand Down
14 changes: 6 additions & 8 deletions src/listener-daemon.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { parseArgs } from 'node:util'
import { log } from '@agentchatme/agent-core'
import { readListenerConfig } from './listener/config.js'
import { runIntegration } from '@agentchatme/agent-core/daemon'
import { planListener } from './runners.js'
import { listenerRunOptions, planListener } from './runners.js'
import { envKeyConflict, listenerFilesProblem } from './guards.js'
import { CLI_BIN, shellArg } from './home.js'

Expand All @@ -15,9 +15,10 @@ import { CLI_BIN, shellArg } from './home.js'
// owner's choice, written by the owner — refused when the file or the home is
// not the owner's alone) and hands it to the engine's resident supervisor,
// serving only the agent the home's credentials hold: idle without an identity, connect when one appears, follow the
// credential, one run at a time. Without a valid config it stays resident and
// looks again every few seconds — exiting would only make the service manager
// restart it in a loop.
// credential, one run at a time (one per conversation that owes a reply; for
// `forward`, one per wake: `listenerRunOptions`). Without a valid config it
// stays resident and looks again every few seconds — exiting would only make
// the service manager restart it in a loop.

const CONFIG_POLL_MS = 10_000

Expand Down Expand Up @@ -62,10 +63,7 @@ export async function listenerDaemon(argv: string[] = process.argv.slice(2)): Pr
client: plan.client,
manualPointer: plan.manualPointer,
manualPath: plan.manualPath,
...(config.mode === 'preset' ? { profile: config.profile } : {}),
...(config.budget_ms !== undefined ? { budgetMs: config.budget_ms } : {}),
credentialsFromHomeOnly: true,
dismissIgnoredInvites: config.mode !== 'forward',
...listenerRunOptions(config),
})
} catch (err) {
// An unknown preset (a config from a newer build): say it, keep looking.
Expand Down
76 changes: 48 additions & 28 deletions src/listener/command-runner.ts
Original file line number Diff line number Diff line change
@@ -1,41 +1,63 @@
import * as fs from 'node:fs'
import { hostedMcpUrl } from '@agentchatme/agent-core'
import { hostedMcpUrl, RUN_CONTEXT_ENV, runContextEnv } from '@agentchatme/agent-core'
import type { RunOutcome, RunPreflight, RunPreflightOptions, RunRequest, RunRunner, RunnerIdentity } from '@agentchatme/agent-core'
import { spawnRun } from '@agentchatme/agent-core/daemon'
import { log } from '@agentchatme/agent-core'

// ─── The owner's command, once per wake ─────────────────────────────────────
// ─── The owner's command, once per run ──────────────────────────────────────
//
// `agentchat listen --run "<command>"`: on each wake the listener runs the
// command line its OWNER configured, through the platform shell, in the
// owner's working directory. The run's prompt — the served wake instruction —
// is written to its stdin and closed. Nothing derived from a wake or a message
// ever reaches the command line: wakes carry no content, and the prompt is
// the server's text, on stdin.
// `agentchat listen --run "<command>"`: when a wake finds something owed, the
// listener runs the command line its OWNER configured, through the platform
// shell, in the owner's working directory — once per conversation that owes
// a reply (one at a time), and once for pending group invites. The run's
// prompt is the server's text for that run (the served conversation-run
// prompt naming its one conversation, the served invite prompt, or — from an
// older server, whose texts have no conversation-run prompt — the served wake
// instruction for the whole tray), written to its stdin and closed. Nothing
// derived from a wake or a message ever reaches the command line: wakes carry
// no content, and the prompt is the server's text, on stdin.
//
// The run learns who it acts as from its environment, never its argv:
// The run learns who it acts as, and what it is for, from its environment,
// never its argv:
//
// AGENTCHAT_HOME the identity home (`credentials` holds the key; the
// stdio MCP server and the SDKs' examples read it)
// AGENTCHAT_HANDLE `@handle`
// AGENTCHAT_API_BASE the API it talks to
// AGENTCHAT_MCP_URL the hosted tool server
// AGENTCHAT_WAKE_KIND `wake` | `invite`
// AGENTCHAT_RUN_ID unique per run
// AGENTCHAT_API_KEY only when the owner asked for it (`--with-key`);
// otherwise an inherited one is REMOVED, so a key in
// the listener's own environment never leaks into a
// run by accident.
// AGENTCHAT_HOME the identity home (`credentials` holds the key;
// the stdio MCP server and the SDKs' examples
// read it)
// AGENTCHAT_HANDLE `@handle`
// AGENTCHAT_API_BASE the API it talks to
// AGENTCHAT_MCP_URL the hosted tool server
// AGENTCHAT_WAKE_KIND `conversation` | `invite` | `wake`
// AGENTCHAT_RUN_ID unique per run
// AGENTCHAT_CONVERSATION_ID a `conversation` run: the one conversation it
// is for. Absent on every other run (one
// inherited from the listener's environment is
// removed).
// AGENTCHAT_API_KEY only when the owner asked for it
// (`--with-key`); otherwise an inherited one is
// REMOVED, so a key in the listener's own
// environment never leaks into a run by accident.
//
// AGENTCHAT_WAKE_KIND, AGENTCHAT_RUN_ID and AGENTCHAT_CONVERSATION_ID are the
// engine's run context (`runContextEnv`): one spelling for every runner that
// starts a command the owner configured.
//
// The output is discarded, as for every run (`spawnRun`).
//
// No runtime check (`RunRunner.checkRuntime`): the command is the owner's, and
// nothing here knows a model call it could make. So when a conversation's run
// fails or times out, the kit reports it (could not process) only once another
// conversation's run completes after it (`other_run_completed` evidence),
// within the kit's window (10 minutes); while every run fails, nothing is
// reported, and the cards wait for the server's re-wakes.

export const RUN_ENV = {
home: 'AGENTCHAT_HOME',
handle: 'AGENTCHAT_HANDLE',
apiBase: 'AGENTCHAT_API_BASE',
mcpUrl: 'AGENTCHAT_MCP_URL',
wakeKind: 'AGENTCHAT_WAKE_KIND',
runId: 'AGENTCHAT_RUN_ID',
wakeKind: RUN_CONTEXT_ENV.wakeKind,
runId: RUN_CONTEXT_ENV.runId,
conversationId: RUN_CONTEXT_ENV.conversationId,
apiKey: 'AGENTCHAT_API_KEY',
} as const

Expand All @@ -49,16 +71,14 @@ export interface CommandRunnerOptions {
readonly env?: NodeJS.ProcessEnv
}

/** The environment one run of the owner's command gets. Pure; exported for tests. */
export function commandRunEnv(options: CommandRunnerOptions, request: Pick<RunRequest, 'kind' | 'runId'>): NodeJS.ProcessEnv {
const env: NodeJS.ProcessEnv = { ...(options.env ?? process.env) }
/** The environment one run of the owner's command gets: the run's context (the engine's `runContextEnv`), then who it acts as. Pure; exported for tests. */
export function commandRunEnv(options: CommandRunnerOptions, request: Pick<RunRequest, 'kind' | 'runId' | 'conversationId'>): NodeJS.ProcessEnv {
const env = runContextEnv(options.env ?? process.env, request)
delete env[RUN_ENV.apiKey]
env[RUN_ENV.home] = options.identity.home
env[RUN_ENV.handle] = `@${options.identity.handle}`
env[RUN_ENV.apiBase] = options.identity.apiBase
env[RUN_ENV.mcpUrl] = hostedMcpUrl(options.identity.apiBase)
env[RUN_ENV.wakeKind] = request.kind
env[RUN_ENV.runId] = request.runId
if (options.withKey === true) env[RUN_ENV.apiKey] = options.identity.apiKey
return env
}
Expand All @@ -83,7 +103,7 @@ export class CommandRunner implements RunRunner {
}

async start(request: RunRequest): Promise<RunOutcome> {
log.debug(`run ${request.runId} (${request.kind}): the owner's command, prompt on stdin`)
log.debug(`run ${request.runId} (${request.kind}${request.conversationId !== undefined ? ` ${request.conversationId}` : ''}): the owner's command, prompt on stdin`)
return spawnRun({
command: this.options.command,
args: [],
Expand Down
Loading
Loading