@makaio/framework 1.0.0-dev-1779046984397

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Makaio GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,363 @@
+<div align="center">
+  <img src="../../docs/assets/logo.svg" alt="Makaio Logo" width="120" />
+  <h1>Makaio Framework</h1>
+  <p><strong>A typed, bus-centric runtime for orchestrating AI agents, tools, and sessions across providers.</strong></p>
+
+  [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+  [![CI](https://github.com/makaio-ai/makaio-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/makaio-ai/makaio-framework/actions/workflows/ci.yml)
+
+  [Website](https://makaio.ai) · [Getting Started](https://makaio.ai/guides/getting-started/) · [Why Makaio](https://makaio.ai/why/)
+</div>
+
+---
+
+> [!TIP]
+> **Give your AI agent full context.** Point it at [`makaio.ai/llms.txt`](https://makaio.ai/llms.txt) — everything it needs to answer questions, write extensions, or explore the architecture with you.
+
+---
+
+
+Most AI tooling today solves one layer: call an LLM, stream a response, maybe loop on tool calls. That works until you need multiple providers in one system, agents that communicate across processes, storage you can swap without rewriting services, or extensions that load at runtime without forking the host.
+
+Makaio Framework is a typed runtime for building and hosting AI agent systems. It gives you a bus-centric architecture where agents, services, tools, and storage communicate through typed events and RPC — across threads, processes, or machines.
+
+---
+
+### Connect your AI tools
+
+> [!NOTE]
+> Makaio normalizes the infrastructure beneath your AI tools — adapters, credentials, streaming, storage. Build a usage tracker, session viewer, or approval workflow once, and it works across Claude Code, Codex, Gemini, and more. Already built something for one provider? Move it to Makaio and it works with all of them.
+>
+> → [Connect your tooling](../../docs/connect.md) · [Shipped extensions](../../extensions/index.md)
+
+### Extend the ecosystem
+
+> [!NOTE]
+> Scaffold an extension in one command, contribute CLI commands, background services, tools, or UI surfaces. The framework provides adapters for 8 providers, bus-mediated storage, and a full runtime — you focus on what your extension does.
+>
+> → [Create an extension](../../docs/creating-extensions.md) · [Extension model](../../docs/architecture/extensions/index.md)
+
+### Compose, intercept, extend
+
+> [!NOTE]
+> Everything flows through a typed bus — tool calls, agent events, storage requests. Intercept tool inputs for redaction, route sensitive analysis to local models, chain handlers with priority middleware. Build sophisticated automations without forking the framework.
+>
+> → [Bus architecture](../../docs/architecture/bus/index.md) · [Writing an adapter](../../docs/creating-adapters.md)
+
+### Evaluating agent frameworks?
+
+> [!NOTE]
+> Makaio is not another LangChain wrapper. It's runtime infrastructure: a typed event bus with cross-process transports, a 3-layer adapter contract with conformance tests, and an extension system where capabilities load at runtime. Compare it to the orchestration layer beneath your agents, not the agents themselves.
+>
+> → [How this differs](#how-this-differs) · [Architecture](#architecture)
+
+---
+
+## Install
+
+Makaio Framework is currently source-first. From a source checkout:
+
+```bash
+yarn install
+yarn dev
+```
+
+The development script starts the framework runtime and web host. Verify the
+CLI directly from source:
+
+```bash
+yarn tsx apps/cli/src/cli-entry.ts --help
+```
+
+## Quick Start
+
+Start the runtime and manage extensions — no code required:
+
+```bash
+# Start the Makaio runtime (bus + services + adapters)
+makaio serve
+
+# In another terminal — install extensions
+makaio extension install ./extensions/account-manager   # Local source checkout
+makaio extension install ./my-local-extension           # Your local extension
+
+# See what's installed
+makaio extension list
+```
+
+Extensions contribute CLI commands, background services, tools, UI surfaces, and more — all discovered at runtime via `descriptor.json`. During the pre-release phase, framework-shipped extensions are installed from local paths; published npm package names will be documented once those packages are public.
+
+The [account-manager](../../extensions/account-manager/README.md) extension adds credential management across AI tools. The [prompt](../../extensions/prompt/README.md) extension adds `makaio prompt send` — a provider-agnostic CLI for sending prompts, useful as a drop-in replacement for `claude -p` in scripts and CI pipelines.
+
+## Why a Shared Framework
+
+Everyone building AI-powered applications ends up writing the same infrastructure: provider adapters that break every SDK update, streaming pipelines, tool execution loops, session management, storage layers. Then the model landscape shifts — a new provider launches, an API version bumps, a protocol like ACP emerges — and every project maintains its own copy of the same adapter fixes.
+
+This is that shared copy. One set of adapters with conformance tests, one extension model, one typed bus. You build your application, workflow, or agent system on top. When Anthropic ships a new API version or OpenAI changes their streaming format, the fix lands here once — not in every project independently.
+
+## How This Differs
+
+Existing solutions occupy specific layers:
+
+| Layer | Examples | What they solve |
+|-------|----------|-----------------|
+| Provider abstraction | Vercel AI SDK, LiteLLM | Unified interface to call any LLM |
+| Agent orchestration | LangGraph, AutoGen, CrewAI | Build and run multi-agent workflows |
+| Coding assistants | Claude Code, Cursor, Copilot | AI-powered development in a single tool |
+
+Makaio Framework operates below and across these layers. It provides the runtime infrastructure that agent systems need regardless of which provider, orchestration pattern, or host surface they use:
+
+- A **typed event bus** with pub/sub, RPC, namespaces, and cross-process transports
+- A **3-layer adapter contract** (Adapter → Agent → Connector) with conformance tests
+- An **extension system** where capabilities load at runtime, not compile time
+- **Bus-mediated storage** so backends are swappable without touching service code
+- **Host composition** — CLI and desktop share the same boot pipeline
+
+The bus isn't a notification layer added to a procedural core. It's the architectural backbone: services subscribe, adapters publish, storage handlers respond to requests, and transports bridge it all across process boundaries.
+
+## Build on Makaio
+
+Start any provider's agent with a bus request. Control tool access. React to events. All typed, all provider-agnostic:
+
+> `@makaio/framework` is the intended public aggregate package. Until that package is published, these imports describe the release surface rather than an installable npm package.
+
+```ts
+import { MakaioBus } from '@makaio/framework/bus';
+import { AgentSubjects, SessionSubjects } from '@makaio/framework/contracts';
+
+const sessionId = crypto.randomUUID();
+
+// Start a session-backed turn — same shape regardless of provider
+const { messageId } = await MakaioBus.request(SessionSubjects.sendMessage, {
+  sessionId,
+  agent: {
+    kind: 'adapter',
+    adapterName: 'anthropic-sdk', // swap to 'openai-node', 'gemini-sdk', etc.
+    systemPrompt: 'You are a security reviewer. Be concise.',
+    // Omit model to use the provider default, or pass an adapter-specific ID from the model registry.
+  },
+  message: 'Review the changes in src/ for security issues',
+});
+
+// Control what the agent can do — approve, deny, or abort
+const unsub = MakaioBus.on(
+  AgentSubjects.toolApprove,
+  (ctx) => {
+    if (ctx.payload.toolName === 'write_file') {
+      ctx.setResult({ action: 'deny', message: 'Read-only review.', shouldAbort: false });
+    } else {
+      ctx.setResult({ action: 'allow' });
+    }
+  },
+  { filter: { sessionId } },
+);
+
+// Wait for completion — typed result
+const completed = await MakaioBus.once(AgentSubjects.complete, {
+  filter: { sessionId, messageId },
+  timeoutMs: 120_000,
+});
+
+console.info(completed.payload.message);
+unsub();
+```
+
+Switch `adapterName` and the same session orchestration code runs against Claude, Codex, Gemini, or Qwen. Keep `model` omitted for provider defaults unless you have resolved a concrete adapter-specific model ID from the model registry. The [adapter conformance test suite](../../adapters/implementations/__tests__/) guarantees consistent behavior across all of them.
+
+### Architecture
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│              Your Application / Host                    │
+│           CLI, Electron, or custom host                 │
+└────────────────────────┬────────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────────┐
+│            Runtime + Extension Coordinator              │
+│     Dependency ordering · Lifecycle · Surfaces          │
+└────────────────────────┬────────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────────┐
+│                    Makaio Bus                           │
+│  Typed pub/sub + RPC · Namespaces · Scoped/Filtered     │
+│  Transport registry (WebSocket, loopback, custom)       │
+└───────┬────────────────┼───────────────────┬────────────┘
+        │                │                   │
+┌───────▼──────┐  ┌──────▼───────┐  ┌────────▼─────────┐
+│   Services   │  │   Storage    │  │      Tools       │
+│  Session,    │  │  Bus-backed  │  │  Typed schemas,  │
+│  Orchestrator│  │  handlers    │  │  registry,       │
+│  Registry    │  │  (swappable) │  │  approval flow   │
+└──────────────┘  └──────────────┘  └──────────────────┘
+        │
+┌───────▼─────────────────────────────────────────────────┐
+│              Adapter Layer (3-part)                     │
+│  AIAdapter        → lifecycle, session management       │
+│  AIAgent          → turn execution, tool orchestration  │
+│  AIAgentConnector → provider SDK / CLI / ACP bridge     │
+└─────────────────────────────────────────────────────────┘
+```
+
+Everything communicates through the [bus](../../docs/architecture/bus/index.md). The transport registry means the bus spans process boundaries — a VS Code extension, a mobile app, or a CI pipeline can participate as a bus client over WebSocket without importing the framework.
+
+### Adapters
+
+Each adapter implements the 3-layer contract (Adapter → Agent → Connector) and passes a shared [conformance test suite](../../adapters/implementations/__tests__/) that verifies lifecycle, streaming, tool approval, and error handling.
+
+| Adapter | Provider | Protocol | Status |
+|---------|----------|----------|--------|
+| `anthropic-sdk` | Anthropic (Claude) | API SDK | Stable |
+| `openai-node` | OpenAI (GPT) | API SDK | Stable |
+| `gemini-sdk` | Google (Gemini) | API SDK | Stable |
+| `claude-code-cli` | Anthropic (Claude Code) | CLI subprocess | Stable |
+| `claude-code` | Anthropic (Claude Agent SDK implementation) | API SDK | Stable |
+| `codex-app-server` | OpenAI (Codex) | ACP | Experimental |
+| `qwen-acp` | Alibaba (Qwen) | ACP | Experimental |
+| `github-copilot-sdk` | GitHub (Copilot) | API SDK | [ABANDONED](https://github.blog/news-insights/company-news/github-copilot-is-moving-to-usage-based-billing/) |
+
+**Status definitions:**
+
+- **Stable** — Actively maintained, conformance tests pass, used in production
+- **Experimental** — Working implementation, API surface may change
+- **Community** — Maintained by contributors, not the core team
+
+Writing a new adapter means implementing `AIAgentConnector` (the provider bridge), wrapping it in an `AIAgent` and `AIAdapter`, and running the conformance suite. See [Creating Adapters](../../docs/creating-adapters.md).
+
+### SDKs
+
+The bus protocol is language-neutral. SDKs let any process participate — subscribe to events, handle requests, emit — without importing the TypeScript framework:
+
+| SDK | Language | Transport | Status |
+|-----|----------|-----------|--------|
+| [`@makaio/sdk`](../../sdks/typescript/) | TypeScript | Framework-native facade | Pre-release, unpublished package |
+| [`makaio-sdk`](../../sdks/python/) | Python | WebSocket + stdio (asyncio) | Pre-release, unpublished package |
+| [`makaio-sdk`](../../sdks/rust/) | Rust | WebSocket + stdio (tokio) | Unpublished crate (`publish = false`) |
+
+All SDKs expose the same logical surface:
+
+```
+connect(url, options?)       // WebSocket connection with optional HMAC auth and dispatch mode
+subscribe(subject, handler)  // event subscription (local + remote dispatch)
+onRequest/on_request(...)    // request handler with middleware chaining (TypeScript uses onRequest; Python/Rust use on_request)
+request(subject, payload)    // typed RPC (local-first dispatch by default)
+emit(subject, payload)       // fire-and-forget (dispatches to local + remote subscribers)
+close()                      // clean shutdown
+```
+
+All three SDKs support HMAC authentication (auto-probed from `/health`), local-first request dispatch with middleware chaining via `RequestContext.next()`, typed subject descriptors generated from the protocol manifest, and WebSocket transport. Python and Rust additionally support stdio transport for detached extension processes.
+
+Subscription cleanup is language-shaped: TypeScript returns unsubscribe functions, Python subscription handles expose `close()`, and Rust uses `unsubscribe()` for event subscriptions and `unregister()` for request handlers.
+
+Cross-language SDKs are generated from a [shared protocol manifest](../../sdks/manifest/) derived from `@makaio/contracts`, validated against a [shared conformance suite](../../sdks/conformance/). The TypeScript SDK is a thin facade over the framework's bus packages.
+
+## Documentation
+
+**Use Makaio:**
+
+| Topic | Link |
+|-------|------|
+| Getting started | [docs/getting-started.md](../../docs/getting-started.md) |
+| CLI reference | [apps/cli/README.md](../../apps/cli/README.md) |
+| Configuration | [docs/configuration.md](../../docs/configuration.md) |
+
+**Build on Makaio:**
+
+| Topic | Link |
+|-------|------|
+| Writing an extension | [docs/creating-extensions.md](../../docs/creating-extensions.md) |
+| Writing an adapter | [docs/creating-adapters.md](../../docs/creating-adapters.md) |
+| Extension model | [docs/architecture/extensions/index.md](../../docs/architecture/extensions/index.md) |
+| Bus architecture | [docs/architecture/bus/](../../docs/architecture/bus/index.md) |
+| Transport (WebSocket, cross-process) | [docs/architecture/transport.md](../../docs/architecture/transport.md) |
+
+**Host and deploy:**
+
+| Topic | Link |
+|-------|------|
+| Host applications | [docs/architecture/apps.md](../../docs/architecture/apps.md) |
+
+## Repository Layout
+
+Representative high-level tree for the framework distribution. It lists the main workspace groups and notable packages; individual provider, extension, and test packages may change as the framework evolves.
+
+```text
+├── adapters/
+│   ├── core/                  Adapter contracts, conformance test suite
+│   ├── shared/                Shared ACP, Claude, and stream-session helpers
+│   └── implementations/       One directory per provider adapter
+├── apps/
+│   ├── cli/                   Headless CLI server + bus client
+│   ├── electron/              Electron desktop host
+│   ├── electrobun/            Electrobun desktop host (experimental)
+│   ├── host-shared/           Shared desktop host boot/rendering logic
+│   └── mcp-server/            MCP server bridge
+├── build-tooling/             Shared Vite/tsdown configs for packages and extensions
+├── clients/                   External tool client integrations (Claude Code, Codex, Gemini, Copilot, Qwen)
+├── docs/                      Framework documentation
+├── extensions/                Framework-shipped extensions
+├── packages/
+│   ├── adapter-subsystem/     Adapter contribution loading, runtime registry, identity
+│   ├── bus-core/              Typed event bus — pub/sub, RPC, namespaces, scoped/filtered buses
+│   ├── bus-server/            HTTP + WebSocket server lifecycle
+│   ├── bus-server-vite/       Vite dev-server bus integration
+│   ├── clients-core/          Managed client/runtime/binary services
+│   ├── contracts/             Zod schemas, subject taxonomy, wire format
+│   ├── expression/            Expression evaluator over contracts
+│   ├── file-watcher/          File watching abstraction
+│   ├── hooks/                 Bus-event hook system
+│   ├── machine-identity/      Stable machine ID (keypair)
+│   ├── makaio-core/           Foundational types, errors, OptionalResult
+│   ├── mcp-http-server/       MCP-over-HTTP bridge
+│   ├── native-session-supervisor/ Native client session observation
+│   ├── kernel/                ExtensionCoordinator, service lifecycle, boot observability
+│   ├── services/base/         BaseService lifecycle primitive
+│   ├── services/core/         Core services: session, orchestrator, tool registry, model registry
+│   ├── services/log-import/   Session log import service
+│   ├── services/package-manager/ Package discovery and management service
+│   ├── storage/core/          Storage namespace contracts
+│   ├── storage/drizzle/       Drizzle/SQLite client helpers, FTS, transactions
+│   ├── storage/handlers/      Bus-backed CRUD + list handler factories
+│   ├── storage-migrations/    Migration runner + schema discovery
+│   ├── preferences/           User preferences storage
+│   ├── providers/             Config/provider runtime helpers
+│   ├── rules/                 Runtime rule helpers
+│   ├── test-utils/            Test helpers, bus fixtures, SQLite test harness
+│   └── utils/                 Shared utilities
+├── providers/                 Provider metadata packages (model catalogs, capability tags)
+├── runtimes/
+│   ├── bun/                   Bun host assembly helpers
+│   └── node/                  Node host assembly: bootMakaioRuntime(), discovery, DB init
+├── sdks/
+│   ├── typescript/            @makaio/sdk — TypeScript facade
+│   ├── python/                Python SDK (asyncio, WebSocket + stdio)
+│   ├── rust/                  Rust SDK (tokio, WebSocket + stdio)
+│   ├── manifest/              Language-neutral protocol definition (generated)
+│   └── conformance/           Shared wire-level conformance fixtures
+├── tools/
+│   ├── core/                  Tool contract, defineTool(), defineToolset(), executor
+│   ├── filesystem/            File read/write/search tools
+│   ├── shell/                 Shell execution tool
+│   └── subagent/              Sub-agent spawning tool
+├── transports/
+│   ├── ws/                    WebSocket transport (HMAC auth, E2E encryption, relay)
+│   └── message-channel/       MessageChannel transport (SharedWorker, iframe)
+└── ui/
+    ├── kernel/                UI contracts, registries (widgets, pages, navigation)
+    ├── theme/                 SCSS design system: tokens, themes, mixins
+    ├── components/            Pure UI components (no hooks, no bus)
+    ├── hooks/                 React hooks, stores, providers (BusProvider, useBus)
+    └── views/                 Composed views and shell components
+```
+
+## Contributing
+
+We welcome contributions — adapters, extensions, tools, bug fixes, and documentation. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development setup, contribution surfaces, and PR guidelines.
+
+## Community
+
+- [Code of Conduct](../../CODE_OF_CONDUCT.md)
+- [Security Policy](../../SECURITY.md)
+
+## License
+
+[MIT](../../LICENSE)

package/dist/account-identity-Ce1Bwrqi.mjs

@@ -0,0 +1 @@
+import{m as e}from"./shared-DxHLl9UP.mjs";import{m as t,p as n}from"./profile-4StaDQW0.mjs";import{n as r}from"./version-CjS20oXi.mjs";import{z as i}from"zod";const a=i.enum([`strong`,`alias`]),o=i.object({scheme:t,value:t,strength:a}),s=i.object({key:t,label:i.string(),usedPercentage:i.number().finite().min(0).max(100),resetsAt:n.optional()}),c=i.object({windows:i.array(s)}),l=i.record(i.string(),i.unknown()).optional(),u=i.object({clientId:t,found:i.boolean(),version:i.string().optional(),warningMessage:i.string().optional()}),d=i.object({clientId:t,binaryName:t,supportedVersions:r.optional()}),f=i.object({clientAccountId:t,clientId:t,observedAt:n,source:t,displayLabel:i.string().optional(),usage:c,metadata:l}),p=i.discriminatedUnion(`kind`,[i.object({kind:i.literal(`session`),sessionId:t}),i.object({kind:i.literal(`adapter-session`),adapterSessionId:t}),i.object({kind:i.literal(`both`),sessionId:t,adapterSessionId:t})]),m=i.object({clientId:i.string(),source:i.string(),kind:i.string(),observedAt:n,payload:e}),h={request:i.object({clientId:t,observedAt:n.optional(),displayLabel:i.string().optional(),identifiers:i.array(o).min(1),metadata:l}),response:i.object({clientAccountId:t,displayLabel:i.string().optional()})},g={request:m.extend({locator:p}),response:i.object({handled:i.boolean(),sessionId:t.nullable(),clientAccountId:t.nullable(),changed:i.boolean()})},_={request:i.object({clientId:t,observedAt:n,source:t,account:i.object({displayLabel:i.string().optional(),identifiers:i.array(o).min(1)}),usage:c,metadata:l}),response:i.object({clientAccountId:t,snapshot:f})};export{l as a,g as c,f as d,s as f,m as i,p as l,h as n,u as o,c as p,a as r,d as s,o as t,_ as u};

package/dist/adapter-CbyjCE2d.mjs

@@ -0,0 +1 @@
+import{_ as e,b as t,c as n,d as r,f as i,g as a,h as o,i as s,l as c,m as l,ot as u,p as d,r as f,s as p,t as m,u as h,v as g,x as _,y as v}from"./schemas-BXstpWVp.mjs";import"./contracts/adapter/schemas/session-lineage.mjs";import{createBusNamespace as y}from"@makaio/framework/core";const b={getCapabilities:u,startAgent:_,infer:t,listAgents:v,getAgent:g,stopAgent:e,rehydrateAgent:a,getConfigSchema:o,"agent.created":l,"session.created":d,"session.discovered":s,"session.linked":f,"session.statusChanged":m,"session.usage":i,"session.closed":r,log:h,error:c,initialized:n,quota:p},x=y(`adapter`,b),S=x.subjects;export{S as n,b as r,x as t};

package/dist/adapters/acp-client/index.d.mts

@@ -0,0 +1,209 @@
+import * as acp from "@agentclientprotocol/sdk";
+import { Client, CreateTerminalRequest, CreateTerminalResponse, KillTerminalRequest, KillTerminalResponse, ReadTextFileRequest, ReadTextFileResponse, ReleaseTerminalRequest, ReleaseTerminalResponse, RequestPermissionRequest, RequestPermissionResponse, SessionNotification, TerminalOutputRequest, TerminalOutputResponse, WaitForTerminalExitRequest, WaitForTerminalExitResponse, WriteTextFileRequest, WriteTextFileResponse } from "@agentclientprotocol/sdk";
+
+//#region adapters/shared/acp-client/src/terminal-manager.d.ts
+/**
+ * Manages stateful terminal lifecycles for ACP agents.
+ *
+ * ACP's terminal protocol is stateful (create → output → wait_for_exit → kill → release),
+ * which does not map cleanly to a single request/response. This manager handles direct
+ * child_process lifecycle with bounded output buffering.
+ */
+declare class TerminalManager {
+  private readonly terminals;
+  private nextId;
+  /**
+   * Creates a new terminal subprocess.
+   * @param params - ACP create terminal request
+   * @returns Terminal ID for subsequent operations
+   */
+  createTerminal(params: acp.CreateTerminalRequest): Promise<acp.CreateTerminalResponse>;
+  /**
+   * Gets the current output of a terminal without waiting for it to exit.
+   * @param params - ACP terminal output request
+   * @returns Current buffered output and truncation status
+   */
+  getOutput(params: acp.TerminalOutputRequest): Promise<acp.TerminalOutputResponse>;
+  /**
+   * Waits for a terminal process to exit.
+   * @param params - ACP wait for exit request
+   * @returns Exit code and terminating signal
+   */
+  waitForExit(params: acp.WaitForTerminalExitRequest): Promise<acp.WaitForTerminalExitResponse>;
+  /**
+   * Kills a terminal process without releasing it.
+   *
+   * The terminal remains valid after this call, allowing callers to retrieve
+   * final output before releasing.
+   * @param params - ACP kill terminal request
+   * @returns Empty response object
+   */
+  killTerminal(params: acp.KillTerminalRequest): Promise<acp.KillTerminalResponse>;
+  /**
+   * Releases a terminal, killing the process and freeing all associated resources.
+   *
+   * After this call the terminal ID is no longer valid.
+   * @param params - ACP release terminal request
+   * @returns Empty response object
+   */
+  releaseTerminal(params: acp.ReleaseTerminalRequest): Promise<acp.ReleaseTerminalResponse>;
+  /**
+   * Kills and removes all managed terminals.
+   *
+   * Should be called during connector shutdown to prevent resource leaks.
+   */
+  releaseAll(): void;
+  /**
+   * Returns a managed terminal by ID, throwing if not found.
+   * @param terminalId - Terminal identifier assigned at creation time
+   * @returns The managed terminal state
+   */
+  private requireTerminal;
+}
+//#endregion
+//#region adapters/shared/acp-client/src/types.d.ts
+/**
+ * Configuration for spawning an ACP agent subprocess.
+ */
+interface AcpConnectionOptions {
+  /** Subprocess command (e.g., 'qwen') */
+  command: string;
+  /** CLI arguments (e.g., ['--acp', '--model', 'qwen3-coder']) */
+  args: string[];
+  /** Working directory for the subprocess */
+  cwd: string;
+  /** Environment variables passed to the subprocess */
+  env: Record<string, string>;
+  /** Callback for stderr output */
+  onStderr?: (data: string) => void;
+  /** Callback for subprocess spawn/runtime errors */
+  onError?: (error: Error) => void;
+  /** Callback for subprocess exit */
+  onExit?: (code: number | null) => void;
+}
+/**
+ * Handle to a running ACP connection (subprocess + protocol layer).
+ */
+interface AcpConnectionHandle {
+  /** The ACP client-side connection for sending requests to the agent */
+  connection: acp.ClientSideConnection;
+  /** Kill the subprocess with SIGTERM */
+  kill(): void;
+  /** Promise that resolves with the exit code when the subprocess exits */
+  exited: Promise<number | null>;
+}
+/**
+ * Callbacks for routing ACP server requests to Makaio infrastructure.
+ */
+interface MakaioAcpClientConfig {
+  /**
+   * Handle session update notifications (message chunks, tool calls, usage, etc.).
+   * @param notification - The session notification from the agent
+   */
+  onSessionUpdate: (notification: acp.SessionNotification) => Promise<void>;
+  /**
+   * Handle permission requests (tool approval).
+   * @param params - The permission request from the agent
+   */
+  onRequestPermission: (params: acp.RequestPermissionRequest) => Promise<acp.RequestPermissionResponse>;
+  /**
+   * Handle file read requests. Only required if fs.readTextFile capability is advertised.
+   * @param params - The read file request from the agent
+   */
+  onReadTextFile?: (params: acp.ReadTextFileRequest) => Promise<acp.ReadTextFileResponse>;
+  /**
+   * Handle file write requests. Only required if fs.writeTextFile capability is advertised.
+   * @param params - The write file request from the agent
+   */
+  onWriteTextFile?: (params: acp.WriteTextFileRequest) => Promise<acp.WriteTextFileResponse>;
+  /** Terminal lifecycle manager for stateful terminal operations */
+  terminalManager?: TerminalManager;
+}
+//#endregion
+//#region adapters/shared/acp-client/src/connection.d.ts
+/**
+ * Spawns an ACP agent subprocess and establishes a protocol connection over stdio.
+ *
+ * The subprocess stdin/stdout are bridged to the ACP SDK via Web Streams using
+ * `Readable.toWeb()` / `Writable.toWeb()` (Node.js 16+). The returned handle
+ * exposes the {@link acp.ClientSideConnection} for issuing ACP requests along with
+ * lifecycle controls.
+ * @param clientFactory - Factory called with the negotiated {@link acp.Agent} proxy;
+ *   must return the {@link acp.Client} implementation that handles incoming agent requests
+ * @param options - Subprocess spawn configuration
+ * @returns Handle containing the live connection, a kill function, and an exit promise
+ */
+declare function createAcpConnection(clientFactory: (agent: acp.Agent) => acp.Client, options: AcpConnectionOptions): Promise<AcpConnectionHandle>;
+//#endregion
+//#region adapters/shared/acp-client/src/client.d.ts
+/**
+ * ACP {@link Client} implementation that bridges agent requests to Makaio infrastructure.
+ *
+ * Routes session updates, permission requests, filesystem operations, and terminal
+ * lifecycle events to the connector-provided callbacks and optional terminal manager.
+ * All optional Client methods throw a descriptive error when the corresponding
+ * capability has not been configured.
+ */
+declare class MakaioAcpClient implements Client {
+  private readonly config;
+  /**
+   * @param config - Callbacks and optional managers for each ACP client capability
+   */
+  constructor(config: MakaioAcpClientConfig);
+  /**
+   * Forwards session update notifications to the connector.
+   * @param params - Session notification from the agent
+   * @returns Void promise resolving after the notification is processed
+   */
+  sessionUpdate(params: SessionNotification): Promise<void>;
+  /**
+   * Forwards permission requests to the connector approval handler.
+   * @param params - Permission request from the agent
+   * @returns The user's permission decision
+   */
+  requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse>;
+  /**
+   * Forwards file read requests to the optional handler.
+   * @param params - Read file request from the agent
+   * @returns File contents
+   */
+  readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
+  /**
+   * Forwards file write requests to the optional handler.
+   * @param params - Write file request from the agent
+   * @returns Write confirmation
+   */
+  writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
+  /**
+   * Creates a new terminal process via the terminal manager.
+   * @param params - Terminal creation parameters from the agent
+   * @returns Terminal ID for subsequent operations
+   */
+  createTerminal(params: CreateTerminalRequest): Promise<CreateTerminalResponse>;
+  /**
+   * Retrieves the current output of a managed terminal.
+   * @param params - Terminal output request from the agent
+   * @returns Current buffered output and truncation status
+   */
+  terminalOutput(params: TerminalOutputRequest): Promise<TerminalOutputResponse>;
+  /**
+   * Waits for a managed terminal to exit.
+   * @param params - Wait for exit request from the agent
+   * @returns Exit code and terminating signal
+   */
+  waitForTerminalExit(params: WaitForTerminalExitRequest): Promise<WaitForTerminalExitResponse>;
+  /**
+   * Kills a managed terminal process without releasing it.
+   * @param params - Kill terminal request from the agent
+   * @returns Empty kill response
+   */
+  killTerminal(params: KillTerminalRequest): Promise<KillTerminalResponse>;
+  /**
+   * Releases a managed terminal and frees all associated resources.
+   * @param params - Release terminal request from the agent
+   * @returns Empty release response
+   */
+  releaseTerminal(params: ReleaseTerminalRequest): Promise<ReleaseTerminalResponse>;
+}
+//#endregion
+export { type AcpConnectionHandle, type AcpConnectionOptions, MakaioAcpClient, type MakaioAcpClientConfig, TerminalManager, createAcpConnection };

package/dist/adapters/acp-client/index.mjs

@@ -0,0 +1 @@
+import{spawn as e}from"node:child_process";import{Readable as t,Writable as n}from"node:stream";import*as r from"@agentclientprotocol/sdk";function i(e){return new Promise((t,n)=>{let r=()=>{e.off(`error`,i),t()},i=t=>{e.off(`spawn`,r),n(t)};e.once(`spawn`,r),e.once(`error`,i)})}async function a(e){e.stdin?.destroy(),e.stdout?.destroy(),e.stderr?.destroy(),e.kill(`SIGTERM`),await new Promise(t=>{e.once(`exit`,()=>t()),e.once(`close`,()=>t()),setTimeout(t,100)})}function o(e){return e}function s(e){return e}async function c(c,l){let u=e(l.command,l.args,{cwd:l.cwd,env:l.env,stdio:[`pipe`,`pipe`,`pipe`]});try{await i(u)}catch(e){throw l.onError?.(e),e}l.onStderr&&u.stderr&&u.stderr.on(`data`,e=>{l.onStderr(e.toString(`utf-8`))});let d=new Promise(e=>{u.once(`exit`,t=>{l.onExit?.(t),e(t)})});u.on(`error`,e=>{l.onError?.(e)});let f;try{let e=t.toWeb(u.stdout),i=n.toWeb(u.stdin),a=r.ndJsonStream(s(i),o(e));f=new r.ClientSideConnection(c,a)}catch(e){throw await a(u),e}return{connection:f,kill:()=>u.kill(`SIGTERM`),exited:d}}var l=class{config;constructor(e){this.config=e}async sessionUpdate(e){await this.config.onSessionUpdate(e)}async requestPermission(e){return this.config.onRequestPermission(e)}async readTextFile(e){if(!this.config.onReadTextFile)throw Error(`readTextFile not supported: no handler configured`);return this.config.onReadTextFile(e)}async writeTextFile(e){if(!this.config.onWriteTextFile)throw Error(`writeTextFile not supported: no handler configured`);return this.config.onWriteTextFile(e)}async createTerminal(e){if(!this.config.terminalManager)throw Error(`createTerminal not supported: no terminal manager configured`);return this.config.terminalManager.createTerminal(e)}async terminalOutput(e){if(!this.config.terminalManager)throw Error(`terminalOutput not supported: no terminal manager configured`);return this.config.terminalManager.getOutput(e)}async waitForTerminalExit(e){if(!this.config.terminalManager)throw Error(`waitForTerminalExit not supported: no terminal manager configured`);return this.config.terminalManager.waitForExit(e)}async killTerminal(e){if(!this.config.terminalManager)throw Error(`killTerminal not supported: no terminal manager configured`);return this.config.terminalManager.killTerminal(e)}async releaseTerminal(e){if(!this.config.terminalManager)throw Error(`releaseTerminal not supported: no terminal manager configured`);return this.config.terminalManager.releaseTerminal(e)}},u=class{terminals=new Map;nextId=0;async createTerminal(t){let n=`terminal-${(++this.nextId).toString()}`,r=t.outputByteLimit??1024*1024,o={...process.env};if(t.env)for(let e of t.env)o[e.name]=e.value;let s=e(t.command,t.args??[],{cwd:t.cwd??void 0,env:o,stdio:[`pipe`,`pipe`,`pipe`]});try{await i(s)}catch(e){throw await a(s),e}let c={process:s,output:``,outputByteLimit:r,truncated:!1,exitCode:void 0,signal:void 0,hasExited:!1,exitPromise:new Promise(e=>{s.on(`exit`,(e,t)=>{c.exitCode=e,c.signal=t??null}),s.on(`close`,()=>{c.hasExited=!0,e({exitCode:c.exitCode??null,signal:c.signal??null})})})},l=e=>{if(c.output+=e.toString(`utf-8`),Buffer.byteLength(c.output,`utf-8`)>c.outputByteLimit){let e=Buffer.from(c.output,`utf-8`),t=e.length-c.outputByteLimit;for(;t<e.length&&(e[t]&192)==128;)t+=1;c.output=e.subarray(t).toString(`utf-8`),c.truncated=!0}};return s.stdout?.on(`data`,l),s.stderr?.on(`data`,l),this.terminals.set(n,c),{terminalId:n}}async getOutput(e){let t=this.requireTerminal(e.terminalId);return{output:t.output,truncated:t.truncated,...t.hasExited&&{exitStatus:{exitCode:t.exitCode??null,signal:t.signal??null}}}}async waitForExit(e){let{exitCode:t,signal:n}=await this.requireTerminal(e.terminalId).exitPromise;return{exitCode:t??void 0,signal:n??void 0}}async killTerminal(e){return this.requireTerminal(e.terminalId).process.kill(`SIGTERM`),{}}async releaseTerminal(e){let t=this.terminals.get(e.terminalId);return t&&(t.process.kill(`SIGKILL`),this.terminals.delete(e.terminalId)),{}}releaseAll(){for(let[e,t]of this.terminals)t.process.kill(`SIGKILL`),this.terminals.delete(e)}requireTerminal(e){let t=this.terminals.get(e);if(!t)throw Error(`Terminal not found: ${e}`);return t}};export{l as MakaioAcpClient,u as TerminalManager,c as createAcpConnection};