negotium 0.1.17 → 0.1.19

package/README.md

@@ -14,9 +14,8 @@ negotium status
 negotium stop
 negotium telegram
 negotium otium join <invite-code>
-negotium start terminal
-negotium start telegram  # separate shell
-negotium start otium     # separate shell
+negotium serve otium     # separate shell
+negotium -v
 ```
 
 Authenticate Claude with `claude`, Codex with `codex login`, or Maestro with
@@ -47,6 +46,215 @@ import {
 These subpaths are the stable public boundary. Paths under `negotium/dist/` are package internals
 and may change between releases.
 
+## Context warning policy
+
+Embedding hosts can share Negotium's provider-neutral 80% context warning policy while adapting
+the command guidance to their own capabilities:
+
+```ts
+import {
+  claudeRequestContextTokens,
+  createContextWarningState,
+  nextContextWarning,
+} from "negotium/runtime-helpers";
+
+const warningState = createContextWarningState(); // owned by this host/runtime
+const contextTokens = claudeRequestContextTokens(claudeMessageUsage);
+const alert = nextContextWarning(warningState, {
+  key: `${userId}:${topicId}`,
+  topicTitle,
+  usage: { contextTokens, contextWindow },
+  supportsCompact: false, // legacy Otium currently guides users to /new only
+});
+```
+
+Call `clearContextWarning(warningState, key)` when that consumer starts a fresh provider session.
+The helper has no process-global dedupe state, so separate runtimes cannot suppress each other's
+alerts.
+
+## Shared runtime utilities
+
+Small provider-neutral helpers that otherwise tend to drift between embedding hosts are also
+available from the same public boundary:
+
+```ts
+import {
+  deepMapStrings,
+  delay,
+  errorResult,
+  errMsg,
+  isSensitivePath,
+  mcpError,
+  mcpOk,
+  parseUserIdArg,
+  sanitizeFileName,
+  sanitizeId,
+  sanitizeTopicName,
+  textResult,
+  topicAppLink,
+  topicMarkdownLink,
+} from "negotium/runtime-helpers";
+```
+
+These exports are stateless or caller-owned. Process singleton utilities such as logging,
+configuration, SQLite ownership, and outbox watchers remain excluded. Lifecycle reuse is available
+only through `createLifecycleManager({ logger, process })`, which keeps handlers and signal hooks
+owned by the embedding host.
+
+Maintainers can measure source overlap against an embedding host and fail on regressions with:
+
+```sh
+bun run audit:runtime-overlap \
+  --source=packages/core/src \
+  --consumer=/path/to/otium/apps/runtime-api/src \
+  --max-exact=0 --max-95=4 --max-80=14
+```
+
+The caps are upper bounds: removing wrappers makes the counts fall, while newly introduced copies
+make the audit fail.
+
+## MCP server factories
+
+Embedding hosts can reuse tool registration while retaining ownership of storage and process
+lifecycle. Factories never connect to stdio or parse global CLI arguments:
+
+```ts
+import { createTaskMcpServer } from "negotium/mcp-factories";
+
+const taskServer = createTaskMcpServer(
+  { userId, topic: topicTitle, topicId },
+  {
+    readTasks: (userId, scopeKey) => hostTasks.read(userId, scopeKey),
+    writeTasks: (userId, scopeKey, tasks) =>
+      hostTasks.write(userId, scopeKey, tasks),
+  },
+);
+```
+
+`createTokenStatsMcpServer({ userId }, host)` and `createSystemHealthMcpServer(host)` provide the
+same boundary for usage statistics and system probes. The standalone Negotium CLI remains a thin
+stdio entrypoint over these factories. More common MCP servers will move behind this host-injection
+boundary incrementally.
+
+Vault consumers must inject credential operations explicitly, so two embedding hosts cannot share
+process-global Vault state accidentally:
+
+```ts
+import { createVaultMcpServer, protectMcpStdio } from "negotium/mcp-factories";
+
+const vaultServer = createVaultMcpServer(
+  { userId, httpOnly: true },
+  {
+    list: (id) => vault.list(id),
+    substitute: (id, text) => vault.substitute(id, text),
+    redact: (id, text) => vault.redact(id, text),
+  },
+);
+```
+
+`protectMcpStdio({ env, console })` is an opt-in standalone-entrypoint helper and returns an
+idempotent restore function. Embedded transports should normally avoid changing process-wide
+console behavior.
+
+Wiki hosts inject both the filesystem root and the optional topic-brief bridge. Importing the
+factory does not parse `process.argv`, open SQLite, or connect stdio:
+
+```ts
+import { createWikiMcpServer } from "negotium/mcp-factories";
+
+const wikiServer = createWikiMcpServer(
+  { userId, topicId, surface: "wiki" },
+  {
+    wikiRoot: hostWikiRoot,
+    getTopicBrief: (id) => hostBriefs.get(id),
+    setTopicBrief: (id, patch) => hostBriefs.set(id, patch),
+  },
+);
+```
+
+Long-lived hosts can also own an isolated background process manager:
+
+```ts
+import { createBackgroundBashManager } from "negotium/background-bash";
+
+const backgroundBash = createBackgroundBashManager({
+  env: hostEnvironment,
+  basePort: 47_000,
+  maxPort: 47_099,
+});
+```
+
+Each manager owns its capability, server identity, reserved ports, process handles, and known
+contexts. The root exports remain compatibility wrappers over Negotium's default manager.
+
+## Agent host helpers
+
+Embedding hosts can reuse pre-flight authentication, fork lifecycle, and task snapshot behavior
+without copying provider files:
+
+```ts
+import {
+  acquireCodexSpawnLock,
+  checkAgentAuth,
+  forkAgentSession,
+  killCodexTrees,
+  resolveTaskEventScope,
+  withTaskSnapshots,
+} from "negotium/agent-helpers";
+
+const auth = checkAgentAuth("codex", hostAuth);
+const scope = resolveTaskEventScope(queryOptions, hostTasks);
+```
+
+The host arguments own credential paths, environment checks, and task storage. Provider execution
+itself remains available through `negotium/hosted-agent`.
+
+Process-tree helpers are also exported from this subpath so an embedding runtime does not need a
+copied `codex-tree-kill.ts`. Their ownership Set is process-local; use them only for Codex children
+spawned by the current runtime process.
+
+## Agent helper embedding API
+
+Agent switching, task-stream snapshots, and session forks are available from one stable subpath:
+
+```ts
+import {
+  checkAgentAuth,
+  forkAgentSession,
+  resolveTaskEventScope,
+  withTaskSnapshots,
+} from "negotium/agent-helpers";
+
+const auth = checkAgentAuth("codex", hostAuth);
+const scope = resolveTaskEventScope(queryOptions, hostTasks);
+const events = scope ? withTaskSnapshots(providerEvents, scope, hostTasks) : providerEvents;
+```
+
+Supplying `AgentAuthHost` and `TaskEventHost` keeps auth paths, environment state, and task stores
+owned by the embedding process. The default host remains available only as a convenience for the
+standalone Negotium runtime.
+
+## MCP catalog policy
+
+`negotium/mcp-catalog` exposes transport-independent required/optional classification. Embedding
+hosts can merge host-only capabilities without duplicating Negotium's built-in list:
+
+```ts
+import {
+  classifyForumMcpServers,
+  COMMON_RUNTIME_MCP_POLICY,
+} from "negotium/mcp-catalog";
+
+const policy = {
+  ...COMMON_RUNTIME_MCP_POLICY,
+  "cron-manager": { scopes: ["forum", "manager"], forumRequired: true },
+};
+const { required, optional } = classifyForumMcpServers(policy);
+```
+
+Playwright and background Bash are canonical required forum capabilities, so topic settings should
+not present them as optional toggles. Host-only entries choose their own `forumRequired` policy.
+
 ## Storage embedding API
 
 Embedding hosts can reuse Negotium's SQLite and filesystem stores without importing package