@theokit/sdk 4.4.0 → 4.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@theokit/sdk/interactive` — pluggable interactive-session backend seam.
|
|
3
|
+
*
|
|
4
|
+
* The streaming twin of `@theokit/sdk/sandbox` (one-shot `execute`) and sibling
|
|
5
|
+
* of `@theokit/sdk/filesystem`. Ship an `InteractiveBackend` (e.g. the local
|
|
6
|
+
* `@theokit/sdk-pty`, a container/E2B backend for the cluster, or a Tauri
|
|
7
|
+
* backend) to give agent shell tools a surface-agnostic REPL/stdin capability —
|
|
8
|
+
* with NO native dependency in core.
|
|
9
|
+
*
|
|
10
|
+
* @public
|
|
11
|
+
*/
|
|
12
|
+
export { InteractiveBackend, type InteractiveProvider, InteractiveUnavailableError, NoSuchSessionError, resolveInteractive, type StartInteractiveOptions, type StartInteractiveResult, type WriteStdinOptions, type WriteStdinResult, } from "./types.js";
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Interactive-session backend protocol — the streaming twin of `SandboxBackend`
|
|
3
|
+
* (which is one-shot `execute`). A surface-agnostic contract for driving a
|
|
4
|
+
* long-lived interactive process (a REPL, `git rebase -i`, any command that
|
|
5
|
+
* PROMPTS for stdin): start → `session_id`, write to stdin, read incremental
|
|
6
|
+
* output, kill.
|
|
7
|
+
*
|
|
8
|
+
* Injected exactly like {@link FilesystemProvider} (SE31) — the tool depends on
|
|
9
|
+
* the interface, the HOST supplies the implementation, so the SAME tool runs on
|
|
10
|
+
* a local PTY (`@theokit/sdk-pty`), a container/E2B backend (cluster/web), or a
|
|
11
|
+
* desktop backend (Tauri) with NO tool change and NO native dependency in core.
|
|
12
|
+
*
|
|
13
|
+
* @public
|
|
14
|
+
*/
|
|
15
|
+
/** Thrown when the interactive path is requested but no backend can provide it
|
|
16
|
+
* (no provider injected, or a local backend whose native module / spawn failed).
|
|
17
|
+
* The caller falls back to non-interactive exec. */
|
|
18
|
+
export declare class InteractiveUnavailableError extends Error {
|
|
19
|
+
readonly code: "interactive_unavailable";
|
|
20
|
+
constructor(message: string);
|
|
21
|
+
}
|
|
22
|
+
/** Thrown (typed) when a write/kill targets an unknown or already-exited session,
|
|
23
|
+
* so callers branch on the type instead of string-matching a message. */
|
|
24
|
+
export declare class NoSuchSessionError extends Error {
|
|
25
|
+
readonly code: "no_such_session";
|
|
26
|
+
constructor(sessionId: string);
|
|
27
|
+
}
|
|
28
|
+
/** Result of starting a session: its id + whatever the program printed on startup. */
|
|
29
|
+
export interface StartInteractiveResult {
|
|
30
|
+
sessionId: string;
|
|
31
|
+
output: string;
|
|
32
|
+
}
|
|
33
|
+
/** Result of writing to a session: the output produced during the yield window + liveness. */
|
|
34
|
+
export interface WriteStdinResult {
|
|
35
|
+
output: string;
|
|
36
|
+
alive: boolean;
|
|
37
|
+
}
|
|
38
|
+
/** Bounds a start call. All optional; a backend clamps/defaults each. */
|
|
39
|
+
export interface StartInteractiveOptions {
|
|
40
|
+
/** Working directory for the session. Defaults to the backend's root. */
|
|
41
|
+
cwd?: string;
|
|
42
|
+
/** How long to wait, in ms, before returning the startup output (clamped by the backend). */
|
|
43
|
+
yieldMs?: number;
|
|
44
|
+
/** Idle time, in ms, after which the backend reaps a forgotten session. */
|
|
45
|
+
ttlMs?: number;
|
|
46
|
+
/** Cap on the returned output bytes (tail kept). */
|
|
47
|
+
maxBytes?: number;
|
|
48
|
+
/** Terminal geometry, when the backend allocates a real TTY. */
|
|
49
|
+
cols?: number;
|
|
50
|
+
rows?: number;
|
|
51
|
+
}
|
|
52
|
+
/** Bounds a write call. */
|
|
53
|
+
export interface WriteStdinOptions {
|
|
54
|
+
yieldMs?: number;
|
|
55
|
+
ttlMs?: number;
|
|
56
|
+
maxBytes?: number;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Pluggable interactive-session backend. Implement the three abstract methods.
|
|
60
|
+
* A backend that cannot provide interactive sessions should not be constructed —
|
|
61
|
+
* callers detect absence by catching {@link InteractiveUnavailableError}.
|
|
62
|
+
*
|
|
63
|
+
* @public
|
|
64
|
+
*/
|
|
65
|
+
export declare abstract class InteractiveBackend {
|
|
66
|
+
/** Spawn `command` as an interactive session; resolve after the yield window with the
|
|
67
|
+
* `session_id` + startup output. Throws {@link InteractiveUnavailableError} when the
|
|
68
|
+
* session cannot be allocated. */
|
|
69
|
+
abstract startInteractive(command: string, opts?: StartInteractiveOptions): Promise<StartInteractiveResult>;
|
|
70
|
+
/** Write `chars` to a live session's stdin; resolve after the yield window with the output it
|
|
71
|
+
* produced + whether it is still alive. Throws {@link NoSuchSessionError} on an unknown session. */
|
|
72
|
+
abstract writeStdin(sessionId: string, chars: string, opts?: WriteStdinOptions): Promise<WriteStdinResult>;
|
|
73
|
+
/** Kill a session (idempotent) and free its slot. */
|
|
74
|
+
abstract kill(sessionId: string): void;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* A backend OR a per-request resolver of one — mirrors {@link FilesystemProvider}. A resolver runs
|
|
78
|
+
* at tool-execution time (request scope), so multi-tenant / multi-role agents get a distinct backend
|
|
79
|
+
* per request without a shared mutable one.
|
|
80
|
+
*
|
|
81
|
+
* @public
|
|
82
|
+
*/
|
|
83
|
+
export type InteractiveProvider<Ctx = unknown> = InteractiveBackend | ((ctx: Ctx) => InteractiveBackend | Promise<InteractiveBackend>);
|
|
84
|
+
/** Resolve an {@link InteractiveProvider} to a concrete backend for `ctx`. */
|
|
85
|
+
export declare function resolveInteractive<Ctx>(provider: InteractiveProvider<Ctx>, ctx: Ctx): Promise<InteractiveBackend>;
|
package/package.json
CHANGED