@theokit/sdk 4.3.0 → 4.4.1

package/dist/interactive/index.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// src/interactive/types.ts
+var InteractiveUnavailableError = class extends Error {
+  code = "interactive_unavailable";
+  constructor(message) {
+    super(message);
+    this.name = "InteractiveUnavailableError";
+  }
+};
+var NoSuchSessionError = class extends Error {
+  code = "no_such_session";
+  constructor(sessionId) {
+    super(`no such live session "${sessionId}" (it may have exited or been killed)`);
+    this.name = "NoSuchSessionError";
+  }
+};
+var InteractiveBackend = class {
+};
+async function resolveInteractive(provider, ctx) {
+  return provider instanceof InteractiveBackend ? provider : provider(ctx);
+}
+
+exports.InteractiveBackend = InteractiveBackend;
+exports.InteractiveUnavailableError = InteractiveUnavailableError;
+exports.NoSuchSessionError = NoSuchSessionError;
+exports.resolveInteractive = resolveInteractive;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/interactive/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/interactive/types.ts"],"names":[],"mappings":";;;AAkBO,IAAM,2BAAA,GAAN,cAA0C,KAAA,CAAM;AAAA,EAC5C,IAAA,GAAO,yBAAA;AAAA,EAChB,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,6BAAA;AAAA,EACd;AACF;AAIO,IAAM,kBAAA,GAAN,cAAiC,KAAA,CAAM;AAAA,EACnC,IAAA,GAAO,iBAAA;AAAA,EAChB,YAAY,SAAA,EAAmB;AAC7B,IAAA,KAAA,CAAM,CAAA,sBAAA,EAAyB,SAAS,CAAA,qCAAA,CAAuC,CAAA;AAC/E,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACd;AACF;AA2CO,IAAe,qBAAf,MAAkC;AAmBzC;AAcA,eAAsB,kBAAA,CACpB,UACA,GAAA,EAC6B;AAC7B,EAAA,OAAO,QAAA,YAAoB,kBAAA,GAAqB,QAAA,GAAW,QAAA,CAAS,GAAG,CAAA;AACzE","file":"index.cjs","sourcesContent":["/**\n * Interactive-session backend protocol — the streaming twin of `SandboxBackend`\n * (which is one-shot `execute`). A surface-agnostic contract for driving a\n * long-lived interactive process (a REPL, `git rebase -i`, any command that\n * PROMPTS for stdin): start → `session_id`, write to stdin, read incremental\n * output, kill.\n *\n * Injected exactly like {@link FilesystemProvider} (SE31) — the tool depends on\n * the interface, the HOST supplies the implementation, so the SAME tool runs on\n * a local PTY (`@theokit/sdk-pty`), a container/E2B backend (cluster/web), or a\n * desktop backend (Tauri) with NO tool change and NO native dependency in core.\n *\n * @public\n */\n\n/** Thrown when the interactive path is requested but no backend can provide it\n *  (no provider injected, or a local backend whose native module / spawn failed).\n *  The caller falls back to non-interactive exec. */\nexport class InteractiveUnavailableError extends Error {\n  readonly code = \"interactive_unavailable\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"InteractiveUnavailableError\";\n  }\n}\n\n/** Thrown (typed) when a write/kill targets an unknown or already-exited session,\n *  so callers branch on the type instead of string-matching a message. */\nexport class NoSuchSessionError extends Error {\n  readonly code = \"no_such_session\" as const;\n  constructor(sessionId: string) {\n    super(`no such live session \"${sessionId}\" (it may have exited or been killed)`);\n    this.name = \"NoSuchSessionError\";\n  }\n}\n\n/** Result of starting a session: its id + whatever the program printed on startup. */\nexport interface StartInteractiveResult {\n  sessionId: string;\n  output: string;\n}\n\n/** Result of writing to a session: the output produced during the yield window + liveness. */\nexport interface WriteStdinResult {\n  output: string;\n  alive: boolean;\n}\n\n/** Bounds a start call. All optional; a backend clamps/defaults each. */\nexport interface StartInteractiveOptions {\n  /** Working directory for the session. Defaults to the backend's root. */\n  cwd?: string;\n  /** How long to wait, in ms, before returning the startup output (clamped by the backend). */\n  yieldMs?: number;\n  /** Idle time, in ms, after which the backend reaps a forgotten session. */\n  ttlMs?: number;\n  /** Cap on the returned output bytes (tail kept). */\n  maxBytes?: number;\n  /** Terminal geometry, when the backend allocates a real TTY. */\n  cols?: number;\n  rows?: number;\n}\n\n/** Bounds a write call. */\nexport interface WriteStdinOptions {\n  yieldMs?: number;\n  ttlMs?: number;\n  maxBytes?: number;\n}\n\n/**\n * Pluggable interactive-session backend. Implement the three abstract methods.\n * A backend that cannot provide interactive sessions should not be constructed —\n * callers detect absence by catching {@link InteractiveUnavailableError}.\n *\n * @public\n */\nexport abstract class InteractiveBackend {\n  /** Spawn `command` as an interactive session; resolve after the yield window with the\n   *  `session_id` + startup output. Throws {@link InteractiveUnavailableError} when the\n   *  session cannot be allocated. */\n  abstract startInteractive(\n    command: string,\n    opts?: StartInteractiveOptions,\n  ): Promise<StartInteractiveResult>;\n\n  /** Write `chars` to a live session's stdin; resolve after the yield window with the output it\n   *  produced + whether it is still alive. Throws {@link NoSuchSessionError} on an unknown session. */\n  abstract writeStdin(\n    sessionId: string,\n    chars: string,\n    opts?: WriteStdinOptions,\n  ): Promise<WriteStdinResult>;\n\n  /** Kill a session (idempotent) and free its slot. */\n  abstract kill(sessionId: string): void;\n}\n\n/**\n * A backend OR a per-request resolver of one — mirrors {@link FilesystemProvider}. A resolver runs\n * at tool-execution time (request scope), so multi-tenant / multi-role agents get a distinct backend\n * per request without a shared mutable one.\n *\n * @public\n */\nexport type InteractiveProvider<Ctx = unknown> =\n  | InteractiveBackend\n  | ((ctx: Ctx) => InteractiveBackend | Promise<InteractiveBackend>);\n\n/** Resolve an {@link InteractiveProvider} to a concrete backend for `ctx`. */\nexport async function resolveInteractive<Ctx>(\n  provider: InteractiveProvider<Ctx>,\n  ctx: Ctx,\n): Promise<InteractiveBackend> {\n  return provider instanceof InteractiveBackend ? provider : provider(ctx);\n}\n"]}

