@kana-ai/edgar-sdk 0.0.0-stage → 0.1.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.
- package/LICENSE +202 -0
- package/README.md +430 -2
- package/dist/src/build/cli.d.ts +6 -0
- package/dist/src/build/cli.js +110 -0
- package/dist/src/build/json.d.ts +2 -0
- package/dist/src/build/json.js +71 -0
- package/dist/src/build/manifest.d.ts +15 -0
- package/dist/src/build/manifest.js +111 -0
- package/dist/src/define/card-block.d.ts +15 -0
- package/dist/src/define/card-block.js +66 -0
- package/dist/src/define/context.d.ts +60 -0
- package/dist/src/define/context.js +1 -0
- package/dist/src/define/extension.d.ts +58 -0
- package/dist/src/define/extension.js +14 -0
- package/dist/src/define/hook.d.ts +61 -0
- package/dist/src/define/hook.js +72 -0
- package/dist/src/define/service.d.ts +32 -0
- package/dist/src/define/service.js +33 -0
- package/dist/src/define/tool.d.ts +93 -0
- package/dist/src/define/tool.js +24 -0
- package/dist/src/define/tracker.d.ts +59 -0
- package/dist/src/define/tracker.js +27 -0
- package/dist/src/index.d.ts +15 -0
- package/dist/src/index.js +12 -0
- package/dist/src/outcome/end.d.ts +61 -0
- package/dist/src/outcome/end.js +292 -0
- package/dist/src/outcome/failures.d.ts +15 -0
- package/dist/src/outcome/failures.js +57 -0
- package/dist/src/outcome/limits.d.ts +13 -0
- package/dist/src/outcome/limits.js +115 -0
- package/dist/src/outcome/outcome.d.ts +32 -0
- package/dist/src/outcome/outcome.js +59 -0
- package/dist/src/outcome/plain.d.ts +7 -0
- package/dist/src/outcome/plain.js +55 -0
- package/dist/src/outcome/result.d.ts +35 -0
- package/dist/src/outcome/result.js +58 -0
- package/dist/src/provider/child.d.ts +51 -0
- package/dist/src/provider/child.js +152 -0
- package/dist/src/provider/serve.d.ts +42 -0
- package/dist/src/provider/serve.js +175 -0
- package/dist/src/runtime/index.d.ts +4 -0
- package/dist/src/runtime/index.js +3 -0
- package/dist/src/runtime/invoke.d.ts +10 -0
- package/dist/src/runtime/invoke.js +232 -0
- package/dist/src/runtime/network.d.ts +20 -0
- package/dist/src/runtime/network.js +120 -0
- package/dist/src/runtime/ports.d.ts +31 -0
- package/dist/src/runtime/ports.js +1 -0
- package/dist/src/runtime/secrets.d.ts +13 -0
- package/dist/src/runtime/secrets.js +33 -0
- package/dist/src/testing/context.d.ts +12 -0
- package/dist/src/testing/context.js +39 -0
- package/dist/src/testing/index.d.ts +3 -0
- package/dist/src/testing/index.js +3 -0
- package/dist/src/testing/mock.d.ts +16 -0
- package/dist/src/testing/mock.js +39 -0
- package/dist/src/wire/codec.d.ts +46 -0
- package/dist/src/wire/codec.js +134 -0
- package/dist/src/wire/lines.d.ts +10 -0
- package/dist/src/wire/lines.js +41 -0
- package/package.json +48 -3
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { Readable, Writable } from "node:stream";
|
|
2
|
+
import type { ProviderHelloResult, SessionEvent, SessionStartParams } from "@kana-ai/edgar-contracts/provider";
|
|
3
|
+
import { type Outcome } from "#outcome/outcome";
|
|
4
|
+
import { type Peer } from "#wire/codec";
|
|
5
|
+
/** What a session reports to the server: events, tool requests the engine answers, and its end. */
|
|
6
|
+
export interface Hooks {
|
|
7
|
+
event(event: SessionEvent): void;
|
|
8
|
+
toolRequest(tool: string, input: unknown): Promise<Outcome>;
|
|
9
|
+
log(line: string): void;
|
|
10
|
+
closed(): void;
|
|
11
|
+
}
|
|
12
|
+
/** One open provider session; `send` starts a turn that ends with a `result` event. `cancel` ends the session: the server forgets its handle when `cancel` resolves, and a `closed` after that changes nothing. */
|
|
13
|
+
export interface Session {
|
|
14
|
+
send(message: string): void;
|
|
15
|
+
cancel(): Promise<void>;
|
|
16
|
+
}
|
|
17
|
+
/** The port the server drives. `start` resolves the handle the session answers to, which may differ from the one proposed, and calls `hooks` once with it; a vendor failure is a session whose next `send` reports it. A session that calls `closed` before its first `send` is replaced by one whose `send` reports its last `error` or `result` event, because the engine reads no event of a handle before it sends. */
|
|
18
|
+
export interface Agent {
|
|
19
|
+
start(spec: SessionStartParams, proposed: string, hooks: (handle: string) => Hooks): Promise<{
|
|
20
|
+
readonly handle: string;
|
|
21
|
+
readonly session: Session;
|
|
22
|
+
}>;
|
|
23
|
+
}
|
|
24
|
+
/** What `serve` needs; streams are the process's stdin and stdout in a runtime's `main.ts` and `PassThrough` pairs in tests. */
|
|
25
|
+
export interface ServeOptions {
|
|
26
|
+
readonly input: Readable;
|
|
27
|
+
readonly output: Writable;
|
|
28
|
+
readonly log: (line: string) => void;
|
|
29
|
+
readonly agent: Agent;
|
|
30
|
+
readonly provider: ProviderHelloResult["provider"];
|
|
31
|
+
readonly sdkVersion: string;
|
|
32
|
+
readonly idleSeconds: number;
|
|
33
|
+
readonly exit: (code: number) => void;
|
|
34
|
+
}
|
|
35
|
+
/** The part of a system prompt that lists the role's skills, one line for each, and says that `edgar__skill` loads one; empty for a role with no skill. */
|
|
36
|
+
export declare function skillList(skills: SessionStartParams["skills"]): string;
|
|
37
|
+
/** A session that could not start: its next `send` reports `event` and the session closes. */
|
|
38
|
+
export declare function failedSession(hooks: Hooks, event: SessionEvent): Session;
|
|
39
|
+
/** Asks the engine to run `tool` for the session `handle`; an error answer reaches the agent as `refused`, or `runtime_payload_too_large` for an input over 4 MiB. */
|
|
40
|
+
export declare function toolRequest(rpc: Peer, handle: string, tool: string, input: unknown): Promise<Outcome>;
|
|
41
|
+
/** Serves the provider contract until `shutdown`, the end of input, or `idleSeconds` with no turn running, and cancels each open session before it exits; the idle timer alone keeps no process alive, since the open input does. */
|
|
42
|
+
export declare function serve(options: ServeOptions): Promise<void>;
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
2
|
+
import { permanentFailure } from "#outcome/outcome";
|
|
3
|
+
import { CONTRACT, acceptHello, errorCodes, peer, trusted, } from "#wire/codec";
|
|
4
|
+
/** The part of a system prompt that lists the role's skills, one line for each, and says that `edgar__skill` loads one; empty for a role with no skill. */
|
|
5
|
+
export function skillList(skills) {
|
|
6
|
+
if (skills.length === 0)
|
|
7
|
+
return "";
|
|
8
|
+
const lines = skills.map((skill) => `- ${skill.name}: ${skill.description}`);
|
|
9
|
+
return `# Skills\n\nLoad a skill with the tool edgar__skill before you do what it covers. Each one is text you do not have yet.\n\n${lines.join("\n")}`;
|
|
10
|
+
}
|
|
11
|
+
/** A session that could not start: its next `send` reports `event` and the session closes. */
|
|
12
|
+
export function failedSession(hooks, event) {
|
|
13
|
+
let open = true;
|
|
14
|
+
const close = () => {
|
|
15
|
+
if (open)
|
|
16
|
+
hooks.closed();
|
|
17
|
+
open = false;
|
|
18
|
+
};
|
|
19
|
+
return {
|
|
20
|
+
send() {
|
|
21
|
+
if (open)
|
|
22
|
+
hooks.event(event);
|
|
23
|
+
close();
|
|
24
|
+
},
|
|
25
|
+
cancel() {
|
|
26
|
+
close();
|
|
27
|
+
return Promise.resolve();
|
|
28
|
+
},
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
/** Asks the engine to run `tool` for the session `handle`; an error answer reaches the agent as `refused`, or `runtime_payload_too_large` for an input over 4 MiB. */
|
|
32
|
+
export async function toolRequest(rpc, handle, tool, input) {
|
|
33
|
+
const params = { handle, call_id: randomUUID(), tool, input };
|
|
34
|
+
const answer = await rpc.request("tool.request", params);
|
|
35
|
+
if (answer.ok)
|
|
36
|
+
return trusted(answer.result).outcome;
|
|
37
|
+
const kind = answer.code === errorCodes.runtime_payload_too_large ? "runtime_payload_too_large" : "refused";
|
|
38
|
+
return permanentFailure(kind, answer.message, answer.code === undefined ? {} : { cause: String(answer.code) });
|
|
39
|
+
}
|
|
40
|
+
/** Serves the provider contract until `shutdown`, the end of input, or `idleSeconds` with no turn running, and cancels each open session before it exits; the idle timer alone keeps no process alive, since the open input does. */
|
|
41
|
+
export async function serve(options) {
|
|
42
|
+
const rpc = peer(options.output, options.log);
|
|
43
|
+
const sessions = new Map();
|
|
44
|
+
const starting = new Set();
|
|
45
|
+
let ready = false;
|
|
46
|
+
let idle;
|
|
47
|
+
const armIdle = () => {
|
|
48
|
+
clearTimeout(idle);
|
|
49
|
+
if (starting.size > 0 || [...sessions.values()].some((open) => open.turn))
|
|
50
|
+
return;
|
|
51
|
+
idle = setTimeout(() => {
|
|
52
|
+
options.log(`idle for ${options.idleSeconds} s, exiting`);
|
|
53
|
+
const exit = () => options.exit(0);
|
|
54
|
+
cancelAll().then(exit, exit);
|
|
55
|
+
}, options.idleSeconds * 1000).unref();
|
|
56
|
+
};
|
|
57
|
+
const cancelAll = async () => {
|
|
58
|
+
await Promise.all([...sessions.values()].map(async (open) => await open.session.cancel()));
|
|
59
|
+
};
|
|
60
|
+
const hooks = (handle) => ({
|
|
61
|
+
event: (event) => {
|
|
62
|
+
const open = sessions.get(handle);
|
|
63
|
+
if (event.type === "result" && open !== undefined) {
|
|
64
|
+
open.turn = false;
|
|
65
|
+
armIdle();
|
|
66
|
+
}
|
|
67
|
+
if (!rpc.send({ jsonrpc: "2.0", method: "session.event", params: { handle, event } }))
|
|
68
|
+
options.log(`a ${event.type} event of ${handle} is over 4 MiB and was dropped`);
|
|
69
|
+
},
|
|
70
|
+
toolRequest: async (tool, input) => await toolRequest(rpc, handle, tool, input),
|
|
71
|
+
log: options.log,
|
|
72
|
+
closed: () => {
|
|
73
|
+
sessions.delete(handle);
|
|
74
|
+
armIdle();
|
|
75
|
+
},
|
|
76
|
+
});
|
|
77
|
+
const start = async (id, spec) => {
|
|
78
|
+
const proposed = spec.resume !== undefined && !spec.resume.fork ? spec.resume.handle : randomUUID();
|
|
79
|
+
if (sessions.has(proposed) || starting.has(proposed))
|
|
80
|
+
return rpc.fail(id, "invalid_params", `${proposed} is already open`);
|
|
81
|
+
starting.add(proposed);
|
|
82
|
+
clearTimeout(idle);
|
|
83
|
+
const life = { over: false };
|
|
84
|
+
const failed = (handle) => failedSession(hooks(handle), life.last ?? {
|
|
85
|
+
type: "error",
|
|
86
|
+
kind: "runtime_crashed",
|
|
87
|
+
message: "the session closed before its first turn",
|
|
88
|
+
});
|
|
89
|
+
const bind = (handle) => {
|
|
90
|
+
const bound = hooks(handle);
|
|
91
|
+
return {
|
|
92
|
+
...bound,
|
|
93
|
+
event: (event) => {
|
|
94
|
+
if (event.type === "error" || event.type === "result")
|
|
95
|
+
life.last = event;
|
|
96
|
+
bound.event(event);
|
|
97
|
+
},
|
|
98
|
+
closed: () => {
|
|
99
|
+
life.over = true;
|
|
100
|
+
const open = sessions.get(handle);
|
|
101
|
+
if (life.open !== undefined && open !== life.open)
|
|
102
|
+
return;
|
|
103
|
+
if (open === undefined || !open.fresh)
|
|
104
|
+
return bound.closed();
|
|
105
|
+
open.session = failed(handle);
|
|
106
|
+
},
|
|
107
|
+
};
|
|
108
|
+
};
|
|
109
|
+
const started = await options.agent.start(spec, proposed, bind).then((value) => value, (error) => (error instanceof Error ? error : new Error(String(error))));
|
|
110
|
+
starting.delete(proposed);
|
|
111
|
+
if (started instanceof Error) {
|
|
112
|
+
armIdle();
|
|
113
|
+
return rpc.fail(id, "internal_error", `the session did not start: ${started.message}`);
|
|
114
|
+
}
|
|
115
|
+
const session = life.over ? failed(started.handle) : started.session;
|
|
116
|
+
life.open = { session, turn: false, fresh: true };
|
|
117
|
+
sessions.set(started.handle, life.open);
|
|
118
|
+
armIdle();
|
|
119
|
+
return rpc.reply(id, { handle: started.handle });
|
|
120
|
+
};
|
|
121
|
+
const send = (id, params) => {
|
|
122
|
+
const open = sessions.get(params.handle);
|
|
123
|
+
if (open === undefined)
|
|
124
|
+
return rpc.fail(id, "invalid_params", `no session ${params.handle}`);
|
|
125
|
+
if (open.turn)
|
|
126
|
+
return rpc.fail(id, "busy", `${params.handle} has a turn running`);
|
|
127
|
+
open.turn = true;
|
|
128
|
+
open.fresh = false;
|
|
129
|
+
clearTimeout(idle);
|
|
130
|
+
rpc.reply(id, {});
|
|
131
|
+
return open.session.send(params.message);
|
|
132
|
+
};
|
|
133
|
+
const request = async (id, method, params) => {
|
|
134
|
+
if (method !== "hello" && method !== "shutdown" && !ready)
|
|
135
|
+
return rpc.fail(id, "invalid_request", "hello first");
|
|
136
|
+
switch (method) {
|
|
137
|
+
case "hello":
|
|
138
|
+
if (!acceptHello(rpc, id, params))
|
|
139
|
+
return;
|
|
140
|
+
ready = true;
|
|
141
|
+
armIdle();
|
|
142
|
+
return rpc.reply(id, {
|
|
143
|
+
contract: CONTRACT,
|
|
144
|
+
provider: options.provider,
|
|
145
|
+
sdk_version: options.sdkVersion,
|
|
146
|
+
});
|
|
147
|
+
case "session.start":
|
|
148
|
+
return await start(id, trusted(params));
|
|
149
|
+
case "session.send":
|
|
150
|
+
return send(id, trusted(params));
|
|
151
|
+
case "session.cancel": {
|
|
152
|
+
const handle = String(params["handle"]);
|
|
153
|
+
const open = sessions.get(handle);
|
|
154
|
+
if (open === undefined)
|
|
155
|
+
return rpc.reply(id, { cancelled: false });
|
|
156
|
+
await open.session.cancel();
|
|
157
|
+
if (sessions.get(handle) === open)
|
|
158
|
+
sessions.delete(handle);
|
|
159
|
+
armIdle();
|
|
160
|
+
return rpc.reply(id, { cancelled: true });
|
|
161
|
+
}
|
|
162
|
+
case "shutdown":
|
|
163
|
+
clearTimeout(idle);
|
|
164
|
+
await cancelAll();
|
|
165
|
+
rpc.reply(id, null);
|
|
166
|
+
return options.exit(0);
|
|
167
|
+
default:
|
|
168
|
+
return rpc.fail(id, "method_not_found", method);
|
|
169
|
+
}
|
|
170
|
+
};
|
|
171
|
+
await rpc.listen(options.input, request);
|
|
172
|
+
await cancelAll();
|
|
173
|
+
clearTimeout(idle);
|
|
174
|
+
options.exit(0);
|
|
175
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { callables, invoke } from "#runtime/invoke";
|
|
2
|
+
export { installNetworkPolicy, guardNodeNetwork } from "#runtime/network";
|
|
3
|
+
export type { Callable, Port, PortMethod, PortTypes } from "#runtime/ports";
|
|
4
|
+
export { SecretHolder, SecretsCleared } from "#runtime/secrets";
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { ToolCallParams } from "@kana-ai/edgar-contracts/rpc";
|
|
2
|
+
import type { Extension } from "#define/extension";
|
|
3
|
+
import { type Outcome } from "#outcome/outcome";
|
|
4
|
+
import type { Callable, Port } from "#runtime/ports";
|
|
5
|
+
/** Every callable of an extension by the name `tool.call` uses. */
|
|
6
|
+
export declare function callables(extension: Extension): ReadonlyMap<string, Callable>;
|
|
7
|
+
/** Runs one `tool.call`: per-call secrets and network policy, a throw as `tool_error`, an ignored cancel as `cancelled` after `graceMs`, and the newest limit the call reported on its outcome. */
|
|
8
|
+
export declare function invoke(callable: Callable, call: ToolCallParams, port: Port, signal: AbortSignal, graceMs?: number): Promise<Outcome>;
|
|
9
|
+
/** Splits `<run id>:<stage>:<attempt>:<call sequence>`; a malformed id is an engine bug. */
|
|
10
|
+
export declare function parseOperationId(operationId: string): readonly [runId: string, stage: string, attempt: number];
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
import { runEvent } from "#define/hook";
|
|
2
|
+
import { serviceInput } from "#define/service";
|
|
3
|
+
import { trackerMethods } from "#define/tracker";
|
|
4
|
+
import { withReportedLimit } from "#outcome/limits";
|
|
5
|
+
import { done, permanentFailure } from "#outcome/outcome";
|
|
6
|
+
import { err, map, ok } from "#outcome/result";
|
|
7
|
+
import { installNetworkPolicy, networkHosts } from "#runtime/network";
|
|
8
|
+
import { SecretHolder } from "#runtime/secrets";
|
|
9
|
+
/** Every callable of an extension by the name `tool.call` uses. */
|
|
10
|
+
export function callables(extension) {
|
|
11
|
+
const table = new Map();
|
|
12
|
+
for (const [name, tool] of Object.entries(extension.tools ?? {})) {
|
|
13
|
+
table.set(name, { run: async (input, ctx) => await checked(tool, input, ctx) });
|
|
14
|
+
const approval = tool.approval;
|
|
15
|
+
if (typeof approval === "object") {
|
|
16
|
+
table.set(`approval.${name}`, {
|
|
17
|
+
run: async (input, ctx) => done(await approval.auto(input, ctx)),
|
|
18
|
+
});
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
for (const [name, environment] of Object.entries(extension.environments ?? {})) {
|
|
22
|
+
for (const step of ["prepare", "start", "health", "stop"]) {
|
|
23
|
+
const tool = environment[step];
|
|
24
|
+
table.set(`environment.${name}.${step}`, {
|
|
25
|
+
run: async (input, ctx) => await checked(tool, input, ctx),
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
for (const [name, hook] of Object.entries(extension.hooks ?? {})) {
|
|
30
|
+
table.set(`hook.${name}`, hookCallable(hook));
|
|
31
|
+
}
|
|
32
|
+
const service = extension.service;
|
|
33
|
+
if (service !== undefined) {
|
|
34
|
+
table.set("service", {
|
|
35
|
+
run: async (input, ctx) => {
|
|
36
|
+
const given = serviceInput(input);
|
|
37
|
+
if (given === undefined) {
|
|
38
|
+
return permanentFailure("invalid", "the engine handed a value that is not a service input");
|
|
39
|
+
}
|
|
40
|
+
return await service.run(ctx, given);
|
|
41
|
+
},
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
const tracker = extension.tracker;
|
|
45
|
+
if (tracker !== undefined) {
|
|
46
|
+
for (const method of trackerMethods) {
|
|
47
|
+
table.set(`tracker.${method}`, {
|
|
48
|
+
run: async (input, ctx) => await tracker.call(method, input, ctx),
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
return table;
|
|
53
|
+
}
|
|
54
|
+
function issuePath(issue) {
|
|
55
|
+
return (issue.path ?? [])
|
|
56
|
+
.map((part) => String(typeof part === "object" ? part.key : part))
|
|
57
|
+
.join(".");
|
|
58
|
+
}
|
|
59
|
+
/** Runs `execute` on the value the tool's schema parses, so defaults and transforms apply; an input it refuses is `invalid`, each issue in `cause`. A `jsonSchema()` input has no `validate` and goes through as sent. */
|
|
60
|
+
async function checked(tool, input, ctx) {
|
|
61
|
+
const result = await tool.input["~standard"].validate?.(input);
|
|
62
|
+
if (result === undefined)
|
|
63
|
+
return await tool.execute(input, ctx);
|
|
64
|
+
if (result.issues === undefined)
|
|
65
|
+
return await tool.execute(result.value, ctx);
|
|
66
|
+
const cause = result.issues.map((issue) => `${issuePath(issue) || "(input)"}: ${issue.message}`);
|
|
67
|
+
return permanentFailure("invalid", "the input does not match the tool's input schema", {
|
|
68
|
+
cause: cause.join("; "),
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
/** Runs one `tool.call`: per-call secrets and network policy, a throw as `tool_error`, an ignored cancel as `cancelled` after `graceMs`, and the newest limit the call reported on its outcome. */
|
|
72
|
+
export async function invoke(callable, call, port, signal, graceMs = 5000) {
|
|
73
|
+
const secrets = new SecretHolder(call.secrets);
|
|
74
|
+
const state = { ended: false };
|
|
75
|
+
const abandon = abandoned(signal, graceMs);
|
|
76
|
+
installNetworkPolicy(networkHosts(call.capabilities));
|
|
77
|
+
try {
|
|
78
|
+
const ctx = context(call, secrets, port, signal, state);
|
|
79
|
+
const running = callable.run(call.input, ctx).then((outcome) => outcome, (error) => thrown(error, signal));
|
|
80
|
+
return withReportedLimit(await Promise.race([running, abandon.outcome]), ctx);
|
|
81
|
+
}
|
|
82
|
+
finally {
|
|
83
|
+
state.ended = true;
|
|
84
|
+
abandon.stop();
|
|
85
|
+
secrets.clear();
|
|
86
|
+
installNetworkPolicy(new Set());
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
function thrown(error, signal) {
|
|
90
|
+
if (signal.aborted)
|
|
91
|
+
return permanentFailure("cancelled", "the call was cancelled");
|
|
92
|
+
return permanentFailure("tool_error", causeChain(error));
|
|
93
|
+
}
|
|
94
|
+
/** The message of `error` and of each error in its `cause`, outer first, as `a: b`, since `fetch` hides why it failed, such as a refused host, in its cause. At most 5 deep; a message that repeats the one before it is said once. */
|
|
95
|
+
function causeChain(error) {
|
|
96
|
+
const messages = [];
|
|
97
|
+
for (let at = error, depth = 0; at instanceof Error && depth < 5; at = at.cause, depth += 1) {
|
|
98
|
+
if (messages.at(-1) !== at.message)
|
|
99
|
+
messages.push(at.message);
|
|
100
|
+
}
|
|
101
|
+
return messages.length === 0 ? String(error) : messages.join(": ");
|
|
102
|
+
}
|
|
103
|
+
function abandoned(signal, graceMs) {
|
|
104
|
+
let timer;
|
|
105
|
+
let onAbort = () => { };
|
|
106
|
+
const outcome = new Promise((resolve) => {
|
|
107
|
+
onAbort = () => {
|
|
108
|
+
timer = setTimeout(() => resolve(permanentFailure("cancelled", `the tool did not stop within ${graceMs} ms of the cancel`)), graceMs);
|
|
109
|
+
};
|
|
110
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
111
|
+
});
|
|
112
|
+
return {
|
|
113
|
+
outcome,
|
|
114
|
+
stop: () => {
|
|
115
|
+
signal.removeEventListener("abort", onAbort);
|
|
116
|
+
clearTimeout(timer);
|
|
117
|
+
},
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
/** The tool sees `<store key in hex>:<engine operation id>`, unique across stores; each ask back to the engine names the engine's own id. */
|
|
121
|
+
function context(call, secrets, port, signal, state) {
|
|
122
|
+
const operation_id = call.operation_id;
|
|
123
|
+
const ask = async (method, params) => {
|
|
124
|
+
if (state.ended)
|
|
125
|
+
return err({ code: "call_ended", message: `${method} after the call ended` });
|
|
126
|
+
return await port.request(method, params);
|
|
127
|
+
};
|
|
128
|
+
const request = async (asked) => await ask("service.request", { operation_id, request: asked });
|
|
129
|
+
const tracker = {
|
|
130
|
+
list_cards: async (input) => await ask("tracker.list_cards", { operation_id, input }),
|
|
131
|
+
card: async (input) => await ask("tracker.card", { operation_id, input }),
|
|
132
|
+
comments: async (input) => await ask("tracker.comments", { operation_id, input }),
|
|
133
|
+
attachments: async (input) => await ask("tracker.attachments", { operation_id, input }),
|
|
134
|
+
comment: async (input) => await ask("tracker.comment", { operation_id, input }),
|
|
135
|
+
move: async (input) => await ask("tracker.move", { operation_id, input }),
|
|
136
|
+
set_labels: async (input) => await ask("tracker.set_labels", { operation_id, input }),
|
|
137
|
+
create_card: async (input) => await ask("tracker.create_card", { operation_id, input }),
|
|
138
|
+
close: async (input) => await ask("tracker.close", { operation_id, input }),
|
|
139
|
+
whoami: async (input) => await ask("tracker.whoami", { operation_id, input }),
|
|
140
|
+
person: async (input) => await ask("tracker.person", { operation_id, input }),
|
|
141
|
+
};
|
|
142
|
+
const [run_id, stage, attempt] = parseOperationId(operation_id);
|
|
143
|
+
return {
|
|
144
|
+
operation_id: `${call.store_key.toString(16)}:${operation_id}`,
|
|
145
|
+
run_id,
|
|
146
|
+
stage,
|
|
147
|
+
attempt,
|
|
148
|
+
signal,
|
|
149
|
+
config: call.config,
|
|
150
|
+
secrets,
|
|
151
|
+
sandbox: {
|
|
152
|
+
read: async (path, encoding = "utf8") => map(await ask("sandbox.read", { operation_id, path, encoding }), (r) => r.content),
|
|
153
|
+
write: async (path, content, encoding = "utf8") => map(await ask("sandbox.write", { operation_id, path, content, encoding }), (r) => r.bytes),
|
|
154
|
+
exec: async (command, args, cwd) => await ask("sandbox.exec", {
|
|
155
|
+
operation_id,
|
|
156
|
+
command,
|
|
157
|
+
args: [...args],
|
|
158
|
+
...(cwd === undefined ? {} : { cwd }),
|
|
159
|
+
}),
|
|
160
|
+
},
|
|
161
|
+
tracker,
|
|
162
|
+
cards: {
|
|
163
|
+
open: async (card) => {
|
|
164
|
+
const answer = await request({ kind: "cards.open", card });
|
|
165
|
+
if (!answer.ok)
|
|
166
|
+
return answer;
|
|
167
|
+
return "outcome" in answer.value ? ok(answer.value) : shape();
|
|
168
|
+
},
|
|
169
|
+
reply: async (to, text, by, origin) => moved(await request({
|
|
170
|
+
kind: "cards.reply",
|
|
171
|
+
...to,
|
|
172
|
+
text,
|
|
173
|
+
by,
|
|
174
|
+
...(origin === undefined ? {} : { origin }),
|
|
175
|
+
})),
|
|
176
|
+
},
|
|
177
|
+
moves: {
|
|
178
|
+
complete: async (key, outcome, by) => moved(await request({ kind: "moves.complete", key, outcome, by })),
|
|
179
|
+
approve: async (operation, by) => moved(await request({ kind: "moves.approve", operation, by })),
|
|
180
|
+
deny: async (operation, by, reason) => moved(await request({ kind: "moves.deny", operation, by, reason })),
|
|
181
|
+
},
|
|
182
|
+
runs: {
|
|
183
|
+
read: async (run) => await ask("runs.read", { operation_id, run_id: run }),
|
|
184
|
+
cancel: async (origin, by, reason) => moved(await request({ kind: "runs.cancel", origin, by, reason })),
|
|
185
|
+
chat: async (text, by, origin, card) => moved(await request({ kind: "runs.chat", text, by, origin, card })),
|
|
186
|
+
},
|
|
187
|
+
complete: async (key, outcome) => await ask("complete", { operation_id, key, outcome }),
|
|
188
|
+
progress: (snapshot) => {
|
|
189
|
+
if (!state.ended)
|
|
190
|
+
port.progress(snapshot);
|
|
191
|
+
},
|
|
192
|
+
log: (line) => {
|
|
193
|
+
if (!state.ended)
|
|
194
|
+
port.log(line);
|
|
195
|
+
},
|
|
196
|
+
};
|
|
197
|
+
}
|
|
198
|
+
/** Splits `<run id>:<stage>:<attempt>:<call sequence>`; a malformed id is an engine bug. */
|
|
199
|
+
export function parseOperationId(operationId) {
|
|
200
|
+
const [runId, stage, attempt, sequence, ...rest] = operationId.split(":");
|
|
201
|
+
const positive = (part) => part !== undefined && /^[1-9][0-9]*$/.test(part);
|
|
202
|
+
if (!positive(runId) ||
|
|
203
|
+
stage === undefined ||
|
|
204
|
+
stage === "" ||
|
|
205
|
+
!positive(attempt) ||
|
|
206
|
+
!positive(sequence) ||
|
|
207
|
+
rest.length > 0) {
|
|
208
|
+
throw new Error(`malformed operation id ${operationId}`);
|
|
209
|
+
}
|
|
210
|
+
return [runId, stage, Number(attempt)];
|
|
211
|
+
}
|
|
212
|
+
function hookCallable(hook) {
|
|
213
|
+
if (hook.on === "event") {
|
|
214
|
+
return {
|
|
215
|
+
run: async (input, ctx) => {
|
|
216
|
+
const event = runEvent(input);
|
|
217
|
+
if (event === undefined) {
|
|
218
|
+
return permanentFailure("invalid", "the engine handed a value that is not a run event");
|
|
219
|
+
}
|
|
220
|
+
return await hook.deliver(event, ctx);
|
|
221
|
+
},
|
|
222
|
+
};
|
|
223
|
+
}
|
|
224
|
+
const erased = hook;
|
|
225
|
+
return { run: async (input, ctx) => done(await erased.check(input, ctx)) };
|
|
226
|
+
}
|
|
227
|
+
const shape = () => err({ code: "engine_error", message: "the engine answered a shape this request does not have" });
|
|
228
|
+
function moved(answer) {
|
|
229
|
+
if (!answer.ok)
|
|
230
|
+
return answer;
|
|
231
|
+
return "applied" in answer.value ? ok(answer.value) : shape();
|
|
232
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { type Dispatcher } from "undici";
|
|
2
|
+
import { type Result } from "#outcome/result";
|
|
3
|
+
/** A connection to a host outside the call's `network:<host>` capabilities. */
|
|
4
|
+
export declare class NetworkRefused extends Error {
|
|
5
|
+
readonly _tag = "NetworkRefused";
|
|
6
|
+
readonly host: string;
|
|
7
|
+
constructor(host: string);
|
|
8
|
+
}
|
|
9
|
+
/** The hosts of a call's `network:<host>` capabilities. */
|
|
10
|
+
export declare function networkHosts(capabilities: readonly string[]): ReadonlySet<string>;
|
|
11
|
+
/** Whether `host` is in `hosts`, or under one of its `*.<domain>` entries; the domain itself is not under its wildcard. */
|
|
12
|
+
export declare function allowedHost(hosts: ReadonlySet<string>, host: string): boolean;
|
|
13
|
+
/** Wraps `target` so that a request to any host outside `hosts` fails with `NetworkRefused` before it connects; a WebSocket upgrade is a request like any other. */
|
|
14
|
+
export declare function policyDispatcher(hosts: ReadonlySet<string>, target: Dispatcher): Dispatcher;
|
|
15
|
+
/** Installs the policy as undici's global dispatcher, which `fetch` uses, and makes the global `WebSocket` undici's, which uses it too: Node's own `WebSocket` does not read that dispatcher. An empty set refuses every host. */
|
|
16
|
+
export declare function installNetworkPolicy(hosts: ReadonlySet<string>): void;
|
|
17
|
+
/**
|
|
18
|
+
* Holds the process to the installed policy's hosts: `http.request`, `http.get`, `https.request` and `https.get` throw; `Socket.connect`, which `net.connect`, `tls.connect`, `http2.connect` and any undici `Agent` go through, throws `NetworkRefused` for an unlisted host; UDP throws for every host.
|
|
19
|
+
*/
|
|
20
|
+
export declare function guardNodeNetwork(): Result<undefined, Error>;
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import dgram from "node:dgram";
|
|
2
|
+
import http from "node:http";
|
|
3
|
+
import https from "node:https";
|
|
4
|
+
import { syncBuiltinESMExports } from "node:module";
|
|
5
|
+
import net from "node:net";
|
|
6
|
+
import { Agent, WebSocket, setGlobalDispatcher } from "undici";
|
|
7
|
+
import { attempt, err, ok } from "#outcome/result";
|
|
8
|
+
/** A connection to a host outside the call's `network:<host>` capabilities. */
|
|
9
|
+
export class NetworkRefused extends Error {
|
|
10
|
+
_tag = "NetworkRefused";
|
|
11
|
+
host;
|
|
12
|
+
constructor(host) {
|
|
13
|
+
super(`network refused: ${host} is not in this call's network capabilities`);
|
|
14
|
+
this.host = host;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
/** The hosts of a call's `network:<host>` capabilities. */
|
|
18
|
+
export function networkHosts(capabilities) {
|
|
19
|
+
const prefix = "network:";
|
|
20
|
+
return new Set(capabilities.filter((c) => c.startsWith(prefix)).map((c) => c.slice(prefix.length)));
|
|
21
|
+
}
|
|
22
|
+
/** Whether `host` is in `hosts`, or under one of its `*.<domain>` entries; the domain itself is not under its wildcard. */
|
|
23
|
+
export function allowedHost(hosts, host) {
|
|
24
|
+
if (hosts.has(host))
|
|
25
|
+
return true;
|
|
26
|
+
const dot = host.indexOf(".");
|
|
27
|
+
for (let at = dot; at !== -1; at = host.indexOf(".", at + 1)) {
|
|
28
|
+
if (at > 0 && hosts.has(`*${host.slice(at)}`))
|
|
29
|
+
return true;
|
|
30
|
+
}
|
|
31
|
+
return false;
|
|
32
|
+
}
|
|
33
|
+
/** Wraps `target` so that a request to any host outside `hosts` fails with `NetworkRefused` before it connects; a WebSocket upgrade is a request like any other. */
|
|
34
|
+
export function policyDispatcher(hosts, target) {
|
|
35
|
+
return target.compose((dispatch) => (options, handler) => {
|
|
36
|
+
const host = options.origin === undefined ? "" : new URL(options.origin).hostname;
|
|
37
|
+
if (allowedHost(hosts, host))
|
|
38
|
+
return dispatch(options, handler);
|
|
39
|
+
const refused = new NetworkRefused(host);
|
|
40
|
+
if (handler.onError === undefined)
|
|
41
|
+
throw refused;
|
|
42
|
+
handler.onError(refused);
|
|
43
|
+
return true;
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
let agent;
|
|
47
|
+
let allowed = new Set();
|
|
48
|
+
/** Installs the policy as undici's global dispatcher, which `fetch` uses, and makes the global `WebSocket` undici's, which uses it too: Node's own `WebSocket` does not read that dispatcher. An empty set refuses every host. */
|
|
49
|
+
export function installNetworkPolicy(hosts) {
|
|
50
|
+
allowed = hosts;
|
|
51
|
+
agent ??= new Agent();
|
|
52
|
+
setGlobalDispatcher(policyDispatcher(hosts, agent));
|
|
53
|
+
if (globalThis.WebSocket !== WebSocket) {
|
|
54
|
+
Object.defineProperty(globalThis, "WebSocket", {
|
|
55
|
+
value: WebSocket,
|
|
56
|
+
configurable: true,
|
|
57
|
+
writable: true,
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
/** The host that the arguments of `Socket.connect` name, in the form `fetch` checks: lower case, an IPv6 address in brackets, `localhost` when none is given; `undefined` for a pipe or a `lookup` of its own, which no host rule covers. */
|
|
62
|
+
function connectHost(args) {
|
|
63
|
+
const head = args[0];
|
|
64
|
+
const first = Array.isArray(head) ? head[0] : head;
|
|
65
|
+
let host = "localhost";
|
|
66
|
+
if (typeof first === "object" && first !== null) {
|
|
67
|
+
if ("path" in first && first.path !== undefined)
|
|
68
|
+
return undefined;
|
|
69
|
+
if ("lookup" in first && first.lookup !== undefined)
|
|
70
|
+
return undefined;
|
|
71
|
+
if ("host" in first && first.host !== undefined)
|
|
72
|
+
host = first.host;
|
|
73
|
+
}
|
|
74
|
+
else if (typeof first === "string" && !(Number(first) >= 0)) {
|
|
75
|
+
return undefined;
|
|
76
|
+
}
|
|
77
|
+
else if (typeof args[1] === "string") {
|
|
78
|
+
host = args[1];
|
|
79
|
+
}
|
|
80
|
+
if (typeof host !== "string")
|
|
81
|
+
return undefined;
|
|
82
|
+
const lower = host.toLowerCase();
|
|
83
|
+
return net.isIPv6(lower) ? `[${lower}]` : lower;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Holds the process to the installed policy's hosts: `http.request`, `http.get`, `https.request` and `https.get` throw; `Socket.connect`, which `net.connect`, `tls.connect`, `http2.connect` and any undici `Agent` go through, throws `NetworkRefused` for an unlisted host; UDP throws for every host.
|
|
87
|
+
*/
|
|
88
|
+
export function guardNodeNetwork() {
|
|
89
|
+
const stub = () => {
|
|
90
|
+
throw new NetworkRefused("node:http");
|
|
91
|
+
};
|
|
92
|
+
const udp = () => {
|
|
93
|
+
throw new NetworkRefused("node:dgram");
|
|
94
|
+
};
|
|
95
|
+
const connect = net.Socket.prototype.connect;
|
|
96
|
+
function checked(...args) {
|
|
97
|
+
const host = connectHost(args);
|
|
98
|
+
if (host === undefined || !allowedHost(allowed, host))
|
|
99
|
+
throw new NetworkRefused(host ?? "a socket with no host");
|
|
100
|
+
Reflect.apply(connect, this, args);
|
|
101
|
+
return this;
|
|
102
|
+
}
|
|
103
|
+
const installed = attempt(() => {
|
|
104
|
+
http.request = stub;
|
|
105
|
+
http.get = stub;
|
|
106
|
+
https.request = stub;
|
|
107
|
+
https.get = stub;
|
|
108
|
+
net.Socket.prototype.connect = checked;
|
|
109
|
+
dgram.createSocket = udp;
|
|
110
|
+
dgram.Socket.prototype.bind = udp;
|
|
111
|
+
syncBuiltinESMExports();
|
|
112
|
+
}, (caught) => new Error("cannot replace the network functions of node", { cause: caught }));
|
|
113
|
+
if (!installed.ok)
|
|
114
|
+
return installed;
|
|
115
|
+
const replaced = [http.request, http.get, https.request, https.get].every((f) => f === stub) &&
|
|
116
|
+
net.Socket.prototype.connect === checked &&
|
|
117
|
+
dgram.createSocket === udp &&
|
|
118
|
+
dgram.Socket.prototype.bind === udp;
|
|
119
|
+
return replaced ? ok(undefined) : err(new Error("node kept one of its network functions"));
|
|
120
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { CompleteParams, CompleteResult, Created, MoveResult, ServiceRequestParams, Method, RunsReadParams, RunsReadResult, SandboxExecParams, SandboxExecResult, SandboxReadParams, SandboxReadResult, SandboxWriteParams, SandboxWriteResult, TrackerParams } from "@kana-ai/edgar-contracts/rpc";
|
|
2
|
+
import type { Ctx, PortResult } from "#define/context";
|
|
3
|
+
import type { TrackerMethod, TrackerTypes } from "#define/tracker";
|
|
4
|
+
import type { Outcome } from "#outcome/outcome";
|
|
5
|
+
/** Params and result of each request a tool makes to the engine. */
|
|
6
|
+
export type PortTypes = {
|
|
7
|
+
readonly "sandbox.read": readonly [SandboxReadParams, SandboxReadResult];
|
|
8
|
+
readonly "sandbox.write": readonly [SandboxWriteParams, SandboxWriteResult];
|
|
9
|
+
readonly "sandbox.exec": readonly [SandboxExecParams, SandboxExecResult];
|
|
10
|
+
readonly complete: readonly [CompleteParams, CompleteResult];
|
|
11
|
+
readonly "runs.read": readonly [RunsReadParams, RunsReadResult];
|
|
12
|
+
/** `cards.open` answers the tracker's outcome; each move answers a `MoveResult`. */
|
|
13
|
+
readonly "service.request": readonly [ServiceRequestParams, Outcome<Created> | MoveResult];
|
|
14
|
+
} & {
|
|
15
|
+
readonly [M in TrackerMethod as `tracker.${M}`]: readonly [
|
|
16
|
+
TrackerParams,
|
|
17
|
+
Outcome<TrackerTypes[M][1]>
|
|
18
|
+
];
|
|
19
|
+
};
|
|
20
|
+
/** A request method a tool may send. */
|
|
21
|
+
export type PortMethod = keyof PortTypes & Method;
|
|
22
|
+
/** The runtime's side of the engine ports: one request per call, answered by id. */
|
|
23
|
+
export interface Port {
|
|
24
|
+
request<M extends PortMethod>(method: M, params: PortTypes[M][0]): Promise<PortResult<PortTypes[M][1]>>;
|
|
25
|
+
progress(snapshot: Readonly<Record<string, unknown>>): void;
|
|
26
|
+
log(line: string): void;
|
|
27
|
+
}
|
|
28
|
+
/** One function the engine may name in `tool.call`. */
|
|
29
|
+
export interface Callable {
|
|
30
|
+
run(input: unknown, ctx: Ctx<string>): Promise<Outcome>;
|
|
31
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { Secrets } from "#define/context";
|
|
2
|
+
/** Thrown when a secret is read after its call ended. */
|
|
3
|
+
export declare class SecretsCleared extends Error {
|
|
4
|
+
readonly _tag = "SecretsCleared";
|
|
5
|
+
}
|
|
6
|
+
/** Holds a call's secrets as bytes so that `clear` can zero them. */
|
|
7
|
+
export declare class SecretHolder implements Secrets<string> {
|
|
8
|
+
#private;
|
|
9
|
+
constructor(secrets: Readonly<Record<string, string>>);
|
|
10
|
+
bytes(name: string): Uint8Array;
|
|
11
|
+
get(name: string): string;
|
|
12
|
+
clear(): void;
|
|
13
|
+
}
|