vino-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vinh Bui
+
+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

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+# vino-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero-dependency TypeScript client for the
+[vino-backend](https://github.com/vinhbt241/vino-backend) HTTP API. Stream runs,
+continue conversations, and read transcripts through one ergonomic client —
+no hand-rolled SSE parsing or error mapping.
+
+- **Runs on**: Node 18+, browsers, Deno, Bun (anything with `fetch`).
+- **Dependencies**: none at runtime.
+- **Types**: strict, handwritten from the server's documented wire contract.
+
+## Install
+
+```bash
+npm install vino-sdk
+```
+
+## Quick start
+
+The server defaults to `http://127.0.0.1:8080`.
+
+```ts
+import { Vino } from "vino-sdk";
+
+const vino = new Vino();
+
+// One-shot: get the final answer and tool activity.
+const result = await vino.run({
+  messages: [{ role: "user", content: "List the files in the current directory." }],
+});
+
+console.log(result.finalMessage.content);
+console.log(result.text);                 // same text, streamed deltas concatenated
+console.log(result.toolResults);          // [{ id, name, result }]
+console.log(result.conversationId);
+```
+
+### Stream a run
+
+`stream()` returns an async generator of typed, discriminated events:
+
+```ts
+for await (const event of vino.stream({
+  messages: [{ role: "user", content: "List the files in ." }],
+})) {
+  switch (event.type) {
+    case "run_started": break;
+    case "text_delta": process.stdout.write(event.text); break;
+    case "tool_call_started": console.log("calling", event.name, event.arguments); break;
+    case "tool_result": console.log("result", event.result); break;
+    case "run_finished": console.log("done", event.finalMessage); break;
+    case "error": console.error(event.error); break;
+  }
+}
+```
+
+### Conversations
+
+```ts
+// List, newest first (paginated).
+const page = await vino.listConversations({ limit: 20, order: "desc" });
+console.log(page.nextCursor); // null on the last page
+
+// Read a transcript.
+const conversation = await vino.getConversation("12");
+
+// Continue a conversation: pass conversationId on a new run/resume.
+const next = await vino.run({
+  conversationId: "12",
+  messages: [{ role: "user", content: "What next?" }],
+});
+```
+
+### Health
+
+```ts
+await vino.health(); // { ok: true }
+```
+
+## Configuration
+
+```ts
+const vino = new Vino({
+  baseUrl: "http://127.0.0.1:8080", // default
+  headers: { "x-custom": "value" }, // merged into every request
+  apiKey: "sk-...",                 // sent as `Authorization: Bearer <key>`
+  timeout: 30_000,                  // default request timeout, ms
+});
+```
+
+`apiKey` is inert until the server grows auth; the SDK already sends it as a
+bearer token so a future server change is a config update, not an SDK upgrade.
+
+Every method accepts an optional `AbortSignal` as its last argument
+(`run`/`stream` take it via `RunOptions.signal`):
+
+```ts
+const controller = new AbortController();
+const result = await vino.run({ messages: [...], signal: controller.signal });
+// controller.abort() cancels the in-flight request.
+```
+
+## Run options
+
+```ts
+interface RunOptions {
+  messages: OutgoingMessage[];   // { role: "user" | "assistant"; content: string }
+  systemPrompt?: string;
+  maxIterations?: number;        // 0/absent -> server default (50)
+  toolTimeout?: string;          // Go duration, e.g. "30s"
+  requestId?: string;            // exactly-once: retries resume the same run
+  conversationId?: string;       // present -> append to this conversation
+  signal?: AbortSignal;
+}
+```
+
+## Errors
+
+```ts
+import { VinoError, VinoHttpError, VinoStreamError } from "vino-sdk";
+
+try {
+  await vino.run({ messages: [{ role: "user", content: "hi" }] });
+} catch (err) {
+  if (err instanceof VinoHttpError) {
+    console.error(err.status, err.message); // non-2xx before streaming
+  } else if (err instanceof VinoStreamError) {
+    console.error(err.message);             // terminal SSE error / premature end
+  }
+}
+```
+
+`stream()` yields the terminal `error` event rather than throwing it;
+`run()` throws `VinoStreamError` instead.
+
+## Browser / CORS note
+
+The vino-backend server sends CORS headers, so a browser client can call the
+API cross-origin directly — no reverse proxy required. If the server is
+configured to allow only specific origins, make sure your app's origin is in
+the allow-list.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test            # unit + integration (integration boots the real Go server)
+npm run build       # emit dist/
+```
+
+Integration tests vendor the vino-backend server under
+`test/fixture/vino-backend` and boot it with `go run` against a mock
+OpenAI-compatible provider, so no API key is required. When Go is absent, the
+integration suite auto-skips.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+import type { Conversation, ListConversationsResult, ListQuery, RunEvent, RunOptions, RunResult, VinoOptions } from "./types.js";
+/**
+ * Client for the vino-backend HTTP API.
+ *
+ * ```ts
+ * const vino = new Vino({ baseUrl: "http://127.0.0.1:8080" });
+ *
+ * // Stream a run as typed events:
+ * for await (const ev of vino.stream({ messages: [{ role: "user", content: "hi" }] })) {
+ *   if (ev.type === "text_delta") process.stdout.write(ev.text);
+ * }
+ *
+ * // Or just the final result:
+ * const result = await vino.run({ messages: [{ role: "user", content: "hi" }] });
+ * console.log(result.finalMessage.content);
+ * ```
+ */
+export declare class Vino {
+    private readonly transport;
+    constructor(options?: VinoOptions);
+    /** Liveness probe. Resolves `{ ok: true }` when the server is up. */
+    health(signal?: AbortSignal): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Runs the agent and resolves the completed result, folding the stream into
+     * `finalMessage`, `text`, `toolResults`, and run metadata. Throws
+     * {@link VinoStreamError} if the run aborts.
+     */
+    run(options: RunOptions): Promise<RunResult>;
+    /**
+     * Streams a run as typed {@link RunEvent}s. The terminal `error` event is
+     * yielded (not thrown); use {@link run} to get a thrown {@link VinoStreamError}
+     * instead. Pass `conversationId` to append to an existing conversation.
+     */
+    stream(options: RunOptions): AsyncGenerator<RunEvent>;
+    /** Lists conversations, newest first by default. */
+    listConversations(query?: ListQuery, signal?: AbortSignal): Promise<ListConversationsResult>;
+    /** Fetches one conversation with its full transcript. */
+    getConversation(id: string, signal?: AbortSignal): Promise<Conversation>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACvB,SAAS,EAET,QAAQ,EACR,UAAU,EAEV,SAAS,EAET,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,OAAO,GAAE,WAAgB;IAarC,qEAAqE;IACrE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAItD;;;;OAIG;IACG,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IA0ClD;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC;IAQrD,oDAAoD;IACpD,iBAAiB,CACf,KAAK,GAAE,SAAc,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,uBAAuB,CAAC;IAInC,yDAAyD;IACzD,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAGzE"}

package/dist/client.js

@@ -0,0 +1,108 @@
+import { VinoStreamError } from "./errors.js";
+import { Transport } from "./transport.js";
+/**
+ * Client for the vino-backend HTTP API.
+ *
+ * ```ts
+ * const vino = new Vino({ baseUrl: "http://127.0.0.1:8080" });
+ *
+ * // Stream a run as typed events:
+ * for await (const ev of vino.stream({ messages: [{ role: "user", content: "hi" }] })) {
+ *   if (ev.type === "text_delta") process.stdout.write(ev.text);
+ * }
+ *
+ * // Or just the final result:
+ * const result = await vino.run({ messages: [{ role: "user", content: "hi" }] });
+ * console.log(result.finalMessage.content);
+ * ```
+ */
+export class Vino {
+    transport;
+    constructor(options = {}) {
+        const baseUrl = options.baseUrl ?? "http://127.0.0.1:8080";
+        const headers = { ...(options.headers ?? {}) };
+        if (options.apiKey)
+            headers["authorization"] = `Bearer ${options.apiKey}`;
+        this.transport = new Transport({
+            baseUrl,
+            headers,
+            timeout: options.timeout,
+            fetch: options.fetch,
+        });
+    }
+    /** Liveness probe. Resolves `{ ok: true }` when the server is up. */
+    health(signal) {
+        return this.transport.health(signal);
+    }
+    /**
+     * Runs the agent and resolves the completed result, folding the stream into
+     * `finalMessage`, `text`, `toolResults`, and run metadata. Throws
+     * {@link VinoStreamError} if the run aborts.
+     */
+    async run(options) {
+        let conversationId = "";
+        let submissionId = "";
+        let resumed = false;
+        let text = "";
+        const toolResults = [];
+        let finalMessage = { role: "assistant" };
+        let finished = false;
+        for await (const event of this.stream(options)) {
+            switch (event.type) {
+                case "run_started":
+                    conversationId = event.conversationId;
+                    submissionId = event.submissionId;
+                    resumed = event.resumed;
+                    break;
+                case "text_delta":
+                    text += event.text;
+                    break;
+                case "tool_result":
+                    toolResults.push(event.error === undefined
+                        ? { id: event.id, name: event.name, result: event.result }
+                        : { id: event.id, name: event.name, result: event.result, error: event.error });
+                    break;
+                case "run_finished":
+                    finished = true;
+                    finalMessage = event.finalMessage;
+                    break;
+                case "error":
+                    throw new VinoStreamError(event.error);
+            }
+        }
+        if (!finished) {
+            throw new VinoStreamError("run stream ended before run_finished");
+        }
+        return { conversationId, submissionId, resumed, finalMessage, text, toolResults };
+    }
+    /**
+     * Streams a run as typed {@link RunEvent}s. The terminal `error` event is
+     * yielded (not thrown); use {@link run} to get a thrown {@link VinoStreamError}
+     * instead. Pass `conversationId` to append to an existing conversation.
+     */
+    stream(options) {
+        const { conversationId, signal, ...rest } = options;
+        const path = conversationId
+            ? `/conversations/${encodeURIComponent(conversationId)}/runs`
+            : "/runs";
+        return this.transport.streamRun(path, toRunBody(rest), signal);
+    }
+    /** Lists conversations, newest first by default. */
+    listConversations(query = {}, signal) {
+        return this.transport.listConversations(query, signal);
+    }
+    /** Fetches one conversation with its full transcript. */
+    getConversation(id, signal) {
+        return this.transport.getConversation(id, signal);
+    }
+}
+function toRunBody(options) {
+    return {
+        systemPrompt: options.systemPrompt ?? "",
+        messages: options.messages,
+        maxIterations: options.maxIterations ?? 0,
+        toolTimeout: options.toolTimeout ?? "",
+        requestId: options.requestId ?? "",
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+/** Base class for every error thrown by the SDK. */
+export declare class VinoError extends Error {
+    constructor(message: string);
+}
+/**
+ * A non-2xx HTTP response. Carries the HTTP status and, when present, the
+ * server's `{"error":"..."}` message.
+ */
+export declare class VinoHttpError extends VinoError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * A failure after the run stream opened: either a terminal SSE `error` event
+ * or a stream that ended before `run_finished`.
+ */
+export declare class VinoStreamError extends VinoError {
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI5C;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,SAAS;CAAG"}

package/dist/errors.js

@@ -0,0 +1,25 @@
+/** Base class for every error thrown by the SDK. */
+export class VinoError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/**
+ * A non-2xx HTTP response. Carries the HTTP status and, when present, the
+ * server's `{"error":"..."}` message.
+ */
+export class VinoHttpError extends VinoError {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * A failure after the run stream opened: either a terminal SSE `error` event
+ * or a stream that ended before `run_finished`.
+ */
+export class VinoStreamError extends VinoError {
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,SAAS;IACjC,MAAM,CAAS;IAExB,YAAY,MAAc,EAAE,OAAe;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,SAAS;CAAG"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Vino } from "./client.js";
+export { VinoError, VinoHttpError, VinoStreamError } from "./errors.js";
+export type { Conversation, ConversationSummary, Entry, ForkRef, LatestMessage, ListConversationsResult, ListQuery, Message, OutgoingMessage, OutgoingRole, OwnerRef, Role, RunEvent, RunOptions, RunResult, ToolCall, ToolResult, VinoOptions, } from "./types.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,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,KAAK,EACL,OAAO,EACP,aAAa,EACb,uBAAuB,EACvB,SAAS,EACT,OAAO,EACP,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Vino } from "./client.js";
+export { VinoError, VinoHttpError, VinoStreamError } from "./errors.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,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,37 @@
+import type { Conversation, ListConversationsResult, ListQuery, RunEvent, RunRequestBody } from "./types.js";
+/** The subset of `fetch` the transport relies on, injectable for tests. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Options for building a {@link Transport}. */
+export interface TransportOptions {
+    baseUrl: string;
+    headers: Record<string, string>;
+    fetch?: FetchLike;
+    timeout?: number;
+}
+/**
+ * Internal HTTP layer. Owns base-URL joining, header/query handling, status
+ * to error mapping, and the SSE stream. Consumers use {@link Vino}, not this.
+ */
+export declare class Transport {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly fetchImpl;
+    private readonly timeout?;
+    constructor(options: TransportOptions);
+    health(signal?: AbortSignal): Promise<{
+        ok: boolean;
+    }>;
+    streamRun(path: string, body: RunRequestBody, signal?: AbortSignal): AsyncGenerator<RunEvent>;
+    listConversations(query: ListQuery, signal?: AbortSignal): Promise<ListConversationsResult>;
+    getConversation(id: string, signal?: AbortSignal): Promise<Conversation>;
+    private url;
+    private queryParams;
+    private requestJSON;
+}
+/**
+ * Parses a byte stream of server-sent events into typed {@link RunEvent}s.
+ * Frames are `event: <name>\ndata: <json>\n\n`. Unknown event names are
+ * skipped (forward compatibility); malformed JSON raises {@link VinoStreamError}.
+ */
+export declare function parseSSE(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<RunEvent>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACvB,SAAS,EAET,QAAQ,EACR,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,2EAA2E;AAC3E,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;gBAEtB,OAAO,EAAE,gBAAgB;IAOrC,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAItD,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,QAAQ,CAAC;IAI3B,iBAAiB,CACf,KAAK,EAAE,SAAS,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,uBAAuB,CAAC;IAUnC,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IASxE,OAAO,CAAC,GAAG;IAKX,OAAO,CAAC,WAAW;YAQL,WAAW;CAsB1B;AAED;;;;GAIG;AACH,wBAAuB,QAAQ,CAC7B,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAChC,cAAc,CAAC,QAAQ,CAAC,CAqB1B"}

package/dist/transport.js

@@ -0,0 +1,217 @@
+import { VinoHttpError, VinoStreamError } from "./errors.js";
+/**
+ * Internal HTTP layer. Owns base-URL joining, header/query handling, status
+ * to error mapping, and the SSE stream. Consumers use {@link Vino}, not this.
+ */
+export class Transport {
+    baseUrl;
+    headers;
+    fetchImpl;
+    timeout;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.headers = { ...options.headers };
+        this.fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+        this.timeout = options.timeout;
+    }
+    health(signal) {
+        return this.requestJSON("GET", "/health", undefined, signal);
+    }
+    streamRun(path, body, signal) {
+        return streamEvents(this.fetchImpl, this.url(path), this.headers, this.timeout, body, signal);
+    }
+    listConversations(query, signal) {
+        return this.requestJSON("GET", "/conversations", undefined, signal, this.queryParams(query));
+    }
+    getConversation(id, signal) {
+        return this.requestJSON("GET", `/conversations/${encodeURIComponent(id)}`, undefined, signal);
+    }
+    url(path, query) {
+        const qs = query?.toString();
+        return qs ? `${this.baseUrl}${path}?${qs}` : `${this.baseUrl}${path}`;
+    }
+    queryParams(query) {
+        const params = new URLSearchParams();
+        if (query.limit !== undefined)
+            params.set("limit", String(query.limit));
+        if (query.cursor !== undefined)
+            params.set("cursor", query.cursor);
+        if (query.order !== undefined)
+            params.set("order", query.order);
+        return params;
+    }
+    async requestJSON(method, path, body, signal, query) {
+        const { signal: effective, cleanup } = withTimeout(signal, this.timeout);
+        try {
+            const headers = { ...this.headers };
+            const init = { method, headers, signal: effective };
+            if (body !== undefined) {
+                headers["content-type"] = "application/json";
+                init.body = JSON.stringify(body);
+            }
+            const res = await this.fetchImpl(this.url(path, query), init);
+            if (!res.ok)
+                throw await toHttpError(res);
+            return (await res.json());
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+/**
+ * Parses a byte stream of server-sent events into typed {@link RunEvent}s.
+ * Frames are `event: <name>\ndata: <json>\n\n`. Unknown event names are
+ * skipped (forward compatibility); malformed JSON raises {@link VinoStreamError}.
+ */
+export async function* parseSSE(chunks) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for await (const chunk of chunks) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let sep = buffer.indexOf("\n\n");
+        while (sep !== -1) {
+            const frame = buffer.slice(0, sep);
+            buffer = buffer.slice(sep + 2);
+            const event = parseFrame(frame);
+            if (event)
+                yield event;
+            sep = buffer.indexOf("\n\n");
+        }
+    }
+    buffer += decoder.decode();
+    if (buffer.length > 0) {
+        const event = parseFrame(buffer);
+        if (event)
+            yield event;
+    }
+}
+function parseFrame(frame) {
+    let name = "message";
+    const dataLines = [];
+    for (const line of frame.split("\n")) {
+        if (line.startsWith("event:")) {
+            name = line.slice("event:".length).trim();
+        }
+        else if (line.startsWith("data:")) {
+            dataLines.push(line.slice("data:".length).replace(/^ /, ""));
+        }
+    }
+    if (dataLines.length === 0)
+        return null;
+    let payload;
+    try {
+        payload = JSON.parse(dataLines.join("\n"));
+    }
+    catch {
+        throw new VinoStreamError(`malformed SSE data for event "${name}"`);
+    }
+    return toEvent(name, payload);
+}
+function toEvent(name, payload) {
+    switch (name) {
+        case "run_started": {
+            const p = payload;
+            return {
+                type: "run_started",
+                conversationId: p.conversationId ?? "",
+                submissionId: p.submissionId ?? "",
+                resumed: p.resumed === true,
+            };
+        }
+        case "text_delta": {
+            const p = payload;
+            return { type: "text_delta", text: p.text ?? "" };
+        }
+        case "tool_call_started": {
+            const p = payload;
+            return {
+                type: "tool_call_started",
+                id: p.id ?? "",
+                name: p.name ?? "",
+                arguments: p.arguments ?? null,
+            };
+        }
+        case "tool_result": {
+            const p = payload;
+            const base = {
+                type: "tool_result",
+                id: p.id ?? "",
+                name: p.name ?? "",
+                result: p.result ?? "",
+            };
+            return p.error === undefined ? base : { ...base, error: p.error };
+        }
+        case "run_finished": {
+            const p = payload;
+            return {
+                type: "run_finished",
+                conversationId: p.conversationId ?? "",
+                finalMessage: p.finalMessage ?? { role: "assistant" },
+            };
+        }
+        case "error": {
+            const p = payload;
+            return { type: "error", error: p.error ?? "" };
+        }
+        default:
+            return null;
+    }
+}
+async function* streamEvents(fetchImpl, url, headers, timeout, body, signal) {
+    const { signal: effective, cleanup } = withTimeout(signal, timeout);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                ...headers,
+                "content-type": "application/json",
+                accept: "text/event-stream",
+            },
+            body: JSON.stringify(body),
+            signal: effective,
+        });
+        if (!res.ok)
+            throw await toHttpError(res);
+        if (!res.body)
+            throw new VinoStreamError("response body is empty");
+        yield* parseSSE(res.body);
+    }
+    finally {
+        cleanup();
+    }
+}
+async function toHttpError(res) {
+    let message = `HTTP ${res.status}`;
+    try {
+        const data = (await res.json());
+        if (typeof data?.error === "string")
+            message = data.error;
+    }
+    catch {
+        // Non-JSON error body; keep the status-based message.
+    }
+    return new VinoHttpError(res.status, message);
+}
+function withTimeout(signal, timeoutMs) {
+    if (timeoutMs === undefined) {
+        return { signal, cleanup: () => { } };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new VinoStreamError(`request timed out after ${timeoutMs}ms`)), timeoutMs);
+    if (signal === undefined) {
+        return { signal: controller.signal, cleanup: () => clearTimeout(timer) };
+    }
+    const onAbort = () => controller.abort(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+        onAbort();
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+        },
+    };
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Wire-level types for the vino-backend HTTP API. These mirror the JSON
+ * documented in the server's `docs/api.md` and are the single source of
+ * truth for the client's request/response shapes.
+ */
+/** Author of a message as it appears in a server-side transcript. */
+export type Role = "system" | "user" | "assistant" | "tool";
+/** Role a caller is allowed to send in a run/resume request. */
+export type OutgoingRole = "user" | "assistant";
+/** A model tool call (part of an assistant message). */
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: unknown;
+}
+/**
+ * A single conversation turn, in the server's wire shape. All fields except
+ * `role` are optional because the server omits them when empty.
+ */
+export interface Message {
+    role: Role;
+    content?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+/** A message the caller sends in a run/resume request. */
+export interface OutgoingMessage {
+    role: OutgoingRole;
+    content: string;
+}
+/** Wire request body for `POST /runs` and `POST /conversations/{id}/runs`. */
+export interface RunRequestBody {
+    systemPrompt: string;
+    messages: OutgoingMessage[];
+    maxIterations: number;
+    toolTimeout: string;
+    requestId: string;
+}
+/** One SSE event from a run stream, discriminated by `type`. */
+export type RunEvent = {
+    type: "run_started";
+    conversationId: string;
+    submissionId: string;
+    resumed: boolean;
+} | {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_call_started";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown> | null;
+} | {
+    type: "tool_result";
+    id: string;
+    name: string;
+    result: string;
+    error?: string;
+} | {
+    type: "run_finished";
+    conversationId: string;
+    finalMessage: Message;
+} | {
+    type: "error";
+    error: string;
+};
+/** Outcome of a single tool call within a run. */
+export interface ToolResult {
+    id: string;
+    name: string;
+    result: string;
+    error?: string;
+}
+/** Options for `Vino.run` and `Vino.stream`. */
+export interface RunOptions {
+    /** Conversation turns, in order. Must be non-empty. */
+    messages: OutgoingMessage[];
+    /** System prompt prepended to the conversation. */
+    systemPrompt?: string;
+    /** Loop cap; 0/absent means the server default (50). */
+    maxIterations?: number;
+    /** Per-tool timeout as a Go duration string ("30s", "1m"). */
+    toolTimeout?: string;
+    /** Makes a run exactly-once: retries resume the original run. */
+    requestId?: string;
+    /** When set, the turns are appended to this conversation (resume). */
+    conversationId?: string;
+    /** Aborts the underlying request and stream. */
+    signal?: AbortSignal;
+}
+/** The resolved outcome of a completed run. */
+export interface RunResult {
+    conversationId: string;
+    submissionId: string;
+    resumed: boolean;
+    finalMessage: Message;
+    /** All `text_delta` payloads concatenated in stream order. */
+    text: string;
+    toolResults: ToolResult[];
+}
+/** Options for constructing a {@link Vino} client. */
+export interface VinoOptions {
+    /** Server base URL. Defaults to `http://127.0.0.1:8080`. */
+    baseUrl?: string;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Optional API key, sent as `Authorization: Bearer <key>`. */
+    apiKey?: string;
+    /** Default request timeout in milliseconds. */
+    timeout?: number;
+    /**
+     * Custom `fetch` implementation. Advanced: intended for testing and for
+     * runtimes without a global `fetch`. Defaults to the global `fetch`.
+     */
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+}
+/** Pagination/ordering query for listing conversations. */
+export interface ListQuery {
+    limit?: number;
+    cursor?: string;
+    order?: "asc" | "desc";
+}
+/** Reference to a parent conversation (present when forked). */
+export interface ForkRef {
+    conversationId: string;
+    at: string;
+}
+/** Reference to the task that owns a conversation. */
+export interface OwnerRef {
+    conversationId: string;
+    taskId: string;
+}
+/** Truncated preview of a conversation's latest message. */
+export interface LatestMessage {
+    role: string;
+    content: string;
+    truncated: boolean;
+}
+/** One conversation in a list response. */
+export interface ConversationSummary {
+    id: string;
+    parent?: ForkRef;
+    owner?: OwnerRef;
+    latestMessage?: LatestMessage;
+}
+/** One entry in a conversation transcript. */
+export interface Entry {
+    id: string;
+    kind: string;
+    message: Message;
+}
+/** A full conversation with its transcript. */
+export interface Conversation {
+    id: string;
+    parent?: ForkRef;
+    owner?: OwnerRef;
+    entries: Entry[];
+}
+/** Response from listing conversations. */
+export interface ListConversationsResult {
+    conversations: ConversationSummary[];
+    nextCursor: string | null;
+}
+//# 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,7 @@
+/**
+ * Wire-level types for the vino-backend HTTP API. These mirror the JSON
+ * documented in the server's `docs/api.md` and are the single source of
+ * truth for the client's request/response shapes.
+ */
+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;;;;GAIG"}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "vino-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Zero-dependency TypeScript client for the vino-backend HTTP API.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test test/unit/*.test.ts test/integration/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}