@codespar/types 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# @codespar/types
+
+Zero-dependency TypeScript package defining the shared session interface hierarchy for CodeSpar runtimes.
+
+Any runtime that implements `SessionBase` — the managed CodeSpar backend, Anthropic Managed Agents, a self-hosted server, or a test double — is a first-class citizen in the SDK ecosystem. The contract is the only coupling between runtimes and the tools that run on top of them.
+
+## Install
+
+```bash
+npm install @codespar/types
+```
+
+## Interfaces
+
+### `SessionBase`
+
+The minimal interface any runtime must implement.
+
+```typescript
+import type { SessionBase } from "@codespar/types";
+
+interface SessionBase {
+  readonly id: string;
+  readonly status: "active" | "closed" | "error";
+
+  execute(toolName: string, params: Record<string, unknown>): Promise<ToolResult>;
+  send(message: string): Promise<SendResult>;
+  sendStream(message: string): AsyncIterable<StreamEvent>;
+  connections(): Promise<BaseConnection[]>;
+  close(): Promise<void>;
+}
+```
+
+### `Session`
+
+The codespar-specific extension of `SessionBase`, used when a session was created through the managed CodeSpar API.
+
+```typescript
+import type { Session } from "@codespar/types";
+
+interface Session extends SessionBase {
+  proxyExecute(request: ProxyRequest): Promise<ProxyResult>;
+  authorize(serverId: string, config: AuthConfig): Promise<AuthResult>;
+  mcp?: {
+    url: string;
+    headers: Record<string, string>;
+  };
+}
+```
+
+### `isCodesparSession`
+
+Type guard to narrow a `SessionBase` to `Session` when you need codespar-specific methods.
+
+```typescript
+import { isCodesparSession } from "@codespar/types";
+
+function useSession(session: SessionBase) {
+  if (isCodesparSession(session)) {
+    // session is Session here — proxyExecute, authorize, mcp available
+    const config = session.mcp;
+  }
+}
+```
+
+## Wire types
+
+| Type | Description |
+|------|-------------|
+| `ToolResult` | Return value of `execute()` — `success`, `data`, `error`, `duration`, `server`, `tool` |
+| `SendResult` | Return value of `send()` — `message`, `tool_calls`, `iterations` |
+| `StreamEvent` | Union of events yielded by `sendStream()` — `user_message`, `assistant_text`, `tool_use`, `tool_result`, `done`, `error` |
+| `BaseConnection` | Entry from `connections()` — `id`, `connected` |
+| `ServerConnection` | Extended connection with name and provider metadata |
+| `ProxyRequest` | Input to `proxyExecute()` — `server`, `endpoint`, `method`, `body`, `headers` |
+| `ProxyResult` | Return value of `proxyExecute()` — `status`, `data`, `headers`, `duration`, `proxy_call_id` |
+| `AuthConfig` | Input to `authorize()` — `redirectUri`, `scopes?` |
+| `AuthResult` | Return value of `authorize()` — `linkToken`, `authorizeUrl`, `expiresAt` |
+
+## Conformance testing
+
+`@codespar/types` ships a `runContractSuite` helper under a `/testing` subpath export. It registers a Vitest test suite that exercises the five `SessionBase` methods against a live HTTP endpoint.
+
+```typescript
+// my-runtime.test.ts
+import { runContractSuite } from "@codespar/types/testing";
+
+// Skip unless the env vars are present
+const apiKey = process.env["MY_RUNTIME_API_KEY"];
+const baseUrl = process.env["MY_RUNTIME_BASE_URL"] ?? "http://localhost:3000";
+
+if (apiKey) {
+  runContractSuite(baseUrl, apiKey);
+}
+```
+
+The suite opens a session via `POST /v1/sessions` with `Authorization: Bearer <apiKey>` and body `{ servers: [], user_id: "contract-suite" }`, then validates:
+- `execute()` calls a registered tool and returns a `ToolResult`
+- `send()` returns a `SendResult` with a `message` field
+- `sendStream()` yields well-typed `StreamEvent`s including a `done` event
+- `connections()` returns entries with `id` and `connected` fields
+- `close()` transitions `session.status` to `"closed"`
+
+See [docs/custom-session-runtime.md](../../docs/custom-session-runtime.md) for a full implementation guide.
+
+## License
+
+MIT — [codespar.dev](https://codespar.dev)

package/dist/guards.d.ts

@@ -0,0 +1,3 @@
+import type { SessionBase, Session } from "./types.js";
+export declare function isCodesparSession(s: SessionBase): s is Session;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,IAAI,OAAO,CAE9D"}

package/dist/guards.js

@@ -0,0 +1,4 @@
+export function isCodesparSession(s) {
+    return "proxyExecute" in s && "authorize" in s;
+}
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,iBAAiB,CAAC,CAAc;IAC9C,OAAO,cAAc,IAAI,CAAC,IAAI,WAAW,IAAI,CAAC,CAAC;AACjD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./guards.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./guards.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/dist/testing/contract-suite.d.ts

@@ -0,0 +1,16 @@
+export declare class InvalidBaseUrlError extends Error {
+    constructor(url: string);
+}
+/**
+ * Register the full session contract test suite against a live backend.
+ *
+ * Validates the baseUrl before issuing any request: only https:// URLs and
+ * localhost are accepted. Throws InvalidBaseUrlError synchronously for
+ * invalid URLs so misconfigured CI environments fail early rather than
+ * leaking the apiKey to an arbitrary host.
+ *
+ * @param baseUrl - API base URL (e.g. "https://your-runtime.example" or "http://localhost:3000")
+ * @param apiKey  - Bearer token for session creation
+ */
+export declare function runContractSuite(baseUrl: string, apiKey: string): void;
+//# sourceMappingURL=contract-suite.d.ts.map

package/dist/testing/contract-suite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-suite.d.ts","sourceRoot":"","sources":["../../src/testing/contract-suite.ts"],"names":[],"mappings":"AAGA,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,GAAG,EAAE,MAAM;CAMxB;AAmKD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA8EtE"}

package/dist/testing/contract-suite.js

@@ -0,0 +1,257 @@
+import { describe, it, expect, afterEach } from "vitest";
+export class InvalidBaseUrlError extends Error {
+    constructor(url) {
+        super(`Invalid base URL "${url}" — must use https:// protocol unless the host is localhost`);
+        this.name = "InvalidBaseUrlError";
+    }
+}
+function validateBaseUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new InvalidBaseUrlError(rawUrl);
+    }
+    if (parsed.hostname !== "localhost" && parsed.protocol !== "https:") {
+        throw new InvalidBaseUrlError(rawUrl);
+    }
+}
+// Minimal SSE parser used only within the contract test suite.
+async function* parseSse(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let sep;
+            while ((sep = buffer.indexOf("\n\n")) !== -1) {
+                const chunk = buffer.slice(0, sep);
+                buffer = buffer.slice(sep + 2);
+                let eventName = "message";
+                let dataLine = "";
+                for (const line of chunk.split("\n")) {
+                    if (line.startsWith("event:"))
+                        eventName = line.slice(6).trim();
+                    else if (line.startsWith("data:"))
+                        dataLine += line.slice(5).trim();
+                }
+                if (!dataLine)
+                    continue;
+                let payload;
+                try {
+                    payload = JSON.parse(dataLine);
+                }
+                catch {
+                    continue;
+                }
+                // Yield discriminated StreamEvent from the known event names.
+                // Unrecognised events are silently skipped — the variant list is
+                // defined by the StreamEvent union in types.ts.
+                if (eventName === "user_message")
+                    yield { type: "user_message", content: payload.content };
+                else if (eventName === "assistant_text")
+                    yield {
+                        type: "assistant_text",
+                        content: payload.content,
+                        iteration: payload.iteration,
+                    };
+                else if (eventName === "tool_use")
+                    yield {
+                        type: "tool_use",
+                        id: payload.id,
+                        name: payload.name,
+                        input: payload.input,
+                    };
+                else if (eventName === "tool_result")
+                    yield { type: "tool_result", toolCall: payload };
+                else if (eventName === "done")
+                    yield { type: "done", result: payload };
+                else if (eventName === "error")
+                    yield {
+                        type: "error",
+                        error: payload.error,
+                        message: payload.message,
+                    };
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+// Builds a minimal SessionBase from raw fetch calls so the contract suite
+// can run against any backend that implements the codespar session API.
+async function openSession(baseUrl, apiKey) {
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+    };
+    const res = await fetch(`${baseUrl}/v1/sessions`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ servers: [], user_id: "contract-suite" }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`session create failed: ${res.status} ${text}`);
+    }
+    const raw = (await res.json());
+    const state = { id: raw.id, status: raw.status };
+    return {
+        get id() {
+            return state.id;
+        },
+        get status() {
+            return state.status;
+        },
+        async execute(toolName, params) {
+            const r = await fetch(`${baseUrl}/v1/sessions/${state.id}/execute`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ tool: toolName, input: params }),
+            });
+            if (!r.ok) {
+                const body = await r.text();
+                return {
+                    success: false,
+                    data: null,
+                    error: `${r.status}: ${body}`,
+                    duration: 0,
+                    server: "",
+                    tool: toolName,
+                };
+            }
+            return (await r.json());
+        },
+        async send(message) {
+            const r = await fetch(`${baseUrl}/v1/sessions/${state.id}/send`, {
+                method: "POST",
+                headers: { ...headers, Accept: "application/json" },
+                body: JSON.stringify({ message }),
+            });
+            if (!r.ok) {
+                const body = await r.text();
+                throw new Error(`send failed: ${r.status} ${body}`);
+            }
+            return (await r.json());
+        },
+        async *sendStream(message) {
+            const r = await fetch(`${baseUrl}/v1/sessions/${state.id}/send`, {
+                method: "POST",
+                headers: { ...headers, Accept: "text/event-stream" },
+                body: JSON.stringify({ message }),
+            });
+            if (!r.ok || !r.body) {
+                const body = await r.text();
+                throw new Error(`sendStream failed: ${r.status} ${body}`);
+            }
+            yield* parseSse(r.body);
+        },
+        async connections() {
+            const r = await fetch(`${baseUrl}/v1/sessions/${state.id}/connections`, { headers });
+            if (!r.ok)
+                return [];
+            const payload = (await r.json());
+            return payload.servers;
+        },
+        async close() {
+            await fetch(`${baseUrl}/v1/sessions/${state.id}`, {
+                method: "DELETE",
+                headers,
+            });
+            state.status = "closed";
+        },
+    };
+}
+/**
+ * Register the full session contract test suite against a live backend.
+ *
+ * Validates the baseUrl before issuing any request: only https:// URLs and
+ * localhost are accepted. Throws InvalidBaseUrlError synchronously for
+ * invalid URLs so misconfigured CI environments fail early rather than
+ * leaking the apiKey to an arbitrary host.
+ *
+ * @param baseUrl - API base URL (e.g. "https://your-runtime.example" or "http://localhost:3000")
+ * @param apiKey  - Bearer token for session creation
+ */
+export function runContractSuite(baseUrl, apiKey) {
+    validateBaseUrl(baseUrl);
+    describe("session contract suite", () => {
+        let session = null;
+        afterEach(async () => {
+            try {
+                if (session)
+                    await session.close();
+            }
+            finally {
+                session = null;
+            }
+        });
+        it("execute() calls a registered tool and returns a ToolResult", async () => {
+            session = await openSession(baseUrl, apiKey);
+            const result = await session.execute("codespar_list_tools", {});
+            expect(result).toMatchObject({
+                success: expect.any(Boolean),
+                data: expect.anything(),
+                error: expect.anything(),
+                duration: expect.any(Number),
+                server: expect.any(String),
+                tool: expect.any(String),
+            });
+        });
+        it("send() returns a SendResult with a message field", async () => {
+            session = await openSession(baseUrl, apiKey);
+            const result = await session.send("hello");
+            expect(result).toMatchObject({
+                message: expect.any(String),
+                tool_calls: expect.any(Array),
+                iterations: expect.any(Number),
+            });
+        });
+        it("sendStream() yields well-typed StreamEvents including done", async () => {
+            session = await openSession(baseUrl, apiKey);
+            const events = [];
+            for await (const ev of session.sendStream("hello")) {
+                events.push(ev);
+                if (ev.type === "done" || ev.type === "error")
+                    break;
+            }
+            expect(events.length).toBeGreaterThan(0);
+            const types = new Set(events.map((e) => e.type));
+            // Every event type must be one of the six discriminated variants.
+            const valid = new Set([
+                "user_message",
+                "assistant_text",
+                "tool_use",
+                "tool_result",
+                "done",
+                "error",
+            ]);
+            for (const t of types) {
+                expect(valid.has(t)).toBe(true);
+            }
+        });
+        it("connections() returns entries with id and connected fields", async () => {
+            session = await openSession(baseUrl, apiKey);
+            const conns = await session.connections();
+            expect(Array.isArray(conns)).toBe(true);
+            for (const c of conns) {
+                expect(typeof c.id).toBe("string");
+                expect(typeof c.connected).toBe("boolean");
+            }
+        });
+        it("close() transitions session.status to closed", async () => {
+            session = await openSession(baseUrl, apiKey);
+            expect(session.status).toBe("active");
+            await session.close();
+            expect(session.status).toBe("closed");
+            session = null; // afterEach guard — already closed
+        });
+    });
+}
+//# sourceMappingURL=contract-suite.js.map