package/dist/interactive/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@theokit/sdk/interactive` — pluggable interactive-session backend seam.
+ *
+ * The streaming twin of `@theokit/sdk/sandbox` (one-shot `execute`) and sibling
+ * of `@theokit/sdk/filesystem`. Ship an `InteractiveBackend` (e.g. the local
+ * `@theokit/sdk-pty`, a container/E2B backend for the cluster, or a Tauri
+ * backend) to give agent shell tools a surface-agnostic REPL/stdin capability —
+ * with NO native dependency in core.
+ *
+ * @public
+ */
+export { InteractiveBackend, type InteractiveProvider, InteractiveUnavailableError, NoSuchSessionError, resolveInteractive, type StartInteractiveOptions, type StartInteractiveResult, type WriteStdinOptions, type WriteStdinResult, } from "./types.js";

package/dist/interactive/index.js

@@ -0,0 +1,24 @@
+// src/interactive/types.ts
+var InteractiveUnavailableError = class extends Error {
+  code = "interactive_unavailable";
+  constructor(message) {
+    super(message);
+    this.name = "InteractiveUnavailableError";
+  }
+};
+var NoSuchSessionError = class extends Error {
+  code = "no_such_session";
+  constructor(sessionId) {
+    super(`no such live session "${sessionId}" (it may have exited or been killed)`);
+    this.name = "NoSuchSessionError";
+  }
+};
+var InteractiveBackend = class {
+};
+async function resolveInteractive(provider, ctx) {
+  return provider instanceof InteractiveBackend ? provider : provider(ctx);
+}
+
+export { InteractiveBackend, InteractiveUnavailableError, NoSuchSessionError, resolveInteractive };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/interactive/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/interactive/types.ts"],"names":[],"mappings":";AAkBO,IAAM,2BAAA,GAAN,cAA0C,KAAA,CAAM;AAAA,EAC5C,IAAA,GAAO,yBAAA;AAAA,EAChB,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,6BAAA;AAAA,EACd;AACF;AAIO,IAAM,kBAAA,GAAN,cAAiC,KAAA,CAAM;AAAA,EACnC,IAAA,GAAO,iBAAA;AAAA,EAChB,YAAY,SAAA,EAAmB;AAC7B,IAAA,KAAA,CAAM,CAAA,sBAAA,EAAyB,SAAS,CAAA,qCAAA,CAAuC,CAAA;AAC/E,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACd;AACF;AA2CO,IAAe,qBAAf,MAAkC;AAmBzC;AAcA,eAAsB,kBAAA,CACpB,UACA,GAAA,EAC6B;AAC7B,EAAA,OAAO,QAAA,YAAoB,kBAAA,GAAqB,QAAA,GAAW,QAAA,CAAS,GAAG,CAAA;AACzE","file":"index.js","sourcesContent":["/**\n * Interactive-session backend protocol — the streaming twin of `SandboxBackend`\n * (which is one-shot `execute`). A surface-agnostic contract for driving a\n * long-lived interactive process (a REPL, `git rebase -i`, any command that\n * PROMPTS for stdin): start → `session_id`, write to stdin, read incremental\n * output, kill.\n *\n * Injected exactly like {@link FilesystemProvider} (SE31) — the tool depends on\n * the interface, the HOST supplies the implementation, so the SAME tool runs on\n * a local PTY (`@theokit/sdk-pty`), a container/E2B backend (cluster/web), or a\n * desktop backend (Tauri) with NO tool change and NO native dependency in core.\n *\n * @public\n */\n\n/** Thrown when the interactive path is requested but no backend can provide it\n *  (no provider injected, or a local backend whose native module / spawn failed).\n *  The caller falls back to non-interactive exec. */\nexport class InteractiveUnavailableError extends Error {\n  readonly code = \"interactive_unavailable\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"InteractiveUnavailableError\";\n  }\n}\n\n/** Thrown (typed) when a write/kill targets an unknown or already-exited session,\n *  so callers branch on the type instead of string-matching a message. */\nexport class NoSuchSessionError extends Error {\n  readonly code = \"no_such_session\" as const;\n  constructor(sessionId: string) {\n    super(`no such live session \"${sessionId}\" (it may have exited or been killed)`);\n    this.name = \"NoSuchSessionError\";\n  }\n}\n\n/** Result of starting a session: its id + whatever the program printed on startup. */\nexport interface StartInteractiveResult {\n  sessionId: string;\n  output: string;\n}\n\n/** Result of writing to a session: the output produced during the yield window + liveness. */\nexport interface WriteStdinResult {\n  output: string;\n  alive: boolean;\n}\n\n/** Bounds a start call. All optional; a backend clamps/defaults each. */\nexport interface StartInteractiveOptions {\n  /** Working directory for the session. Defaults to the backend's root. */\n  cwd?: string;\n  /** How long to wait, in ms, before returning the startup output (clamped by the backend). */\n  yieldMs?: number;\n  /** Idle time, in ms, after which the backend reaps a forgotten session. */\n  ttlMs?: number;\n  /** Cap on the returned output bytes (tail kept). */\n  maxBytes?: number;\n  /** Terminal geometry, when the backend allocates a real TTY. */\n  cols?: number;\n  rows?: number;\n}\n\n/** Bounds a write call. */\nexport interface WriteStdinOptions {\n  yieldMs?: number;\n  ttlMs?: number;\n  maxBytes?: number;\n}\n\n/**\n * Pluggable interactive-session backend. Implement the three abstract methods.\n * A backend that cannot provide interactive sessions should not be constructed —\n * callers detect absence by catching {@link InteractiveUnavailableError}.\n *\n * @public\n */\nexport abstract class InteractiveBackend {\n  /** Spawn `command` as an interactive session; resolve after the yield window with the\n   *  `session_id` + startup output. Throws {@link InteractiveUnavailableError} when the\n   *  session cannot be allocated. */\n  abstract startInteractive(\n    command: string,\n    opts?: StartInteractiveOptions,\n  ): Promise<StartInteractiveResult>;\n\n  /** Write `chars` to a live session's stdin; resolve after the yield window with the output it\n   *  produced + whether it is still alive. Throws {@link NoSuchSessionError} on an unknown session. */\n  abstract writeStdin(\n    sessionId: string,\n    chars: string,\n    opts?: WriteStdinOptions,\n  ): Promise<WriteStdinResult>;\n\n  /** Kill a session (idempotent) and free its slot. */\n  abstract kill(sessionId: string): void;\n}\n\n/**\n * A backend OR a per-request resolver of one — mirrors {@link FilesystemProvider}. A resolver runs\n * at tool-execution time (request scope), so multi-tenant / multi-role agents get a distinct backend\n * per request without a shared mutable one.\n *\n * @public\n */\nexport type InteractiveProvider<Ctx = unknown> =\n  | InteractiveBackend\n  | ((ctx: Ctx) => InteractiveBackend | Promise<InteractiveBackend>);\n\n/** Resolve an {@link InteractiveProvider} to a concrete backend for `ctx`. */\nexport async function resolveInteractive<Ctx>(\n  provider: InteractiveProvider<Ctx>,\n  ctx: Ctx,\n): Promise<InteractiveBackend> {\n  return provider instanceof InteractiveBackend ? provider : provider(ctx);\n}\n"]}

