@theokit/tauri 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog — @theokit/tauri
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-12
+
+### Added
+- Initial release — desktop transport glue for TheoKit agents (ADR-0055).
+- **Webview** (`@theokit/tauri`): `createTauriChannelSource(core, { runCommand?, approveCommand? })` bridges an injected Tauri `{ invoke, Channel }` into a `ChannelPushSource` (the M42 `ChannelTransport` push contract) — JSONL `Channel` events (possibly multi-line) become `onLine`, the `run_turn` invoke resolves to `onClose` / rejects to `onError` (never swallowed, Rule 8), and `settle` routes a HITL decision to the `approve` command. `createTauriAgentClient(core, options?)` is the no-React convenience over M44 `createAgentClient`.
+- **Node sidecar** (`@theokit/tauri/sidecar`): `runTurnToJsonl(mod, apiKey, message, write, awaitApproval?)` streams one agent turn via `streamAgentTurnInProcess` and writes each `UIMessageChunk` as a JSONL line; a thrown error is emitted as a trailing `{type:'error'}` line.
+- `@tauri-apps/api` is an **optional** peer dependency — its primitives are injected structurally, so framework core `theokit` stays Tauri-agnostic (ADR-0045).

package/README.md

@@ -0,0 +1,56 @@
+# @theokit/tauri
+
+Ship your TheoKit agent as a desktop app. One call wires the Tauri shell to your agent — you write the UI, not the bridge.
+
+A [Tauri](https://tauri.app) app is a Rust shell around a system webview. `@theokit/tauri` connects the two halves to a TheoKit agent:
+
+- **In the webview** — your agent streams into React with the same `useAgent` hook you already use on the web, rendered with [`@theokit/ui`](https://www.npmjs.com/package/@theokit/ui).
+- **In the Node sidecar** — one helper runs a turn and streams it out as newline-delimited JSON for the Rust shell to forward.
+
+Framework core (`theokit`) never learns about Tauri — the Tauri primitives are handed in, so this package is an opt-in add-on, not a dependency of the framework.
+
+## Install
+
+```sh
+npm add @theokit/tauri
+```
+
+`theokit` is a peer dependency; `@tauri-apps/api` is an **optional** peer (only needed in the webview half).
+
+## Webview — drive the UI with `useAgent`
+
+```ts
+import { Channel, invoke } from '@tauri-apps/api/core'
+import { ChannelTransport } from 'theokit/client'
+import { createTauriChannelSource } from '@theokit/tauri'
+
+const transport = new ChannelTransport({
+  source: createTauriChannelSource({ invoke, Channel }),
+})
+
+// then, in a component:
+const agent = useAgent(transport)
+```
+
+No React? `createTauriAgentClient({ invoke, Channel })` returns the same handle over the standalone client.
+
+The Rust side exposes two commands (names configurable via `{ runCommand, approveCommand }`, default `run_turn` / `approve`) that talk to the sidecar.
+
+## Node sidecar — stream one turn as JSONL
+
+```ts
+import { runTurnToJsonl } from '@theokit/tauri/sidecar'
+import * as chatAgent from './agents/chat.js'
+
+await runTurnToJsonl(chatAgent, process.env.OPENROUTER_API_KEY!, message, (line) => process.stdout.write(line))
+```
+
+Each line is one `UIMessageChunk`; a failed turn ends with a `{"type":"error"}` line — errors are surfaced, never swallowed.
+
+## Scaffold it
+
+`npm create theokit@latest my-app -- --surface desktop` generates a complete Tauri app already wired to this package.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { CreateAgentClientOptions, AgentClientHandle, ChannelPushSource } from 'theokit/client/core';
+
+/**
+ * `@theokit/tauri` (ADR-0055) — the desktop transport glue for TheoKit agents.
+ *
+ * The webview consumes the agent via the unified client (`ChannelTransport` M42 + `createAgentClient` M44 /
+ * `useAgent` M41). This module turns the Tauri `Channel`/`invoke` push into a `ChannelPushSource` so the
+ * webview app writes one call instead of hand-rolling the bridge. The UI is `@theokit/ui` (the webview is a
+ * browser); the runtime is `@theokit/sdk` (in the sidecar — see `@theokit/tauri/sidecar`). Core `theokit`
+ * stays Tauri-agnostic — the `@tauri-apps/api` primitives are INJECTED here (ADR-0055 D3), never a hard dep.
+ */
+/** A Tauri `Channel<string>` — structurally matches `@tauri-apps/api/core`'s `Channel` (no hard dep). */
+interface TauriChannel {
+    onmessage: (line: string) => void;
+}
+/** The Tauri `core` primitives injected into the source (structurally matches `@tauri-apps/api/core`). */
+interface TauriCore {
+    invoke: (cmd: string, args?: Record<string, unknown>) => Promise<unknown>;
+    Channel: new () => TauriChannel;
+}
+interface TauriChannelSourceOptions {
+    /** The Rust `#[tauri::command]` that runs one agent turn (default `run_turn`, matching the M45 scaffold). */
+    runCommand?: string;
+    /** The Rust `#[tauri::command]` that settles a HITL approval (default `approve`). */
+    approveCommand?: string;
+}
+/**
+ * Build a {@link ChannelPushSource} bridging a Tauri `run_turn` `Channel` + `approve` `invoke` (ADR-0045 D3).
+ * Pass it to `new ChannelTransport({ source })` (M42) and drive it with `useAgent(transport)` (React webview)
+ * or `createAgentClient(transport)` (see {@link createTauriAgentClient}).
+ */
+declare function createTauriChannelSource(core: TauriCore, options?: TauriChannelSourceOptions): ChannelPushSource;
+/**
+ * Convenience: a standalone (no-React) agent client wired to the Tauri desktop transport. Equivalent to
+ * `createAgentClient(new ChannelTransport({ source: createTauriChannelSource(core, opts) }), { context })`.
+ * A React webview should instead use `useAgent(new ChannelTransport({ source: createTauriChannelSource(core) }))`
+ * from `theokit/client` (so it can render with `@theokit/ui`).
+ */
+declare function createTauriAgentClient<TInput = unknown>(core: TauriCore, options?: TauriChannelSourceOptions & CreateAgentClientOptions): AgentClientHandle<TInput>;
+
+export { type TauriChannel, type TauriChannelSourceOptions, type TauriCore, createTauriAgentClient, createTauriChannelSource };

package/dist/index.js

@@ -0,0 +1,37 @@
+// src/index.ts
+import {
+  ChannelTransport,
+  createAgentClient
+} from "theokit/client/core";
+function createTauriChannelSource(core, options = {}) {
+  const runCommand = options.runCommand ?? "run_turn";
+  const approveCommand = options.approveCommand ?? "approve";
+  return {
+    start(turn, { onLine, onClose, onError }) {
+      const channel = new core.Channel();
+      channel.onmessage = (line) => {
+        for (const part of line.split("\n")) {
+          const trimmed = part.trim();
+          if (trimmed) onLine(trimmed);
+        }
+      };
+      void core.invoke(runCommand, { message: turn.message, context: turn.context, onChunk: channel }).then(onClose, (err) => {
+        onError?.(err instanceof Error ? err : new Error(String(err)));
+      });
+      return () => void 0;
+    },
+    settle: async (approvalId, decision) => {
+      await core.invoke(approveCommand, { approvalId, approved: decision.approved });
+    }
+  };
+}
+function createTauriAgentClient(core, options = {}) {
+  const { runCommand, approveCommand, ...clientOptions } = options;
+  const source = createTauriChannelSource(core, { runCommand, approveCommand });
+  return createAgentClient(new ChannelTransport({ source }), clientOptions);
+}
+export {
+  createTauriAgentClient,
+  createTauriChannelSource
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  ChannelTransport,\n  createAgentClient,\n  type AgentClientHandle,\n  type ApprovalDecision,\n  type ChannelPushSource,\n  type CreateAgentClientOptions,\n} from 'theokit/client/core'\n\n/**\n * `@theokit/tauri` (ADR-0055) — the desktop transport glue for TheoKit agents.\n *\n * The webview consumes the agent via the unified client (`ChannelTransport` M42 + `createAgentClient` M44 /\n * `useAgent` M41). This module turns the Tauri `Channel`/`invoke` push into a `ChannelPushSource` so the\n * webview app writes one call instead of hand-rolling the bridge. The UI is `@theokit/ui` (the webview is a\n * browser); the runtime is `@theokit/sdk` (in the sidecar — see `@theokit/tauri/sidecar`). Core `theokit`\n * stays Tauri-agnostic — the `@tauri-apps/api` primitives are INJECTED here (ADR-0055 D3), never a hard dep.\n */\n\n/** A Tauri `Channel<string>` — structurally matches `@tauri-apps/api/core`'s `Channel` (no hard dep). */\nexport interface TauriChannel {\n  onmessage: (line: string) => void\n}\n\n/** The Tauri `core` primitives injected into the source (structurally matches `@tauri-apps/api/core`). */\nexport interface TauriCore {\n  invoke: (cmd: string, args?: Record<string, unknown>) => Promise<unknown>\n  Channel: new () => TauriChannel\n}\n\nexport interface TauriChannelSourceOptions {\n  /** The Rust `#[tauri::command]` that runs one agent turn (default `run_turn`, matching the M45 scaffold). */\n  runCommand?: string\n  /** The Rust `#[tauri::command]` that settles a HITL approval (default `approve`). */\n  approveCommand?: string\n}\n\n/**\n * Build a {@link ChannelPushSource} bridging a Tauri `run_turn` `Channel` + `approve` `invoke` (ADR-0045 D3).\n * Pass it to `new ChannelTransport({ source })` (M42) and drive it with `useAgent(transport)` (React webview)\n * or `createAgentClient(transport)` (see {@link createTauriAgentClient}).\n */\nexport function createTauriChannelSource(\n  core: TauriCore,\n  options: TauriChannelSourceOptions = {},\n): ChannelPushSource {\n  const runCommand = options.runCommand ?? 'run_turn'\n  const approveCommand = options.approveCommand ?? 'approve'\n\n  return {\n    start(turn, { onLine, onClose, onError }) {\n      const channel = new core.Channel()\n      channel.onmessage = (line: string) => {\n        // A Stdout event may carry multiple newline-delimited JSON lines (ADR-0045 D2).\n        for (const part of line.split('\\n')) {\n          const trimmed = part.trim()\n          if (trimmed) onLine(trimmed)\n        }\n      }\n      // Forward the M43 per-request context alongside the message — the sidecar receives it via the Rust\n      // command args (the ChannelPushSource contract obliges the invoke to carry `turn.context`, not drop it).\n      void core\n        .invoke(runCommand, { message: turn.message, context: turn.context, onChunk: channel })\n        .then(onClose, (err: unknown) => {\n          // A Tauri command rejection is a real error — surface it, never swallow it (Rule 8 / M45 review LOW).\n          onError?.(err instanceof Error ? err : new Error(String(err)))\n        })\n      // The Rust shell kills the prior sidecar on the next run, so no explicit abort is needed.\n      return () => undefined\n    },\n    settle: async (approvalId: string, decision: ApprovalDecision) => {\n      await core.invoke(approveCommand, { approvalId, approved: decision.approved })\n    },\n  }\n}\n\n/**\n * Convenience: a standalone (no-React) agent client wired to the Tauri desktop transport. Equivalent to\n * `createAgentClient(new ChannelTransport({ source: createTauriChannelSource(core, opts) }), { context })`.\n * A React webview should instead use `useAgent(new ChannelTransport({ source: createTauriChannelSource(core) }))`\n * from `theokit/client` (so it can render with `@theokit/ui`).\n */\nexport function createTauriAgentClient<TInput = unknown>(\n  core: TauriCore,\n  options: TauriChannelSourceOptions & CreateAgentClientOptions = {},\n): AgentClientHandle<TInput> {\n  const { runCommand, approveCommand, ...clientOptions } = options\n  const source = createTauriChannelSource(core, { runCommand, approveCommand })\n  return createAgentClient<TInput>(new ChannelTransport({ source }), clientOptions)\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,OAKK;AAmCA,SAAS,yBACd,MACA,UAAqC,CAAC,GACnB;AACnB,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,iBAAiB,QAAQ,kBAAkB;AAEjD,SAAO;AAAA,IACL,MAAM,MAAM,EAAE,QAAQ,SAAS,QAAQ,GAAG;AACxC,YAAM,UAAU,IAAI,KAAK,QAAQ;AACjC,cAAQ,YAAY,CAAC,SAAiB;AAEpC,mBAAW,QAAQ,KAAK,MAAM,IAAI,GAAG;AACnC,gBAAM,UAAU,KAAK,KAAK;AAC1B,cAAI,QAAS,QAAO,OAAO;AAAA,QAC7B;AAAA,MACF;AAGA,WAAK,KACF,OAAO,YAAY,EAAE,SAAS,KAAK,SAAS,SAAS,KAAK,SAAS,SAAS,QAAQ,CAAC,EACrF,KAAK,SAAS,CAAC,QAAiB;AAE/B,kBAAU,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAAA,MAC/D,CAAC;AAEH,aAAO,MAAM;AAAA,IACf;AAAA,IACA,QAAQ,OAAO,YAAoB,aAA+B;AAChE,YAAM,KAAK,OAAO,gBAAgB,EAAE,YAAY,UAAU,SAAS,SAAS,CAAC;AAAA,IAC/E;AAAA,EACF;AACF;AAQO,SAAS,uBACd,MACA,UAAgE,CAAC,GACtC;AAC3B,QAAM,EAAE,YAAY,gBAAgB,GAAG,cAAc,IAAI;AACzD,QAAM,SAAS,yBAAyB,MAAM,EAAE,YAAY,eAAe,CAAC;AAC5E,SAAO,kBAA0B,IAAI,iBAAiB,EAAE,OAAO,CAAC,GAAG,aAAa;AAClF;","names":[]}

package/dist/sidecar.d.ts

@@ -0,0 +1,21 @@
+import { InProcessAwaitApproval } from 'theokit/server';
+
+/** Writes one JSONL line (the sidecar's stdout `write`). */
+type WriteLine = (line: string) => void;
+/**
+ * Resolve one gated-tool approval inline (the Rust shell forwards the webview's decision over stdin).
+ * Aliases the seam's {@link InProcessAwaitApproval} so a sidecar can return the full `boolean | HitlDecision`
+ * the SDK supports — never a narrower shape (the desktop stdin protocol carries `approved` today, but the
+ * type stays forward-compatible with structured decisions).
+ */
+type SidecarAwaitApproval = InProcessAwaitApproval;
+/**
+ * `@theokit/tauri/sidecar` (ADR-0055 D2) — the NODE side of the desktop app. Run ONE agent turn via the
+ * in-process seam (`streamAgentTurnInProcess`, M35/M36) and emit each `UIMessageChunk` as a single JSONL
+ * line to `write`; the Rust shell streams these to the webview over a Tauri `Channel`. A thrown error is
+ * surfaced as a trailing `{type:'error'}` line, never swallowed (Rule 8). HITL: a gated tool pauses; the
+ * caller resolves `awaitApproval` (typically after the Rust shell forwards the webview's decision on stdin).
+ */
+declare function runTurnToJsonl(mod: unknown, apiKey: string, message: string, write: WriteLine, awaitApproval?: SidecarAwaitApproval): Promise<void>;
+
+export { type SidecarAwaitApproval, type WriteLine, runTurnToJsonl };

package/dist/sidecar.js

@@ -0,0 +1,23 @@
+// src/sidecar.ts
+import { randomUUID } from "crypto";
+import { streamAgentTurnInProcess } from "theokit/server";
+async function runTurnToJsonl(mod, apiKey, message, write, awaitApproval) {
+  try {
+    for await (const chunk of streamAgentTurnInProcess(mod, apiKey, {
+      message,
+      sessionId: `desktop-${randomUUID()}`,
+      awaitApproval
+    })) {
+      write(`${JSON.stringify(chunk)}
+`);
+    }
+  } catch (err) {
+    const errorText = err instanceof Error ? err.message : String(err);
+    write(`${JSON.stringify({ type: "error", errorText })}
+`);
+  }
+}
+export {
+  runTurnToJsonl
+};
+//# sourceMappingURL=sidecar.js.map

package/dist/sidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sidecar.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto'\n\nimport { streamAgentTurnInProcess, type InProcessAwaitApproval } from 'theokit/server'\n\n/** Writes one JSONL line (the sidecar's stdout `write`). */\nexport type WriteLine = (line: string) => void\n\n/**\n * Resolve one gated-tool approval inline (the Rust shell forwards the webview's decision over stdin).\n * Aliases the seam's {@link InProcessAwaitApproval} so a sidecar can return the full `boolean | HitlDecision`\n * the SDK supports — never a narrower shape (the desktop stdin protocol carries `approved` today, but the\n * type stays forward-compatible with structured decisions).\n */\nexport type SidecarAwaitApproval = InProcessAwaitApproval\n\n/**\n * `@theokit/tauri/sidecar` (ADR-0055 D2) — the NODE side of the desktop app. Run ONE agent turn via the\n * in-process seam (`streamAgentTurnInProcess`, M35/M36) and emit each `UIMessageChunk` as a single JSONL\n * line to `write`; the Rust shell streams these to the webview over a Tauri `Channel`. A thrown error is\n * surfaced as a trailing `{type:'error'}` line, never swallowed (Rule 8). HITL: a gated tool pauses; the\n * caller resolves `awaitApproval` (typically after the Rust shell forwards the webview's decision on stdin).\n */\nexport async function runTurnToJsonl(\n  mod: unknown,\n  apiKey: string,\n  message: string,\n  write: WriteLine,\n  awaitApproval?: SidecarAwaitApproval,\n): Promise<void> {\n  try {\n    for await (const chunk of streamAgentTurnInProcess(mod, apiKey, {\n      message,\n      sessionId: `desktop-${randomUUID()}`,\n      awaitApproval,\n    })) {\n      write(`${JSON.stringify(chunk)}\\n`)\n    }\n  } catch (err) {\n    const errorText = err instanceof Error ? err.message : String(err)\n    write(`${JSON.stringify({ type: 'error', errorText })}\\n`)\n  }\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AAE3B,SAAS,gCAA6D;AAoBtE,eAAsB,eACpB,KACA,QACA,SACA,OACA,eACe;AACf,MAAI;AACF,qBAAiB,SAAS,yBAAyB,KAAK,QAAQ;AAAA,MAC9D;AAAA,MACA,WAAW,WAAW,WAAW,CAAC;AAAA,MAClC;AAAA,IACF,CAAC,GAAG;AACF,YAAM,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,CAAI;AAAA,IACpC;AAAA,EACF,SAAS,KAAK;AACZ,UAAM,YAAY,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AACjE,UAAM,GAAG,KAAK,UAAU,EAAE,MAAM,SAAS,UAAU,CAAC,CAAC;AAAA,CAAI;AAAA,EAC3D;AACF;","names":[]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@theokit/tauri",
+  "version": "0.1.0",
+  "description": "Tauri desktop glue for TheoKit agents — the Channel/invoke transport source (webview) + the JSONL sidecar (node), over the unified client. UI is @theokit/ui; the runtime is @theokit/sdk.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sidecar": {
+      "types": "./dist/sidecar.d.ts",
+      "import": "./dist/sidecar.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "theokit": ">=0.30.0",
+    "@tauri-apps/api": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tauri-apps/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "theokit": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}