@sandagent/manager 0.1.0-beta.0
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.
- package/README.md +191 -0
- package/dist/__tests__/sand-agent.test.d.ts +2 -0
- package/dist/__tests__/sand-agent.test.d.ts.map +1 -0
- package/dist/__tests__/sand-agent.test.js +284 -0
- package/dist/__tests__/sand-agent.test.js.map +1 -0
- package/dist/__tests__/signal-integration.test.d.ts +2 -0
- package/dist/__tests__/signal-integration.test.d.ts.map +1 -0
- package/dist/__tests__/signal-integration.test.js +136 -0
- package/dist/__tests__/signal-integration.test.js.map +1 -0
- package/dist/__tests__/transcript.test.d.ts +2 -0
- package/dist/__tests__/transcript.test.d.ts.map +1 -0
- package/dist/__tests__/transcript.test.js +144 -0
- package/dist/__tests__/transcript.test.js.map +1 -0
- package/dist/__tests__/types.test.d.ts +2 -0
- package/dist/__tests__/types.test.d.ts.map +1 -0
- package/dist/__tests__/types.test.js +148 -0
- package/dist/__tests__/types.test.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -0
- package/dist/sand-agent.d.ts +50 -0
- package/dist/sand-agent.d.ts.map +1 -0
- package/dist/sand-agent.js +187 -0
- package/dist/sand-agent.js.map +1 -0
- package/dist/transcript.d.ts +112 -0
- package/dist/transcript.d.ts.map +1 -0
- package/dist/transcript.js +176 -0
- package/dist/transcript.js.map +1 -0
- package/dist/types.d.ts +175 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/package.json +51 -0
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import type { TranscriptEntry, TranscriptWriter } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* JSONL Transcript Writer
|
|
4
|
+
*
|
|
5
|
+
* Writes transcript entries as JSONL (JSON Lines) format for debugging and replay.
|
|
6
|
+
* Each line is a valid JSON object representing a transcript entry.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { JsonlTranscriptWriter } from "@sandagent/manager";
|
|
11
|
+
*
|
|
12
|
+
* const writer = new JsonlTranscriptWriter("./transcript.jsonl");
|
|
13
|
+
*
|
|
14
|
+
* const agent = new SandAgent({ ... });
|
|
15
|
+
* const response = await agent.stream({
|
|
16
|
+
* messages,
|
|
17
|
+
* transcriptWriter: writer,
|
|
18
|
+
* });
|
|
19
|
+
*
|
|
20
|
+
* // After streaming completes
|
|
21
|
+
* await writer.close();
|
|
22
|
+
* ```
|
|
23
|
+
*/
|
|
24
|
+
export declare class JsonlTranscriptWriter implements TranscriptWriter {
|
|
25
|
+
private readonly filePath;
|
|
26
|
+
private readonly stream;
|
|
27
|
+
private closed;
|
|
28
|
+
/**
|
|
29
|
+
* Create a new JSONL transcript writer
|
|
30
|
+
* @param filePath - Path to write the JSONL file
|
|
31
|
+
* @param options - Writer options
|
|
32
|
+
*/
|
|
33
|
+
constructor(filePath: string, options?: {
|
|
34
|
+
append?: boolean;
|
|
35
|
+
});
|
|
36
|
+
/**
|
|
37
|
+
* Write a transcript entry as a JSONL line
|
|
38
|
+
*/
|
|
39
|
+
write(entry: TranscriptEntry): void;
|
|
40
|
+
/**
|
|
41
|
+
* Close the writer and flush pending data
|
|
42
|
+
*/
|
|
43
|
+
close(): Promise<void>;
|
|
44
|
+
/**
|
|
45
|
+
* Get the file path of the transcript
|
|
46
|
+
*/
|
|
47
|
+
getFilePath(): string;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* In-memory transcript writer for testing and debugging
|
|
51
|
+
*
|
|
52
|
+
* @example
|
|
53
|
+
* ```ts
|
|
54
|
+
* const writer = new MemoryTranscriptWriter();
|
|
55
|
+
* const response = await agent.stream({ messages, transcriptWriter: writer });
|
|
56
|
+
*
|
|
57
|
+
* // Access entries after streaming
|
|
58
|
+
* console.log(writer.getEntries());
|
|
59
|
+
* ```
|
|
60
|
+
*/
|
|
61
|
+
export declare class MemoryTranscriptWriter implements TranscriptWriter {
|
|
62
|
+
private readonly entries;
|
|
63
|
+
write(entry: TranscriptEntry): void;
|
|
64
|
+
/**
|
|
65
|
+
* Get all recorded entries
|
|
66
|
+
*/
|
|
67
|
+
getEntries(): ReadonlyArray<TranscriptEntry>;
|
|
68
|
+
/**
|
|
69
|
+
* Get entries as JSONL string
|
|
70
|
+
*/
|
|
71
|
+
toJsonl(): string;
|
|
72
|
+
/**
|
|
73
|
+
* Get only chunk entries with decoded text
|
|
74
|
+
*/
|
|
75
|
+
getChunks(): string[];
|
|
76
|
+
/**
|
|
77
|
+
* Get the full streamed output as a single string
|
|
78
|
+
*/
|
|
79
|
+
getFullOutput(): string;
|
|
80
|
+
/**
|
|
81
|
+
* Clear all entries
|
|
82
|
+
*/
|
|
83
|
+
clear(): void;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Console transcript writer for debugging
|
|
87
|
+
* Outputs transcript entries to console in a readable format
|
|
88
|
+
*/
|
|
89
|
+
export declare class ConsoleTranscriptWriter implements TranscriptWriter {
|
|
90
|
+
private readonly prefix;
|
|
91
|
+
constructor(prefix?: string);
|
|
92
|
+
write(entry: TranscriptEntry): void;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Multi-writer that writes to multiple transcript writers
|
|
96
|
+
* Useful for both logging and recording simultaneously
|
|
97
|
+
*
|
|
98
|
+
* @example
|
|
99
|
+
* ```ts
|
|
100
|
+
* const writer = new MultiTranscriptWriter([
|
|
101
|
+
* new JsonlTranscriptWriter("./transcript.jsonl"),
|
|
102
|
+
* new ConsoleTranscriptWriter(),
|
|
103
|
+
* ]);
|
|
104
|
+
* ```
|
|
105
|
+
*/
|
|
106
|
+
export declare class MultiTranscriptWriter implements TranscriptWriter {
|
|
107
|
+
private readonly writers;
|
|
108
|
+
constructor(writers: TranscriptWriter[]);
|
|
109
|
+
write(entry: TranscriptEntry): Promise<void>;
|
|
110
|
+
close(): Promise<void>;
|
|
111
|
+
}
|
|
112
|
+
//# sourceMappingURL=transcript.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAO;IAQhE;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAQnC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAInC;;OAEG;IACH,UAAU,IAAI,aAAa,CAAC,eAAe,CAAC;IAI5C;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAMrB;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAED;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,SAAiB;IAInC,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;CAmBpC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,OAAO,EAAE,gBAAgB,EAAE;IAIjC,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import * as fs from "node:fs";
|
|
2
|
+
/**
|
|
3
|
+
* JSONL Transcript Writer
|
|
4
|
+
*
|
|
5
|
+
* Writes transcript entries as JSONL (JSON Lines) format for debugging and replay.
|
|
6
|
+
* Each line is a valid JSON object representing a transcript entry.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { JsonlTranscriptWriter } from "@sandagent/manager";
|
|
11
|
+
*
|
|
12
|
+
* const writer = new JsonlTranscriptWriter("./transcript.jsonl");
|
|
13
|
+
*
|
|
14
|
+
* const agent = new SandAgent({ ... });
|
|
15
|
+
* const response = await agent.stream({
|
|
16
|
+
* messages,
|
|
17
|
+
* transcriptWriter: writer,
|
|
18
|
+
* });
|
|
19
|
+
*
|
|
20
|
+
* // After streaming completes
|
|
21
|
+
* await writer.close();
|
|
22
|
+
* ```
|
|
23
|
+
*/
|
|
24
|
+
export class JsonlTranscriptWriter {
|
|
25
|
+
filePath;
|
|
26
|
+
stream;
|
|
27
|
+
closed = false;
|
|
28
|
+
/**
|
|
29
|
+
* Create a new JSONL transcript writer
|
|
30
|
+
* @param filePath - Path to write the JSONL file
|
|
31
|
+
* @param options - Writer options
|
|
32
|
+
*/
|
|
33
|
+
constructor(filePath, options = {}) {
|
|
34
|
+
this.filePath = filePath;
|
|
35
|
+
this.stream = fs.createWriteStream(filePath, {
|
|
36
|
+
flags: options.append ? "a" : "w",
|
|
37
|
+
encoding: "utf-8",
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Write a transcript entry as a JSONL line
|
|
42
|
+
*/
|
|
43
|
+
write(entry) {
|
|
44
|
+
if (this.closed) {
|
|
45
|
+
throw new Error("TranscriptWriter is closed");
|
|
46
|
+
}
|
|
47
|
+
const line = JSON.stringify(entry) + "\n";
|
|
48
|
+
this.stream.write(line);
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Close the writer and flush pending data
|
|
52
|
+
*/
|
|
53
|
+
async close() {
|
|
54
|
+
if (this.closed)
|
|
55
|
+
return;
|
|
56
|
+
this.closed = true;
|
|
57
|
+
return new Promise((resolve, reject) => {
|
|
58
|
+
this.stream.end((error) => {
|
|
59
|
+
if (error) {
|
|
60
|
+
reject(error);
|
|
61
|
+
}
|
|
62
|
+
else {
|
|
63
|
+
resolve();
|
|
64
|
+
}
|
|
65
|
+
});
|
|
66
|
+
});
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Get the file path of the transcript
|
|
70
|
+
*/
|
|
71
|
+
getFilePath() {
|
|
72
|
+
return this.filePath;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* In-memory transcript writer for testing and debugging
|
|
77
|
+
*
|
|
78
|
+
* @example
|
|
79
|
+
* ```ts
|
|
80
|
+
* const writer = new MemoryTranscriptWriter();
|
|
81
|
+
* const response = await agent.stream({ messages, transcriptWriter: writer });
|
|
82
|
+
*
|
|
83
|
+
* // Access entries after streaming
|
|
84
|
+
* console.log(writer.getEntries());
|
|
85
|
+
* ```
|
|
86
|
+
*/
|
|
87
|
+
export class MemoryTranscriptWriter {
|
|
88
|
+
entries = [];
|
|
89
|
+
write(entry) {
|
|
90
|
+
this.entries.push(entry);
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Get all recorded entries
|
|
94
|
+
*/
|
|
95
|
+
getEntries() {
|
|
96
|
+
return this.entries;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Get entries as JSONL string
|
|
100
|
+
*/
|
|
101
|
+
toJsonl() {
|
|
102
|
+
return this.entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Get only chunk entries with decoded text
|
|
106
|
+
*/
|
|
107
|
+
getChunks() {
|
|
108
|
+
return this.entries
|
|
109
|
+
.filter((e) => e.type === "chunk" && e.text)
|
|
110
|
+
.map((e) => e.text);
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Get the full streamed output as a single string
|
|
114
|
+
*/
|
|
115
|
+
getFullOutput() {
|
|
116
|
+
return this.getChunks().join("");
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Clear all entries
|
|
120
|
+
*/
|
|
121
|
+
clear() {
|
|
122
|
+
this.entries.length = 0;
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Console transcript writer for debugging
|
|
127
|
+
* Outputs transcript entries to console in a readable format
|
|
128
|
+
*/
|
|
129
|
+
export class ConsoleTranscriptWriter {
|
|
130
|
+
prefix;
|
|
131
|
+
constructor(prefix = "[Transcript]") {
|
|
132
|
+
this.prefix = prefix;
|
|
133
|
+
}
|
|
134
|
+
write(entry) {
|
|
135
|
+
const timestamp = new Date(entry.timestamp).toISOString();
|
|
136
|
+
const type = entry.type.toUpperCase().padEnd(8);
|
|
137
|
+
if (entry.type === "chunk" && entry.text) {
|
|
138
|
+
// For chunks, show the text content
|
|
139
|
+
console.log(`${this.prefix} ${timestamp} ${type} ${entry.text}`);
|
|
140
|
+
}
|
|
141
|
+
else if (entry.type === "error") {
|
|
142
|
+
console.error(`${this.prefix} ${timestamp} ${type} ${entry.text ?? entry.data}`);
|
|
143
|
+
}
|
|
144
|
+
else if (entry.metadata) {
|
|
145
|
+
console.log(`${this.prefix} ${timestamp} ${type} ${JSON.stringify(entry.metadata)}`);
|
|
146
|
+
}
|
|
147
|
+
else {
|
|
148
|
+
console.log(`${this.prefix} ${timestamp} ${type}`);
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* Multi-writer that writes to multiple transcript writers
|
|
154
|
+
* Useful for both logging and recording simultaneously
|
|
155
|
+
*
|
|
156
|
+
* @example
|
|
157
|
+
* ```ts
|
|
158
|
+
* const writer = new MultiTranscriptWriter([
|
|
159
|
+
* new JsonlTranscriptWriter("./transcript.jsonl"),
|
|
160
|
+
* new ConsoleTranscriptWriter(),
|
|
161
|
+
* ]);
|
|
162
|
+
* ```
|
|
163
|
+
*/
|
|
164
|
+
export class MultiTranscriptWriter {
|
|
165
|
+
writers;
|
|
166
|
+
constructor(writers) {
|
|
167
|
+
this.writers = writers;
|
|
168
|
+
}
|
|
169
|
+
async write(entry) {
|
|
170
|
+
await Promise.all(this.writers.map((w) => w.write(entry)));
|
|
171
|
+
}
|
|
172
|
+
async close() {
|
|
173
|
+
await Promise.all(this.writers.map((w) => (w.close ? w.close() : Promise.resolve())));
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
//# sourceMappingURL=transcript.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"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"}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Options for executing a command in the sandbox
|
|
3
|
+
*/
|
|
4
|
+
export interface ExecOptions {
|
|
5
|
+
/** Working directory for the command */
|
|
6
|
+
cwd?: string;
|
|
7
|
+
/** Environment variables */
|
|
8
|
+
env?: Record<string, string>;
|
|
9
|
+
/** Timeout in milliseconds */
|
|
10
|
+
timeout?: number;
|
|
11
|
+
/** AbortSignal for cancelling the operation */
|
|
12
|
+
signal?: AbortSignal;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Represents a handle to an active sandbox instance
|
|
16
|
+
*/
|
|
17
|
+
export interface SandboxHandle {
|
|
18
|
+
/**
|
|
19
|
+
* Execute a command in the sandbox and stream the output
|
|
20
|
+
* @param command - The command and arguments to execute
|
|
21
|
+
* @param opts - Execution options
|
|
22
|
+
* @returns An async iterable of stdout chunks
|
|
23
|
+
*/
|
|
24
|
+
exec(command: string[], opts?: ExecOptions): AsyncIterable<Uint8Array>;
|
|
25
|
+
/**
|
|
26
|
+
* Upload files to the sandbox
|
|
27
|
+
* @param files - Array of files to upload
|
|
28
|
+
* @param targetDir - Target directory in the sandbox
|
|
29
|
+
*/
|
|
30
|
+
upload(files: Array<{
|
|
31
|
+
path: string;
|
|
32
|
+
content: Uint8Array | string;
|
|
33
|
+
}>, targetDir: string): Promise<void>;
|
|
34
|
+
/**
|
|
35
|
+
* Read a file from the sandbox
|
|
36
|
+
* @param filePath - Path to the file in the sandbox
|
|
37
|
+
* @returns The file content as a string
|
|
38
|
+
*/
|
|
39
|
+
readFile(filePath: string): Promise<string>;
|
|
40
|
+
/**
|
|
41
|
+
* Destroy the sandbox and release resources
|
|
42
|
+
*/
|
|
43
|
+
destroy(): Promise<void>;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Adapter interface for sandbox implementations
|
|
47
|
+
*/
|
|
48
|
+
export interface SandboxAdapter {
|
|
49
|
+
/**
|
|
50
|
+
* Attach to or create a sandbox
|
|
51
|
+
* @returns A handle to the sandbox
|
|
52
|
+
*/
|
|
53
|
+
attach(): Promise<SandboxHandle>;
|
|
54
|
+
/**
|
|
55
|
+
* Get the current handle if already attached, or null if not attached yet.
|
|
56
|
+
* @returns A handle to the sandbox if already attached, null otherwise
|
|
57
|
+
*/
|
|
58
|
+
getHandle(): SandboxHandle | null;
|
|
59
|
+
/**
|
|
60
|
+
* Get the environment variables configured for this sandbox.
|
|
61
|
+
* These will be passed to all commands executed in the sandbox.
|
|
62
|
+
*/
|
|
63
|
+
getEnv?(): Record<string, string>;
|
|
64
|
+
/**
|
|
65
|
+
* Get the agent template configured for this sandbox.
|
|
66
|
+
* (e.g., "default", "coder", "analyst", "researcher")
|
|
67
|
+
*/
|
|
68
|
+
getAgentTemplate?(): string;
|
|
69
|
+
/**
|
|
70
|
+
* Get the working directory configured for this sandbox.
|
|
71
|
+
*/
|
|
72
|
+
getWorkdir?(): string;
|
|
73
|
+
/**
|
|
74
|
+
* Get the runner command to execute in the sandbox.
|
|
75
|
+
* Returns the command array (e.g., ["sandagent", "run"] or ["node", "/path/to/bundle.mjs", "run"])
|
|
76
|
+
*/
|
|
77
|
+
getRunnerCommand?(): string[];
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Output format types
|
|
81
|
+
* - "text": Plain text output (final result only)
|
|
82
|
+
* - "json": Single JSON result object
|
|
83
|
+
* - "stream-json": Realtime streaming JSON (NDJSON)
|
|
84
|
+
* - "stream": SSE-based AI SDK UI Data Stream format
|
|
85
|
+
*/
|
|
86
|
+
export type OutputFormat = "text" | "json" | "stream-json" | "stream";
|
|
87
|
+
/**
|
|
88
|
+
* Specification for the agent runner
|
|
89
|
+
*/
|
|
90
|
+
export interface RunnerSpec {
|
|
91
|
+
/** The type of runner to use */
|
|
92
|
+
kind: "claude-agent-sdk";
|
|
93
|
+
/** The model to use */
|
|
94
|
+
model: string;
|
|
95
|
+
/** Optional system prompt override (overrides template's CLAUDE.md) */
|
|
96
|
+
systemPrompt?: string;
|
|
97
|
+
/** Maximum number of conversation turns */
|
|
98
|
+
maxTurns?: number;
|
|
99
|
+
/** Allowed tools (undefined means all tools, or use template's settings) */
|
|
100
|
+
allowedTools?: string[];
|
|
101
|
+
/** Approval file directory for tool approval flow (e.g., "/sandagent/approvals") */
|
|
102
|
+
approvalDir?: string;
|
|
103
|
+
/** Output format for streaming responses */
|
|
104
|
+
outputFormat?: OutputFormat;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* Options for creating a SandAgent instance
|
|
108
|
+
*/
|
|
109
|
+
export interface SandAgentOptions {
|
|
110
|
+
/** Sandbox adapter to use */
|
|
111
|
+
sandbox: SandboxAdapter;
|
|
112
|
+
/** Runner specification */
|
|
113
|
+
runner: RunnerSpec;
|
|
114
|
+
/** Environment variables to pass to the sandbox */
|
|
115
|
+
env?: Record<string, string>;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* A message in the conversation
|
|
119
|
+
*/
|
|
120
|
+
export interface Message {
|
|
121
|
+
/** Role of the message sender */
|
|
122
|
+
role: "user" | "assistant" | "system";
|
|
123
|
+
/** Content of the message */
|
|
124
|
+
content: string;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Input for streaming a task
|
|
128
|
+
*/
|
|
129
|
+
export interface StreamInput {
|
|
130
|
+
/** Messages to send to the agent */
|
|
131
|
+
messages: Message[];
|
|
132
|
+
/** Workspace configuration */
|
|
133
|
+
workspace?: {
|
|
134
|
+
/** Path to the workspace directory */
|
|
135
|
+
path?: string;
|
|
136
|
+
};
|
|
137
|
+
/** Content type for the response (defaults to text/event-stream) */
|
|
138
|
+
contentType?: string;
|
|
139
|
+
/** Transcript writer for recording all streamed data (optional) */
|
|
140
|
+
transcriptWriter?: TranscriptWriter;
|
|
141
|
+
/** Runner session ID to resume a previous conversation (from assistant message metadata) */
|
|
142
|
+
resume?: string;
|
|
143
|
+
/** AbortSignal for cancelling the operation */
|
|
144
|
+
signal?: AbortSignal;
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* A single transcript entry
|
|
148
|
+
*/
|
|
149
|
+
export interface TranscriptEntry {
|
|
150
|
+
/** ISO 8601 timestamp */
|
|
151
|
+
timestamp: string;
|
|
152
|
+
/** Type of entry */
|
|
153
|
+
type: "chunk" | "metadata" | "error" | "start" | "end";
|
|
154
|
+
/** Raw data (base64 encoded for binary) */
|
|
155
|
+
data?: string;
|
|
156
|
+
/** Decoded text (if data is text) */
|
|
157
|
+
text?: string;
|
|
158
|
+
/** Additional metadata */
|
|
159
|
+
metadata?: Record<string, unknown>;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Interface for writing transcript entries
|
|
163
|
+
*/
|
|
164
|
+
export interface TranscriptWriter {
|
|
165
|
+
/**
|
|
166
|
+
* Write a transcript entry
|
|
167
|
+
* @param entry - The entry to write
|
|
168
|
+
*/
|
|
169
|
+
write(entry: TranscriptEntry): void | Promise<void>;
|
|
170
|
+
/**
|
|
171
|
+
* Close the writer and flush any pending data
|
|
172
|
+
*/
|
|
173
|
+
close?(): void | Promise<void>;
|
|
174
|
+
}
|
|
175
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
|
package/package.json
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@sandagent/manager",
|
|
3
|
+
"version": "0.1.0-beta.0",
|
|
4
|
+
"description": "SandAgent Manager - Manages sandbox and runner lifecycle, defines core interfaces",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"module": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"import": "./dist/index.js",
|
|
12
|
+
"types": "./dist/index.d.ts"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"dist"
|
|
17
|
+
],
|
|
18
|
+
"scripts": {
|
|
19
|
+
"build": "tsc",
|
|
20
|
+
"dev": "tsc --watch",
|
|
21
|
+
"clean": "rm -rf dist",
|
|
22
|
+
"typecheck": "tsc --noEmit",
|
|
23
|
+
"lint": "echo 'no lint configured'",
|
|
24
|
+
"test": "vitest run --passWithNoTests"
|
|
25
|
+
},
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "https://github.com/vikadata/sandagent.git",
|
|
29
|
+
"directory": "packages/manager"
|
|
30
|
+
},
|
|
31
|
+
"keywords": [
|
|
32
|
+
"sandbox",
|
|
33
|
+
"agent",
|
|
34
|
+
"sandagent",
|
|
35
|
+
"runner",
|
|
36
|
+
"manager"
|
|
37
|
+
],
|
|
38
|
+
"license": "Apache-2.0",
|
|
39
|
+
"publishConfig": {
|
|
40
|
+
"access": "public",
|
|
41
|
+
"tag": "beta"
|
|
42
|
+
},
|
|
43
|
+
"engines": {
|
|
44
|
+
"node": ">=20.0.0"
|
|
45
|
+
},
|
|
46
|
+
"devDependencies": {
|
|
47
|
+
"@types/node": "^20.10.0",
|
|
48
|
+
"typescript": "^5.3.0",
|
|
49
|
+
"vitest": "^1.6.1"
|
|
50
|
+
}
|
|
51
|
+
}
|