package/dist/interactive/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Interactive-session backend protocol — the streaming twin of `SandboxBackend`
+ * (which is one-shot `execute`). A surface-agnostic contract for driving a
+ * long-lived interactive process (a REPL, `git rebase -i`, any command that
+ * PROMPTS for stdin): start → `session_id`, write to stdin, read incremental
+ * output, kill.
+ *
+ * Injected exactly like {@link FilesystemProvider} (SE31) — the tool depends on
+ * the interface, the HOST supplies the implementation, so the SAME tool runs on
+ * a local PTY (`@theokit/sdk-pty`), a container/E2B backend (cluster/web), or a
+ * desktop backend (Tauri) with NO tool change and NO native dependency in core.
+ *
+ * @public
+ */
+/** Thrown when the interactive path is requested but no backend can provide it
+ *  (no provider injected, or a local backend whose native module / spawn failed).
+ *  The caller falls back to non-interactive exec. */
+export declare class InteractiveUnavailableError extends Error {
+    readonly code: "interactive_unavailable";
+    constructor(message: string);
+}
+/** Thrown (typed) when a write/kill targets an unknown or already-exited session,
+ *  so callers branch on the type instead of string-matching a message. */
+export declare class NoSuchSessionError extends Error {
+    readonly code: "no_such_session";
+    constructor(sessionId: string);
+}
+/** Result of starting a session: its id + whatever the program printed on startup. */
+export interface StartInteractiveResult {
+    sessionId: string;
+    output: string;
+}
+/** Result of writing to a session: the output produced during the yield window + liveness. */
+export interface WriteStdinResult {
+    output: string;
+    alive: boolean;
+}
+/** Bounds a start call. All optional; a backend clamps/defaults each. */
+export interface StartInteractiveOptions {
+    /** Working directory for the session. Defaults to the backend's root. */
+    cwd?: string;
+    /** How long to wait, in ms, before returning the startup output (clamped by the backend). */
+    yieldMs?: number;
+    /** Idle time, in ms, after which the backend reaps a forgotten session. */
+    ttlMs?: number;
+    /** Cap on the returned output bytes (tail kept). */
+    maxBytes?: number;
+    /** Terminal geometry, when the backend allocates a real TTY. */
+    cols?: number;
+    rows?: number;
+}
+/** Bounds a write call. */
+export interface WriteStdinOptions {
+    yieldMs?: number;
+    ttlMs?: number;
+    maxBytes?: number;
+}
+/**
+ * Pluggable interactive-session backend. Implement the three abstract methods.
+ * A backend that cannot provide interactive sessions should not be constructed —
+ * callers detect absence by catching {@link InteractiveUnavailableError}.
+ *
+ * @public
+ */
+export declare abstract class InteractiveBackend {
+    /** Spawn `command` as an interactive session; resolve after the yield window with the
+     *  `session_id` + startup output. Throws {@link InteractiveUnavailableError} when the
+     *  session cannot be allocated. */
+    abstract startInteractive(command: string, opts?: StartInteractiveOptions): Promise<StartInteractiveResult>;
+    /** Write `chars` to a live session's stdin; resolve after the yield window with the output it
+     *  produced + whether it is still alive. Throws {@link NoSuchSessionError} on an unknown session. */
+    abstract writeStdin(sessionId: string, chars: string, opts?: WriteStdinOptions): Promise<WriteStdinResult>;
+    /** Kill a session (idempotent) and free its slot. */
+    abstract kill(sessionId: string): void;
+}
+/**
+ * A backend OR a per-request resolver of one — mirrors {@link FilesystemProvider}. A resolver runs
+ * at tool-execution time (request scope), so multi-tenant / multi-role agents get a distinct backend
+ * per request without a shared mutable one.
+ *
+ * @public
+ */
+export type InteractiveProvider<Ctx = unknown> = InteractiveBackend | ((ctx: Ctx) => InteractiveBackend | Promise<InteractiveBackend>);
+/** Resolve an {@link InteractiveProvider} to a concrete backend for `ctx`. */
+export declare function resolveInteractive<Ctx>(provider: InteractiveProvider<Ctx>, ctx: Ctx): Promise<InteractiveBackend>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheodev/theokit-sdk#readme",
@@ -278,6 +278,16 @@
         "default": "./dist/filesystem/index.cjs"
       }
     },
+    "./interactive": {
+      "import": {
+        "types": "./dist/interactive/index.d.ts",
+        "default": "./dist/interactive/index.js"
+      },
+      "require": {
+        "types": "./dist/interactive/index.d.cts",
+        "default": "./dist/interactive/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [