@semalt-ai/code 1.8.5 → 1.20.0

package/README.md

@@ -18,7 +18,7 @@ It provides an interactive chat interface, one-shot code generation, AI-assisted
 
 ## Requirements
 
-- Node.js `>=16`
+- Node.js `>=18` (Node 16 is end-of-life; `node --test` is unreliable on it)
 - An OpenAI-compatible API endpoint
 
 The default configuration expects a local API server at `http://127.0.0.1:8800`.
@@ -114,6 +114,14 @@ semalt-code [command] [options]
 - `semalt-code init`
   Creates or updates the local config file.
 
+- `semalt-code mcp <list|status|add|remove|auth>`
+  Manage MCP servers. `add` registers a server (stdio `command`/`args` or remote `--url`),
+  `status` connects and reports each server's tools, `auth` runs the OAuth flow for a remote
+  server (tokens are stored in the OS keychain). Discovered tools register as
+  `mcp__<server>__<tool>` and run through the same approval-gated agent loop as built-ins —
+  MCP results are treated as untrusted external content, and MCP tools require approval by
+  default (opt in per server with `allow`/`allowAll`). In chat, `/mcp` shows the same status.
+
 ### Options
 
 - `-m, --model <name>`
@@ -182,7 +190,7 @@ When the model emits these actions, the CLI:
 2. Prompts the user for approval
 3. Executes the action
 4. Sends the result back to the model
-5. Continues for up to 10 iterations
+5. Continues for up to 125 iterations
 
 This makes the tool behave like a lightweight terminal agent while keeping the user in control.
 
@@ -246,6 +254,99 @@ Saved profiles can then be selected inside chat mode with `/model` or `/models`.
 semalt-code --version
 ```
 
+## Embedding SDK
+
+`@semalt-ai/code` can be embedded in another program as a library, not just run as a
+CLI. There are **two tiers**, physically separated by the package `exports` map:
+
+| Import | Surface | Stability |
+|--------|---------|-----------|
+| `require('@semalt-ai/code')` | `createAgent` — the high-level facade | **Stable** (semver) |
+| `require('@semalt-ai/code/internals')` | `createAgentRunner`, `createApiClient`, the registries, … | **Unstable** — no guarantee, may change in any release |
+
+Both subpaths work for `require` and `import` (the package is CommonJS; ESM consumers
+get the named exports via interop).
+
+### The facade
+
+```js
+const { createAgent } = require('@semalt-ai/code');
+
+const agent = createAgent({
+  apiBase: 'http://127.0.0.1:8800',
+  apiKey:  process.env.SEMALT_API_KEY,
+  model:   'my-model',
+  // permission policy — see below
+});
+
+const res = await agent.run('Summarise README.md in three bullets');
+// res = { result, toolCalls, usage, cost, stopReason, verifyStatus, messages }
+console.log(res.result);
+
+await agent.close(); // REQUIRED — releases MCP connections / processes
+```
+
+`run(prompt, opts?)` executes a prompt to completion and returns the same structured
+envelope headless mode produces, plus `messages` so you can continue the conversation
+(`agent.run(next, { messages: res.messages })`). Stream events with
+`agent.on('token' | 'assistant' | 'tool' | 'tool-start' | 'error' | 'warning' | 'done', cb)`.
+
+### Permission policy — safe by default
+
+There is no terminal in embedded use, so the facade takes a **programmatic** permission
+policy. With **neither** a policy provided, the default is to **refuse every mutating /
+effectful tool** (read-only tools still run) — it never auto-approves:
+
+```js
+// 1) an async approver callback
+createAgent({ /* … */, approve: async (call) => {
+  // call = { actionType, description, tag, rule }
+  return call.tag !== 'delete_file'; // your decision
+}});
+
+// 2) preset allow/deny/ask rules (the same engine as the CLI's per-pattern rules)
+createAgent({ /* … */, rules: [
+  { tool: 'write_file', path: 'src/**', action: 'allow' },
+  { tool: 'shell',      pattern: 'git *', action: 'allow' },
+  { tool: 'shell',      pattern: '/curl.*\\| *sh/', action: 'deny' },
+]});
+
+// 3) coarse tiers (like --allow-fs/exec/net) and read-only
+createAgent({ /* … */, allow: ['fs', 'net'], readonly: true });
+```
+
+The **OS sandbox** and the **destructive-command deny-list** stay **on** regardless of
+there being no TTY. The sandbox is opt-out **only** via explicit config
+(`sandbox: { mode: 'off' }`); a host can permit running a command unsandboxed when the
+kernel primitive is missing by supplying `onUnsandboxed`. A `deny` rule and the
+deny-list are honored even under the deliberate `dangerouslySkipPermissions: true`
+gate opt-out.
+
+By default the SDK does **not** read your `~/.semalt-ai/config.json` (a server wants
+isolation, not the operator's personal defaults) — pass `loadUserConfig: true` to layer
+it in. Pass arbitrary config under `config: { … }`.
+
+### Lifecycle & multi-instance
+
+- **Always call `await agent.close()`** when done. It disconnects MCP servers and frees
+  handles. `run()` after `close()` throws.
+- Each `createAgent` instance keeps its **own config** — two instances never share
+  config state.
+- **Process-global state (documented limitation).** A few things are process-wide, not
+  per-instance, because they were built for the single-process CLI:
+  - the **dynamic tool registry** (MCP + `spawn_agent`) is global — two instances with
+    *different* MCP servers would see each other's tools;
+  - file-path confinement (`isPathSafe`) and the deny-list/secret/config guards read
+    `process.cwd()` and `process.argv` **once at module load**, so they're shared by all
+    instances and the deny-list opt-out requires launching the host process with
+    `--dangerously-skip-permissions`;
+  - the stdout-chrome-suppression flag is process-wide.
+
+  For most embeddings (one agent per process, or instances sharing a CWD and MCP set)
+  none of this matters; run fully-isolated agents in separate processes if it does.
+
+A runnable example lives in [`examples/embed.js`](examples/embed.js).
+
 ## How Responses Are Rendered
 
 The CLI formats streamed output for terminal readability:
@@ -259,13 +360,56 @@ The CLI formats streamed output for terminal readability:
 
 If the backend returns `reasoning_content`, the CLI also shows a lightweight `thinking` section during streaming.
 
+## Dependency Policy
+
+This project keeps its runtime dependency surface **minimal, vetted, and pinned**. It
+ran with **zero runtime dependencies** through its first phases; as of v1.9.0 it has a
+single one — the official Model Context Protocol SDK,
+[`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) —
+adopted to implement MCP against its reference (rather than hand-rolling the protocol).
+
+The policy for any runtime dependency:
+
+- **Minimal & justified** — added only when a Node.js built-in genuinely cannot do the
+  job, with a recorded rationale.
+- **Pinned to an exact version** — no `^`/`~` ranges in `package.json`. Upgrades are
+  deliberate, reviewed commits.
+- **Reviewed with the lockfile** — `package-lock.json` is committed; adding or bumping a
+  dependency is a reviewed change.
+
+**Supply-chain checks.** CI runs `npm ci` (lockfile integrity) and
+`npm audit --omit=dev --audit-level=high` (fails on HIGH/CRITICAL advisories in the
+runtime tree). The full audit-findings policy is documented in `CLAUDE.md`.
+
+The SDK is ESM-only while this project is CommonJS, so it is loaded in exactly one
+place — `lib/mcp/boundary.js`, via dynamic `import()` — and the rest of the codebase
+stays CommonJS.
+
 ## Notes and Limitations
 
