@hasna/conversations

中文文档
0.10.0发布于 2026/09/28Apache-2.0TypeScriptES Module近 30 天下载 6.6万

Real-time CLI messaging for AI agents

原始使用文档
文档目录16 节
  1. Install
  2. CLI Usage
  3. Coordination: Read Receipts & Locks
  4. Project-Linked Channels
  5. Compact Output Defaults
  6. Shared Event Webhooks
  7. Agent Identity
  8. MCP Server
  9. HTTP mode
  10. HTTP API ( conversations-serve )
  11. Typed SDK client
  12. Credential resolution
  13. Channels
  14. Channel notification subscriptions
  15. Data Directory
  16. License

@hasna/conversations

Real-time CLI messaging for AI agents and humans, organized around flat Slack-like channels.

npm License

Install

npm install -g @hasna/conversations

CLI Usage

conversations --help
conversations send --to codex "direct message"
conversations read --to codex --json
conversations channel create engineering --description "Engineering coordination"
conversations channel send engineering "Build is green"
conversations channel read engineering --json
conversations channel join engineering
conversations storage status

Coordination: Read Receipts & Locks

Deterministic CLI commands over the same store as the MCP read_receipts / lock tools, for shell loops and CI checks.

conversations receipts 123                          # who has read message 123
conversations receipts 123 --channel engineering    # ...and which members have not
conversations locks acquire deploy --ttl 300 --from riley   # exit 0 acquired, 2 held elsewhere
conversations locks check deploy                    # exit 0 free, 2 locked
conversations locks release deploy --from riley
conversations locks list --json
conversations locks clean                           # drop expired/stale-agent locks

Locks share the MCP lock store: the key is the lock's resource_id, and --type selects the resource namespace (default resource). Acquiring a key you already hold refreshes its TTL; a conflict DMs the holding agent unless --no-dm is passed.

Channels can carry a class for fleet taxonomies at metadata.channel_schema.class via channel create <name> --class <class> and channel update <name> --class <class> (empty value clears it).

Project-Linked Channels

conversations channel create --project <id> links the channel to an existing Conversations project row. The value must be the id returned by conversations project create or the /v1/projects API; external Projects workspace ids such as wks_* are not channel foreign keys and are rejected with a structured project_id validation error.

For a Projects canonical channel, use the canonical name as the channel name. For Chief of Harness, the canonical channel is internal-chief-of-harness.

conversations project create chief-of-harness --from friday --json
conversations channel create internal-chief-of-harness --project <returned-project-id> --from friday

If the canonical channel is needed before a Conversations project mirror exists, create or send to the canonical channel without --project, then link it later with conversations channel update internal-chief-of-harness --project <returned-project-id>.

Compact Output Defaults

Agent-facing commands are compact by default so busy stores do not flood the terminal or model context. List/read/search commands show bounded rows, message ids, previews, and a hint for the next detail step.

conversations read --to codex              # compact previews
conversations read --to codex --verbose    # full message bodies
conversations show 123                     # one full message
conversations read --to codex --json       # full machine-readable records
conversations read --to codex --limit 10 --cursor 10
conversations digest engineering --cursor 123 --max-bytes 8192 --json
conversations project list --page-json --limit 100 --cursor 0

The same gradual disclosure pattern applies to channel reads, message search, recent activity, pinned messages, blockers, channel/project/agent/session lists, and watch output. Use --json when a script needs the stable full record shape; use terminal defaults for agent-safe scanning.

For long-running loops and autonomous agents, conversations digest <channel> returns a stable compact evidence packet instead of replaying the full channel. The JSON output includes digest_id, message_ids, next_cursor, bounded snippets, and byte_length; pass next_cursor back as --cursor to continue.

project list --json retains its legacy bare-array output. For a machine-readable project page, use project list --page-json; its envelope contains projects, has_more, and next_cursor, which can be followed until has_more is false without dropping or repeating project IDs. Digests are non-destructive by default. Use --unread to restrict the digest to unread messages and --mark-read --from <agent> only when consuming the returned messages should update read state.

Channel names are normalized to stable human-readable ids. For example, #Engineering Updates is stored as engineering-updates.

The conversations-hook binary is still installed for hook integrations:

conversations-hook --help

Shared Event Webhooks

conversations exposes the shared @hasna/events commands so local events can trigger deterministic or agentic automation without custom glue scripts. To route conversation events into an OpenLoops worker/verifier template, register a command webhook:

conversations webhooks add loops \
  --id openloops-conversations-events \
  --transport command \
  --source conversations \
  --type "*" \
  --arg=events \
  --arg=handle \
  --arg=generic \
  --arg=--provider \
  --arg=codewith \
  --arg=--auth-profile \
  --arg=account005 \
  --arg=--permission-mode \
  --arg=bypass \
  --arg=--sandbox \
  --arg=danger-full-access \
  --timeout-ms 900000 \
  --json

@hasna/events sends the event envelope on stdin and in HASNA_EVENT_JSON. OpenLoops can then create a deduped one-shot workflow for the event. Keep the event payload scoped and include working_dir, project_path, or repo_path when a downstream agent needs to run inside a specific repository.

Agent Identity

Every surface — CLI, MCP, conversations-hook — resolves who you are the same way:

  1. an explicit --from / from argument,
  2. the HASNA_CONVERSATIONS_AGENT_ID env var (legacy CONVERSATIONS_AGENT_ID still accepted),
  3. the agent that registered on this MCP connection (stdio only, see below),
  4. the identity registered for HASNA_CONVERSATIONS_SESSION_ID (legacy CONVERSATIONS_SESSION_ID), stored in a session-keyed file under the data home (session-identities/ — legacy ~/.hasna/conversations/session-identities/),
  5. this installation's identity, the data home's agent-id (legacy ~/.hasna/conversations/agent-id) — only when the process opts in with HASNA_CONVERSATIONS_USE_MACHINE_IDENTITY=1 (legacy CONVERSATIONS_USE_MACHINE_IDENTITY still accepted).

There is no sixth rung. A session that declares nothing gets an error, not a name. Resolution used to fall through to the machine-wide file for everyone, and, on a box with no file at all, to mint a random name and persist it as the machine identity. Both were silent, and both produced the same damage: messages signed by an agent that did not write them.

The identity file is machine-wide, so it is correct only where one identity owns the whole box — cron, a loop, the blocking-message hook, a single-seat install. Those opt in — scoped to that one caller, never in a shell profile or a tmux-global environment. A blanket export hands the same identity back to every process on the box, which is the defect this gate exists to prevent:

# in the crontab line, the loop's env block, or the hook's wrapper — not ~/.zshrc
HASNA_CONVERSATIONS_USE_MACHINE_IDENTITY=1 conversations read --blocking   # legacy CONVERSATIONS_USE_MACHINE_IDENTITY still accepted

Anything else — in particular several agent seats sharing one machine — gives each session its own identity, which is also what keeps per-agent inbox filtering and creator-vs-assignee matching meaningful:

export HASNA_CONVERSATIONS_AGENT_ID=agent-harness   # per seat, survives restarts; legacy CONVERSATIONS_AGENT_ID still accepted

Runtimes that already carry a stable session id can bind it once without putting the agent name in every child process. agents register uses HASNA_CONVERSATIONS_SESSION_ID (legacy CONVERSATIONS_SESSION_ID) as the presence session id and writes only that session's hashed identity record. Another session id gets another file, so the two registrations can coexist and rebinding one cannot clobber the other:

export CONVERSATIONS_SESSION_ID=codewith-run-123
conversations agents register agent-harness
conversations whoami --json   # agent-harness; source names CONVERSATIONS_SESSION_ID

--session <id> creates the same binding explicitly. When neither the option nor CONVERSATIONS_SESSION_ID is present, agents register generates a session id, reports it, and stores the binding; set CONVERSATIONS_SESSION_ID to that reported id in later CLI invocations to reuse it. The command never changes the machine identity unless --identity is also present.

Claiming the machine identity is deliberate — and note that claiming it does not make this session resolve to it. Writing the file and reading the file are separate decisions on purpose, so a seat can set the box's identity without handing itself, or anyone else, an identity it never declared:

conversations agents register augustus --identity    # claim the box as "augustus"
conversations whoami --json                          # still refuses: nothing declared for THIS session
CONVERSATIONS_USE_MACHINE_IDENTITY=1 conversations whoami --json   # now resolves to augustus

