@xenosystem/acp-core 0.1.1

package/dist/session.js

@@ -0,0 +1,146 @@
+/**
+ * A `Session` wraps one ACP session id and an async event queue.
+ *
+ * The per-connection client handler dispatches `session/update` notifications here via
+ * `onUpdate`; the consumer (AcpManager / an embedder) drains `events()` as an async
+ * iterable. The queue closes when the prompt turn ends, so the iterator terminates
+ * naturally after the trailing `done` event.
+ */
+/** Minimal single-consumer async queue with explicit close. */
+class AsyncQueue {
+    items = [];
+    resolvers = [];
+    closed = false;
+    push(item) {
+        if (this.closed)
+            return;
+        const r = this.resolvers.shift();
+        if (r)
+            r({ value: item, done: false });
+        else
+            this.items.push(item);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        let r;
+        while ((r = this.resolvers.shift()))
+            r({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const item = this.items.shift();
+                if (item !== undefined)
+                    return Promise.resolve({ value: item, done: false });
+                if (this.closed)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.resolvers.push(resolve));
+            },
+            return: () => {
+                this.close();
+                return Promise.resolve({ value: undefined, done: true });
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+        };
+    }
+}
+/** Convert a raw ACP session update into zero or more structured `AcpEvent`s. */
+export function updateToEvents(update) {
+    switch (update.sessionUpdate) {
+        case "agent_message_chunk": {
+            const c = update.content;
+            if (c.type === "text")
+                return [{ type: "text", text: c.text }];
+            return [{ type: "raw", update }];
+        }
+        case "agent_thought_chunk": {
+            const c = update.content;
+            if (c.type === "text")
+                return [{ type: "thought", text: c.text }];
+            return [{ type: "raw", update }];
+        }
+        case "tool_call":
+            return [
+                {
+                    type: "tool_call",
+                    id: update.toolCallId,
+                    title: update.title,
+                    status: update.status ?? "pending",
+                    ...(update.kind ? { kind: update.kind } : {}),
+                },
+            ];
+        case "tool_call_update":
+            return [
+                {
+                    type: "tool_update",
+                    id: update.toolCallId,
+                    ...(update.status != null ? { status: update.status } : {}),
+                    ...(update.title != null ? { title: update.title } : {}),
+                },
+            ];
+        case "plan":
+            return [
+                {
+                    type: "plan",
+                    entries: (update.entries ?? []).map((e) => ({
+                        content: e.content,
+                        status: e.status,
+                        priority: e.priority,
+                    })),
+                },
+            ];
+        default:
+            return [{ type: "raw", update }];
+    }
+}
+export class Session {
+    id;
+    workspace;
+    queue = new AsyncQueue();
+    ended = false;
+    rawUpdateHandler;
+    constructor(id, workspace, rawUpdateHandler) {
+        this.id = id;
+        this.workspace = workspace;
+        this.rawUpdateHandler = rawUpdateHandler;
+    }
+    /** Feed a raw ACP update (called by the connection's client handler). */
+    onUpdate(update) {
+        this.rawUpdateHandler?.(update);
+        for (const ev of updateToEvents(update))
+            this.queue.push(ev);
+    }
+    /** Temporarily observe raw, SDK-validated ACP updates for an embedding host. */
+    setRawUpdateHandler(handler) {
+        this.rawUpdateHandler = handler;
+    }
+    /** Push a synthesized event (usage, error, etc.). */
+    push(event) {
+        this.queue.push(event);
+    }
+    /** Emit the terminal `done` event and close the stream. */
+    end(stopReason) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.queue.push({ type: "done", stopReason });
+        this.queue.close();
+    }
+    /** Emit an error and close the stream. */
+    fail(message) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.queue.push({ type: "error", message });
+        this.queue.close();
+    }
+    /** Async-iterate the event stream until the turn ends. */
+    events() {
+        return this.queue[Symbol.asyncIterator]();
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Public types for @xenosystem/acp-core.
+ *
+ * The engine is framework-free: these types describe the embeddable surface that
+ * in-process consumers (and the HTTP server) build on. Nothing here knows about
+ * HTTP or the OpenAI schema.
+ */
+import type { StopReason } from "@agentclientprotocol/sdk";
+export type { StopReason };
+/** How the gateway answers an agent's `requestPermission` call. */
+export type PermissionPolicy = "auto" | "deny" | "prompt";
+/** A single chat message handed to the engine; rendered into an ACP prompt. */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    /** Optional name (tool name / participant) — included in the rendered transcript. */
+    name?: string;
+}
+/**
+ * The structured event stream produced by a prompt turn. Embedders consume this
+ * directly (full fidelity); the HTTP server runs it through `flatten()`.
+ */
+export type AcpEvent = {
+    type: "text";
+    text: string;
+} | {
+    type: "thought";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    title: string;
+    status: string;
+    kind?: string;
+} | {
+    type: "tool_update";
+    id: string;
+    status?: string;
+    title?: string;
+} | {
+    type: "plan";
+    entries: Array<{
+        content: string;
+        status: string;
+        priority?: string;
+    }>;
+} | {
+    type: "usage";
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+} | {
+    type: "raw";
+    update: unknown;
+} | {
+    type: "done";
+    stopReason: StopReason;
+} | {
+    type: "error";
+    message: string;
+};
+/** Options for a single prompt turn. */
+export interface PromptOptions {
+    /** Conversation to drive the turn. The trailing user message is the active ask. */
+    messages: ChatMessage[];
+    /**
+     * Reserved session correlation key. In 0.1.0 this is accepted for forward compatibility,
+     * but every call still creates an ephemeral ACP session and renders the full conversation.
+     */
+    session?: string;
+    /** Override the working directory for this turn (default: a sandboxed session dir). */
+    workspace?: string;
+    /** Submodel hint for agents that support it (recorded; surfaced via `_meta`). */
+    model?: string | null;
+    /** ACP session mode (if the agent advertises modes). */
+    mode?: string;
+    /** Narrate tool_call/plan/thought events as part of the stream (consumer's choice). */
+    verbose?: boolean;
+    /** Cancel the in-flight turn. */
+    signal?: AbortSignal;
+}
+/** A declarative agent definition. Adding an agent is data, not code. */
+export interface AgentDef {
+    /** Stable id; what consumers pass as the OpenAI `model`. */
+    id: string;
+    /** Human-friendly name (shown in /v1/models). */
+    name: string;
+    /** Executable to spawn (resolved cross-platform by the supervisor). */
+    cmd: string;
+    /** Arguments that put the agent into ACP/stdio mode. */
+    args: string[];
+    /** Extra environment for the spawned process. */
+    env?: Record<string, string>;
+    /**
+     * Environment variables to strip from the spawned agent's env. Use this to avoid leaking
+     * the *parent* runner's per-session markers into a freshly spawned agent (e.g. spawning
+     * Claude Code from within another Claude Code session trips its nested-session guard via
+     * `CLAUDECODE`).
+     */
+    unsetEnv?: string[];
+    /** Optional default submodel for this agent. */
+    defaultModel?: string | null;
+    /** Per-agent override of the concurrency cap. */
+    maxConcurrentSessions?: number;
+    /** Per-agent override of the permission policy. */
+    permission?: PermissionPolicy;
+    /** Kill terminal commands after this many ms. */
+    terminalTimeoutMs?: number;
+    /** Fail `initialize` if it doesn't complete in this many ms. */
+    initTimeoutMs?: number;
+    /** Base working directory for the spawned process (not the session workspace). */
+    cwd?: string;
+}
+export type AgentVersionReadinessStatus = "not_applicable" | "ok" | "outdated" | "unavailable" | "unknown";
+export interface AgentVersionReadiness {
+    agentId: string;
+    status: AgentVersionReadinessStatus;
+    ok: boolean;
+    installedVersion?: string;
+    minimumVersion?: string;
+    recommendedVersion?: string;
+    updateHint?: string;
+    message: string;
+}
+export interface EngineDefaults {
+    maxConcurrentSessions: number;
+    permission: PermissionPolicy;
+    terminalTimeoutMs: number;
+    initTimeoutMs: number;
+}
+export interface ServerConfig {
+    host: string;
+    port: number;
+    auth: "bearer" | "open";
+}
+export interface KeyEntry {
+    key: string;
+    app: string;
+    /** Agent ids this key may use; `["*"]` = all enabled agents. */
+    agents: string[];
+    maxConcurrentSessions?: number;
+}
+/** Fully-resolved configuration (built-ins merged, env expanded, defaults applied). */
+export interface ResolvedConfig {
+    server: ServerConfig;
+    workspaceRoot: string;
+    keepWorkspaces: boolean;
+    defaults: EngineDefaults;
+    agents: AgentDef[];
+    keys: KeyEntry[];
+}
+/** Status snapshot for one supervised agent (for /healthz and diagnostics). */
+export interface AgentStatus {
+    id: string;
+    name: string;
+    state: "idle" | "starting" | "ready" | "needs-auth" | "error" | "stopped";
+    activeSessions: number;
+    pid?: number;
+    lastError?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE1D,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GACxF;IACE,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,yEAAyE;AACzE,MAAM,WAAW,QAAQ;IACvB,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iDAAiD;IACjD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mDAAmD;IACnD,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,2BAA2B,GAAG,gBAAgB,GAAG,IAAI,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,CAAC;AAE3G,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,2BAA2B,CAAC;IACpC,EAAE,EAAE,OAAO,CAAC;IACZ,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,IAAI,EAAE,QAAQ,EAAE,CAAC;CAClB;AAED,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;IAC1E,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Public types for @xenosystem/acp-core.
+ *
+ * The engine is framework-free: these types describe the embeddable surface that
+ * in-process consumers (and the HTTP server) build on. Nothing here knows about
+ * HTTP or the OpenAI schema.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/workspace.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Per-session sandboxed workspaces and path containment.
+ *
+ * Every session runs against an isolated directory under `workspaceRoot`. All file and
+ * terminal capability handlers MUST route paths through `containPath` so an agent cannot
+ * read or write outside its sandbox (CLAUDE.md rule 4, SPEC §8). Auto-approved permissions
+ * + a writable workspace are powerful; this containment is what bounds the blast radius.
+ */
+export interface Workspace {
+    /** Absolute path to the session's sandbox directory. */
+    dir: string;
+    /** Resolve+validate a path requested by the agent; throws if it escapes the sandbox. */
+    contain(requested: string): string;
+    /** Remove the sandbox (no-op if `keep`). */
+    cleanup(): void;
+}
+/**
+ * Throws unless `requested` resolves to a location at or beneath `root`.
+ * Handles `..` traversal (collapsed by `resolve`) and absolute paths outside the root.
+ */
+export declare function containPath(root: string, requested: string): string;
+/** Create (and return) a sandbox for `${root}/${agentId}/${sessionId}`. */
+export declare function createWorkspace(root: string, agentId: string, sessionId: string, opts?: {
+    keep?: boolean;
+    override?: string;
+}): Workspace;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,4CAA4C;IAC5C,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CASnE;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/C,SAAS,CAkBX"}

package/dist/workspace.js

@@ -0,0 +1,47 @@
+/**
+ * Per-session sandboxed workspaces and path containment.
+ *
+ * Every session runs against an isolated directory under `workspaceRoot`. All file and
+ * terminal capability handlers MUST route paths through `containPath` so an agent cannot
+ * read or write outside its sandbox (CLAUDE.md rule 4, SPEC §8). Auto-approved permissions
+ * + a writable workspace are powerful; this containment is what bounds the blast radius.
+ */
+import { mkdirSync, rmSync } from "node:fs";
+import { resolve, isAbsolute, join, sep } from "node:path";
+function sanitizeSegment(s) {
+    return s.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 80) || "x";
+}
+/**
+ * Throws unless `requested` resolves to a location at or beneath `root`.
+ * Handles `..` traversal (collapsed by `resolve`) and absolute paths outside the root.
+ */
+export function containPath(root, requested) {
+    const absRoot = resolve(root);
+    const candidate = isAbsolute(requested) ? resolve(requested) : resolve(absRoot, requested);
+    if (candidate !== absRoot && !candidate.startsWith(absRoot + sep)) {
+        throw new Error(`path escapes session workspace: ${requested} (resolved ${candidate} not within ${absRoot})`);
+    }
+    return candidate;
+}
+/** Create (and return) a sandbox for `${root}/${agentId}/${sessionId}`. */
+export function createWorkspace(root, agentId, sessionId, opts = {}) {
+    const dir = opts.override
+        ? resolve(opts.override)
+        : join(resolve(root), sanitizeSegment(agentId), sanitizeSegment(sessionId));
+    mkdirSync(dir, { recursive: true });
+    return {
+        dir,
+        contain: (requested) => containPath(dir, requested),
+        cleanup: () => {
+            if (opts.keep || opts.override)
+                return; // never auto-delete an operator-supplied dir
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAW3D,SAAS,eAAe,CAAC,CAAS;IAChC,OAAO,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,SAAiB;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC3F,IAAI,SAAS,KAAK,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,GAAG,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,KAAK,CACb,mCAAmC,SAAS,cAAc,SAAS,eAAe,OAAO,GAAG,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,OAAe,EACf,SAAiB,EACjB,OAA8C,EAAE;IAEhD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ;QACvB,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QACxB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9E,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEpC,OAAO;QACL,GAAG;QACH,OAAO,EAAE,CAAC,SAAiB,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,SAAS,CAAC;QAC3D,OAAO,EAAE,GAAG,EAAE;YACZ,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ;gBAAE,OAAO,CAAC,6CAA6C;YACrF,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAChD,CAAC;YAAC,MAAM,CAAC;gBACP,iBAAiB;YACnB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@xenosystem/acp-core",
+  "version": "0.1.1",
+  "description": "Embeddable ACP-client engine: supervise ACP agents and stream structured events. The framework-free core of xeno-acp.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./agent-version-policy": {
+      "types": "./dist/agent-version-policy.d.ts",
+      "import": "./dist/agent-version-policy.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "acp",
+    "agent-client-protocol",
+    "ai-agent",
+    "xeno"
+  ],
+  "homepage": "https://xenostudio.ai/product/acp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XENO-CORPORATION/xeno-acp.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/XENO-CORPORATION/xeno-acp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "0.24.0",
+    "strip-json-comments": "^5.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rimraf dist *.tsbuildinfo"
+  }
+}