-- This project is currently a single-file CLI implementation centered in `index.js`.
-- It uses Node's built-in `http` and `https` modules and does not require extra runtime dependencies.
+- It uses Node's built-in `http` and `https` modules for all networking; the only
+  runtime dependency is the MCP SDK (see **Dependency Policy** above).
 - The `edit` command writes the model output directly back to the target file, so review prompts and backend behavior carefully.
 - Shell and file operations are approval-based, but they still execute on the local system after approval.
 
+### Not yet implemented
+
+A few capabilities are intentionally absent today — documented here so you don't build
+on something that isn't wired up. See **Deferred / Not Yet Implemented** in `CLAUDE.md`
+for the full list and roadmap status.
+
+- **MCP tools are interactive-chat only** — they are not connected in the `code`/`edit`/`shell`
+  one-shot commands or headless `-p/--print` mode.
+- **No session auto-resume** — there's no "resume your last session?" prompt at startup;
+  use `/history` (local sessions) or `--resume <chat-id>` (dashboard chats).
+- **Proxy env vars are not consumed** — `HTTPS_PROXY`/`HTTP_PROXY` are read into config but
+  outbound HTTP does not yet route through a proxy agent (matters on corporate networks).
+- Planned for Phase 4+: per-pattern permissions, self-verification, checkpoints/rewind, and an OS sandbox.
+
+## Contributing
+
+PRs must pass the CI pipeline (`npm ci` + `npm audit` + lint + tests on Linux/macOS/Windows, Node 18 & 20) before they can be merged. Run `npm ci && npm run lint && npm test` locally first. Any dependency change must follow the **Dependency Policy** above (exact pin, committed lockfile, justification).
+
 ## License
 
 MIT