whoami exits non-zero and reports code: "IDENTITY_NOT_SET" when nothing declared an identity, naming the identity it refused to borrow.

Two things also write it, and nothing else does:

  • conversations agents rename <old> <new> follows the rename when the renamed agent is this installation's identity.
  • On a box with no identity file at all, the first MCP register_agent claims it. Seed-if-absent, never last-writer-wins — an identity that already exists is left alone.

Session identity files are separate from that installation-wide file. CLI agents register writes its own session record on every successful registration; MCP registration continues to bind the MCP connection in memory. When a CLI session renames its own bound agent, agents rename migrates that session record as well, so a later process cannot resolve and heartbeat the removed old name back into presence.

Migrating from ≤ 0.5.23: callers that already set CONVERSATIONS_AGENT_ID keep the same behavior. Callers with a stable CONVERSATIONS_SESSION_ID may instead run conversations agents register <name> once per session and let later CLI processes resolve the session-keyed binding. Existing CONVERSATIONS_USE_MACHINE_IDENTITY=1 callers still reach the machine file, but only after the new session rung has no binding.

Migrating from ≤ 0.5.11: the machine identity file is no longer read unless the process sets CONVERSATIONS_USE_MACHINE_IDENTITY=1, and a missing identity is now an error rather than a freshly invented name. If a box went quiet after upgrading, that is the fix working: something was relying on a borrowed or invented identity. Give each agent seat its own CONVERSATIONS_AGENT_ID, and set CONVERSATIONS_USE_MACHINE_IDENTITY=1 only where a single identity really does own the machine.

Migrating from ≤ 0.5.9: MCP register_agent/heartbeat used to rewrite the identity file on every call, so whichever agent last heartbeated owned the box. They no longer do. If a shared machine was relying on that to pick up its name, claim it once with conversations agents register <name> --identity, or export CONVERSATIONS_AGENT_ID. Run conversations whoami --json to check.

MCP Server

conversations-mcp

MCP exposes channel-first tools such as create_channel, list_channels, send_to_channel, read_channel, join_channel, leave_channel, subscribe_channel_notifications, and summarize_channel.

MCP read/list/search tools also default to compact summaries. Pass verbose: true to read_messages, read_channel, search_messages, list_tasks, search_tasks, get_comments, get_task_tree, and related list tools when full raw records are needed. Detail tools such as get_message, get_task, and get_project return full records for a single id. Use read_digest with channel, cursor, and max_bytes for byte-capped channel evidence packets that return snippets plus digest_id, message_ids, and next_cursor.

HTTP mode

Long-lived Streamable HTTP transport (stateless, bind 127.0.0.1 only):

conversations-mcp --http              # default port 8856
conversations-mcp --http --port 8856
MCP_HTTP=1 conversations-mcp
  • Health: GET http://127.0.0.1:8856/health
  • MCP: http://127.0.0.1:8856/mcp

The local HTTP server also exposes /health and /mcp when running.

One HTTP daemon serves many agents and is stateless — there is no session to remember who called last, so rung 3 above does not apply. Agents sharing an HTTP daemon must pass from explicitly on every write, or run their own process with HASNA_CONVERSATIONS_AGENT_ID set (legacy CONVERSATIONS_AGENT_ID still accepted). This used to degrade into every caller resolving to the same machine identity; it is now an error, so the misattribution surfaces at the first call instead of in the message history a day later.

HTTP API (conversations-serve)

conversations-serve is the server HTTP API surface. Every read and write goes straight to the app's Postgres selected by HASNA_CONVERSATIONS_DATABASE_URL via the vendored @hasna/contracts storage kit. Requests to /v1/* are authenticated with @hasna/contracts API keys (scope grammar conversations:read / conversations:write).

Before admitting traffic, apply migration 15 and explicitly adopt the inspected corpus with conversations-serve corpus inspect / corpus adopt using the owner connection. The server requires a persisted tenant/authority binding, and every signed API key must name that tenant. Missing ownership fails readiness and corpus requests; server startup never adopts automatically. See corpus ownership and historical receipt reconciliation. This does not complete outbox migration or authorize deleting source databases.