package/dist/testing/contract-suite.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+export interface SessionBase {
+    readonly id: string;
+    readonly status: "active" | "closed" | "error";
+    execute(toolName: string, params: Record<string, unknown>): Promise<ToolResult>;
+    send(message: string): Promise<SendResult>;
+    sendStream(message: string): AsyncIterable<StreamEvent>;
+    connections(): Promise<BaseConnection[]>;
+    close(): Promise<void>;
+}
+export interface Session extends SessionBase {
+    proxyExecute(request: ProxyRequest): Promise<ProxyResult>;
+    authorize(serverId: string, config: AuthConfig): Promise<AuthResult>;
+    mcp?: {
+        url: string;
+        headers: Record<string, string>;
+    };
+}
+export type BaseConnection = {
+    id: string;
+    connected: boolean;
+};
+export interface ServerConnection {
+    id: string;
+    name: string;
+    category: string;
+    country: string;
+    auth_type: "oauth" | "api_key" | "cert" | "none";
+    connected: boolean;
+}
+export interface CreateSessionRequest {
+    servers: string[];
+    metadata?: Record<string, string>;
+    projectId?: string;
+}
+export interface ToolResult {
+    success: boolean;
+    data: unknown;
+    error: string | null;
+    duration: number;
+    server: string;
+    tool: string;
+    tool_call_id?: string;
+    called_at?: string;
+}
+export interface SendResult {
+    message: string;
+    tool_calls: ToolCallRecord[];
+    iterations: number;
+}
+export interface ToolCallRecord {
+    id: string;
+    tool_name: string;
+    server_id: string;
+    status: "success" | "error";
+    duration_ms: number;
+    input: unknown;
+    output: unknown;
+    error_code: string | null;
+}
+export type StreamEvent = {
+    type: "user_message";
+    content: string;
+} | {
+    type: "assistant_text";
+    content: string;
+    iteration: number;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: "tool_result";
+    toolCall: ToolCallRecord;
+} | {
+    type: "done";
+    result: SendResult;
+} | {
+    type: "error";
+    error: string;
+    message?: string;
+};
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface ProxyRequest {
+    server: string;
+    endpoint: string;
+    method: HttpMethod;
+    body?: unknown;
+    params?: Record<string, string | number | boolean>;
+    headers?: Record<string, string>;
+}
+export interface ProxyResult {
+    status: number;
+    data: unknown;
+    headers: Record<string, string>;
+    duration: number;
+    proxy_call_id?: string;
+}
+export interface AuthConfig {
+    redirectUri: string;
+    scopes?: string;
+}
+export interface AuthResult {
+    linkToken: string;
+    authorizeUrl: string;
+    expiresAt: 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":"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"}

package/dist/types.js

@@ -0,0 +1,3 @@
+/* ── Runtime-agnostic session base ─────────────────────────────── */
+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,sEAAsE"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@codespar/types",
+  "version": "0.1.0",
+  "description": "Shared session interface contract for codespar runtimes",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./testing": {
+      "development": {
+        "import": "./dist/testing/contract-suite.js",
+        "types": "./dist/testing/contract-suite.d.ts"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "codespar",
+    "session",
+    "contract",
+    "sdk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codespar/codespar-core",
+    "directory": "packages/session-contract"
+  },
+  "homepage": "https://codespar.dev",
+  "bugs": {
+    "url": "https://github.com/codespar/codespar-core/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  }
+}