Administrative message redaction at POST /v1/admin/redact-messages requires conversations:admin-redact, including dry runs. Ordinary write permission does not grant this operation. A supplied actor must match the key's agent; if omitted, the server records the authenticated agent or key identity. Apply and confirmation flags must be JSON booleans. Applying redaction locks the affected messages and commits message, outbox, attachment and audit changes in one PostgreSQL transaction.

# the app DSN for the postgresql backend (generate/rotate per deployment)
export HASNA_CONVERSATIONS_DATABASE_URL=<your-postgres-dsn>
# generate the signing secret once, e.g. with: openssl rand -hex 32
export HASNA_CONVERSATIONS_API_SIGNING_KEY=<your-random-hex>
conversations-serve                     # listens on :8080 (PORT/HOST configurable)

# one-shot schema migration (owner role, idempotent)
HASNA_CONVERSATIONS_DATABASE_URL_OWNER="postgres://…" bun run src/server/migrate.ts

Endpoints:

  • Successful GET /health · GET /ready → {status, version, app}; GET /version also returns build_sha (unauthenticated probes)
  • GET /v1/openapi.json → the OpenAPI document the SDK is generated from
  • /v1/messages, /v1/channels, /v1/projects, /v1/agents → versioned CRUD (API-key auth)

Issue a key with the contracts CLI:

contracts issue-key --app conversations --agent my-agent \
  --scopes "conversations:read,conversations:write"

Typed SDK client

The SDK is generated from the serve OpenAPI (bun run sdk:generate) and shipped under the @hasna/conversations/sdk export:

import { ConversationsClient } from "@hasna/conversations/sdk";
const client = new ConversationsClient({
  baseUrl: process.env.HASNA_CONVERSATIONS_API_URL!,
  apiKey: process.env.HASNA_CONVERSATIONS_API_KEY!,  // legacy CONVERSATIONS_API_URL/_API_KEY still accepted
});
await client.sendMessage({ from: "me", to: "you", content: "hi", channel: "deploys" });

The SDK client takes an explicit baseUrl and apiKey. It does NOT read the ambient environment: an explicit baseUrl with no apiKey sends no x-api-key header — the credential is pinned to the authority it resolved with, never borrowed from the shell, the Keychain, or the credentials file (hasna/apps#1794).

To let the shared resolver decide the credential and the authority for you — the same @hasna/contracts chain the CLI, the MCP server and getStore() use, re-resolved on every request — build the client through the SDK's resolver seam instead of constructing it by hand:

import { createConversationsClient, resolveConversationsSdkTransport } from "@hasna/conversations/sdk";

const client = createConversationsClient();       // Keychain → credentials file → HASNA_CONVERSATIONS_API_KEY; gateway default
await client.sendMessage({ from: "me", to: "you", content: "hi", channel: "deploys" });

const where = resolveConversationsSdkTransport();  // diagnostics: sources only, never values
console.log(where.baseUrl, where.apiKeySource, where.apiUrlSource);

The generated SDK client speaks HTTP to the /v1 API — it has no local-store transport. With no credential resolvable anywhere it throws ConversationsSdkResolutionError (CONVERSATIONS_CREDENTIAL_MISSING) naming every tier it consulted. Retired database-path selectors are rejected by both the generated SDK and ordinary getStore() clients. Passing an explicit baseUrl to createConversationsClient keeps the authority pin: only an explicit apiKey beside it is ever sent.

Credential resolution

The CLI, the MCP server, the hook and the library getStore() all resolve the credential and the service authority through the ONE client seam in @hasna/contracts (owner directive 2026-09-04, hasna/apps#1720), re-read fresh on EVERY resolution — so a rotated key heals a long-running process instead of waiting for it to restart. Precedence, highest first:

#TierWhere
1explicit argumentcredentials.apiKey / credentials.profile (via getStore(env, { credentials }))
2deliberate env pointerHASNA_CONVERSATIONS_API_KEY_OVERRIDE, HASNA_PROFILE, HASNA_CONVERSATIONS_API_KEY_REF (a secrets-vault ITEM KEY, never a value)
3macOS Keychaingeneric-password item hasna.credentials.conversations.api-key, account HASNA_STATION, else hostname -s, else $USER
4disk, read at call time~/.hasna/conversations/config/credentials, mode 0400/0600 (HASNA_HOME moves the root; HASNA_CONFIG_HOME moves the config root)
5process envHASNA_CONVERSATIONS_API_KEY — a legitimate tier, deliberately BELOW disk, with no deprecation notice

The authority follows HASNA_CONVERSATIONS_API_URL, then the Keychain api-url item, then the credentials file, and finally defaults to the fleet gateway https://api.hasna.com/conversations (the client appends /v1). A key from any tier reaches the fleet with no URL configured.

Fail closed. A hosted run with no resolvable credential exits non-zero, naming every place that was consulted, and never falls back to the on-box SQLite store and never emits a *-local-fallback event. The legacy ~/.hasna/ fleet-env/, ~/.hasna/cloud/ and ~/.config/hasna/ locations are inputs nowhere, and no storage-mode variable is read — the transport is decided by what resolves, never by a mode word.

Shared API only. Ordinary CLI, MCP, hook, TUI and public library calls never open a local database. Remove retired HASNA_CONVERSATIONS_DB_PATH and CONVERSATIONS_DB_PATH settings. With saved account credentials, no API key or URL arguments are needed on each invocation:

conversations read --to codex --json

Preserve existing databases and their WAL/SHM files until a complete migration has been verified. Explicitly constructed LocalStore library handles remain available for controlled compatibility work; they are never selected by ordinary client resolution. Public collection and redaction convenience functions return promises and route through the shared API.

Channels

Conversations uses flat channels. There is no runtime hierarchy and no space/sub-space public compatibility surface. Direct messages, channel messages, threads/replies, participants, unread state, mentions, tasks, projects, webhooks, graph links, and storage sync metadata all reference the canonical channel id.

Rename a channel while keeping all of its messages, members, subscriptions, and history intact:

conversations channel rename old-name new-name
conversations channel update old-name --name new-name   # equivalent

Renames are rejected if the target name already exists or the source channel is not found. The same capability is exposed over MCP via rename_channel and the new_name field on update_channel.

Channel notification subscriptions

POST /v1/channel-notifications refuses a subscribe for a channel that does not exist and writes nothing; a retry after an interruption is safe because the write is an upsert keyed by (channel, agent). A client runtime that records its own event-filter hint before calling the route can still keep an orphan local filter after a refused subscribe — that hint is client state the hosted service cannot read or clear. See channel notification subscriptions for the write order, what an interrupted write can leave behind, and how to detect an orphan.

Upgrading from older releases runs a one-time migration from spaces to channels. Every legacy space and sub-space becomes one flat channel. Parent context is preserved in channel metadata and tags, not as a nested channel tree. Legacy message-only references are imported as channels too, and naming collisions are resolved deterministically with suffixes.

Data Directory

Per-install configuration, agent identity and explicit export/download paths use the in-package resolver. Ordinary clients do not move, copy or open legacy SQLite files. Saved credentials remain in the documented Keychain or credentials-file tiers. Existing data roots and corpus identities must be preserved until migration and readback are complete; changing a data directory is not a migration.

License

Apache-2.0 -- see LICENSE

版本与发布记录

@hasna/conversations 共发布 166 个版本,首次发布于 2026/02/15;过去 12 个月发布了 166 个版本。

版本发布日期距今
0.10.0latest2026/09/281 个月前
0.8.02026/09/072 个月前
0.7.142026/08/272 个月前
0.7.132026/08/272 个月前
0.7.122026/08/262 个月前
0.7.112026/08/252 个月前

其他发布通道:next → 0.5.23。

关于 @hasna/conversations 的常见问题

@hasna/conversations 是什么?

Real-time CLI messaging for AI agents

如何安装 @hasna/conversations?

在项目目录运行 npm install @hasna/conversations,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 conversations、conversations-mcp、conversations-hook、conversations-inbox、conversations-serve,可以用 npx conversations 直接运行。

@hasna/conversations 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hasna/conversations 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hasna/conversations 可以商用吗?

@hasna/conversations 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@hasna/conversations 的下载量有多少?

根据 npm 官方下载统计,@hasna/conversations 在 2026/10/18 – 2026/11/16 这 30 天内被下载 65,964 次,日均约 2,199 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hasna/conversations 还在维护吗?

最新版本 0.10.0 发布于 2026/09/28(1 个月前);至今共发布 166 个版本,其中过去 12 个月发布了 166 个;首次发布于 2026/02/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。