@0gfoundation/0g-agentdna 0.0.0-stage → 0.2.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/GUIDE.md +975 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +84 -0
- package/MIGRATION.zh.md +70 -0
- package/PROVIDERS.md +273 -0
- package/PROVIDERS.zh.md +234 -0
- package/README.md +334 -2
- package/dist/AgentClient.d.ts +312 -0
- package/dist/AgentClient.d.ts.map +1 -0
- package/dist/AgentClient.js +715 -0
- package/dist/AgentClient.js.map +1 -0
- package/dist/AgenticID.d.ts +823 -0
- package/dist/AgenticID.d.ts.map +1 -0
- package/dist/AgenticID.js +1188 -0
- package/dist/AgenticID.js.map +1 -0
- package/dist/AgenticIDClient.d.ts +68 -0
- package/dist/AgenticIDClient.d.ts.map +1 -0
- package/dist/AgenticIDClient.js +198 -0
- package/dist/AgenticIDClient.js.map +1 -0
- package/dist/AttestorClient.d.ts +465 -0
- package/dist/AttestorClient.d.ts.map +1 -0
- package/dist/AttestorClient.js +1030 -0
- package/dist/AttestorClient.js.map +1 -0
- package/dist/Providers.d.ts +72 -0
- package/dist/Providers.d.ts.map +1 -0
- package/dist/Providers.js +182 -0
- package/dist/Providers.js.map +1 -0
- package/dist/ReputationClient.d.ts +213 -0
- package/dist/ReputationClient.d.ts.map +1 -0
- package/dist/ReputationClient.js +708 -0
- package/dist/ReputationClient.js.map +1 -0
- package/dist/SandboxClient.d.ts +107 -0
- package/dist/SandboxClient.d.ts.map +1 -0
- package/dist/SandboxClient.js +200 -0
- package/dist/SandboxClient.js.map +1 -0
- package/dist/ServeProof.d.ts +161 -0
- package/dist/ServeProof.d.ts.map +1 -0
- package/dist/ServeProof.js +230 -0
- package/dist/ServeProof.js.map +1 -0
- package/dist/ServeSession.d.ts +180 -0
- package/dist/ServeSession.d.ts.map +1 -0
- package/dist/ServeSession.js +336 -0
- package/dist/ServeSession.js.map +1 -0
- package/dist/Settings.d.ts +179 -0
- package/dist/Settings.d.ts.map +1 -0
- package/dist/Settings.js +247 -0
- package/dist/Settings.js.map +1 -0
- package/dist/abi.d.ts +2216 -0
- package/dist/abi.d.ts.map +1 -0
- package/dist/abi.js +1248 -0
- package/dist/abi.js.map +1 -0
- package/dist/cli/commands/cells.d.ts +62 -0
- package/dist/cli/commands/cells.d.ts.map +1 -0
- package/dist/cli/commands/cells.js +113 -0
- package/dist/cli/commands/cells.js.map +1 -0
- package/dist/cli/commands/doctor.d.ts +15 -0
- package/dist/cli/commands/doctor.d.ts.map +1 -0
- package/dist/cli/commands/doctor.js +236 -0
- package/dist/cli/commands/doctor.js.map +1 -0
- package/dist/cli/commands/interactive.d.ts +115 -0
- package/dist/cli/commands/interactive.d.ts.map +1 -0
- package/dist/cli/commands/interactive.js +3052 -0
- package/dist/cli/commands/interactive.js.map +1 -0
- package/dist/cli/commands/list.d.ts +31 -0
- package/dist/cli/commands/list.d.ts.map +1 -0
- package/dist/cli/commands/list.js +91 -0
- package/dist/cli/commands/list.js.map +1 -0
- package/dist/cli/commands/providers.d.ts +3 -0
- package/dist/cli/commands/providers.d.ts.map +1 -0
- package/dist/cli/commands/providers.js +21 -0
- package/dist/cli/commands/providers.js.map +1 -0
- package/dist/cli/commands/settings.d.ts +22 -0
- package/dist/cli/commands/settings.d.ts.map +1 -0
- package/dist/cli/commands/settings.js +188 -0
- package/dist/cli/commands/settings.js.map +1 -0
- package/dist/cli/commands/status.d.ts +16 -0
- package/dist/cli/commands/status.d.ts.map +1 -0
- package/dist/cli/commands/status.js +148 -0
- package/dist/cli/commands/status.js.map +1 -0
- package/dist/cli/commands/update.d.ts +21 -0
- package/dist/cli/commands/update.d.ts.map +1 -0
- package/dist/cli/commands/update.js +95 -0
- package/dist/cli/commands/update.js.map +1 -0
- package/dist/cli/config.d.ts +73 -0
- package/dist/cli/config.d.ts.map +1 -0
- package/dist/cli/config.js +239 -0
- package/dist/cli/config.js.map +1 -0
- package/dist/cli/env.d.ts +36 -0
- package/dist/cli/env.d.ts.map +1 -0
- package/dist/cli/env.js +74 -0
- package/dist/cli/env.js.map +1 -0
- package/dist/cli/envelope.d.ts +33 -0
- package/dist/cli/envelope.d.ts.map +1 -0
- package/dist/cli/envelope.js +62 -0
- package/dist/cli/envelope.js.map +1 -0
- package/dist/cli/errors.d.ts +48 -0
- package/dist/cli/errors.d.ts.map +1 -0
- package/dist/cli/errors.js +81 -0
- package/dist/cli/errors.js.map +1 -0
- package/dist/cli/inference.d.ts +21 -0
- package/dist/cli/inference.d.ts.map +1 -0
- package/dist/cli/inference.js +60 -0
- package/dist/cli/inference.js.map +1 -0
- package/dist/cli/logo.d.ts +21 -0
- package/dist/cli/logo.d.ts.map +1 -0
- package/dist/cli/logo.js +131 -0
- package/dist/cli/logo.js.map +1 -0
- package/dist/cli/main.d.ts +14 -0
- package/dist/cli/main.d.ts.map +1 -0
- package/dist/cli/main.js +223 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/cli/proofs.d.ts +67 -0
- package/dist/cli/proofs.d.ts.map +1 -0
- package/dist/cli/proofs.js +133 -0
- package/dist/cli/proofs.js.map +1 -0
- package/dist/cli/ref.d.ts +39 -0
- package/dist/cli/ref.d.ts.map +1 -0
- package/dist/cli/ref.js +48 -0
- package/dist/cli/ref.js.map +1 -0
- package/dist/cli/sdk.d.ts +24 -0
- package/dist/cli/sdk.d.ts.map +1 -0
- package/dist/cli/sdk.js +65 -0
- package/dist/cli/sdk.js.map +1 -0
- package/dist/cli/settings.d.ts +66 -0
- package/dist/cli/settings.d.ts.map +1 -0
- package/dist/cli/settings.js +137 -0
- package/dist/cli/settings.js.map +1 -0
- package/dist/cli/tokenize.d.ts +61 -0
- package/dist/cli/tokenize.d.ts.map +1 -0
- package/dist/cli/tokenize.js +157 -0
- package/dist/cli/tokenize.js.map +1 -0
- package/dist/cli/types.d.ts +25 -0
- package/dist/cli/types.d.ts.map +1 -0
- package/dist/cli/types.js +8 -0
- package/dist/cli/types.js.map +1 -0
- package/dist/constants.d.ts +107 -0
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +74 -0
- package/dist/constants.js.map +1 -0
- package/dist/context.d.ts +108 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +64 -0
- package/dist/context.js.map +1 -0
- package/dist/index.d.ts +45 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +118 -0
- package/dist/index.js.map +1 -0
- package/dist/provider-catalog.json +23 -0
- package/dist/seal.d.ts +47 -0
- package/dist/seal.d.ts.map +1 -0
- package/dist/seal.js +145 -0
- package/dist/seal.js.map +1 -0
- package/dist/secretEnv.d.ts +119 -0
- package/dist/secretEnv.d.ts.map +1 -0
- package/dist/secretEnv.js +199 -0
- package/dist/secretEnv.js.map +1 -0
- package/dist/taskHash.d.ts +39 -0
- package/dist/taskHash.d.ts.map +1 -0
- package/dist/taskHash.js +119 -0
- package/dist/taskHash.js.map +1 -0
- package/dist/types.d.ts +336 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +19 -0
- package/dist/types.js.map +1 -0
- package/package.json +75 -4
- package/scripts/sync-providers.cjs +8 -0
- package/src/AgentClient.ts +897 -0
- package/src/AgenticID.ts +1382 -0
- package/src/AgenticIDClient.ts +238 -0
- package/src/AttestorClient.ts +1306 -0
- package/src/Providers.ts +176 -0
- package/src/ReputationClient.ts +821 -0
- package/src/SandboxClient.ts +227 -0
- package/src/ServeProof.ts +290 -0
- package/src/ServeSession.ts +421 -0
- package/src/Settings.ts +296 -0
- package/src/abi.ts +1282 -0
- package/src/cli/commands/cells.ts +107 -0
- package/src/cli/commands/doctor.ts +235 -0
- package/src/cli/commands/interactive.ts +2738 -0
- package/src/cli/commands/list.ts +95 -0
- package/src/cli/commands/providers.ts +16 -0
- package/src/cli/commands/settings.ts +197 -0
- package/src/cli/commands/status.ts +170 -0
- package/src/cli/commands/update.ts +86 -0
- package/src/cli/config.ts +225 -0
- package/src/cli/env.ts +90 -0
- package/src/cli/envelope.ts +57 -0
- package/src/cli/errors.ts +114 -0
- package/src/cli/inference.ts +57 -0
- package/src/cli/logo.ts +125 -0
- package/src/cli/main.ts +235 -0
- package/src/cli/proofs.ts +160 -0
- package/src/cli/ref.ts +58 -0
- package/src/cli/sdk.ts +65 -0
- package/src/cli/settings.ts +153 -0
- package/src/cli/tokenize.ts +131 -0
- package/src/cli/types.ts +27 -0
- package/src/constants.ts +106 -0
- package/src/context.ts +161 -0
- package/src/index.ts +129 -0
- package/src/provider-catalog.json +23 -0
- package/src/seal.ts +163 -0
- package/src/secretEnv.ts +250 -0
- package/src/taskHash.ts +100 -0
- package/src/types.ts +357 -0
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file AgentClient.ts
|
|
3
|
+
* @description Discovery-driven handle for interacting with a running agent.
|
|
4
|
+
*
|
|
5
|
+
* `authenticate()` / `connect()` return an {@link AgentClient}: a handle bound
|
|
6
|
+
* to an agent's base URL plus the agent's own declaration of what it exposes
|
|
7
|
+
* (the `services` and `routes` arrays from its signed `/hello`). It knows
|
|
8
|
+
* nothing framework-specific — it decides how to attach the credential and
|
|
9
|
+
* which affordances (`chat`/`chatStream`) to offer purely from what the agent
|
|
10
|
+
* declared. Adding a framework, or an endpoint, needs no SDK change.
|
|
11
|
+
*
|
|
12
|
+
* The same handle serves both callers, the difference being only the token:
|
|
13
|
+
* - owner (with a signer) → the owner token is minted on demand → `chat`/
|
|
14
|
+
* `chatStream` available;
|
|
15
|
+
* - third party (no signer) → no token → calls the agent's public `/api/*`
|
|
16
|
+
* services via `fetch`/`fetchWithProof` and captures the proof.
|
|
17
|
+
*/
|
|
18
|
+
import { type TaskExchange } from './ServeSession';
|
|
19
|
+
import type { ServeProof } from './types';
|
|
20
|
+
/**
|
|
21
|
+
* One agent-registered service, as listed in `/hello`'s `services` array.
|
|
22
|
+
* These are exact `/api/*` paths the agent's own code serves; they are not
|
|
23
|
+
* gated by the owner token.
|
|
24
|
+
*/
|
|
25
|
+
export interface AgentServiceEntry {
|
|
26
|
+
path: string;
|
|
27
|
+
method: string;
|
|
28
|
+
description?: string;
|
|
29
|
+
input_example?: string;
|
|
30
|
+
/**
|
|
31
|
+
* Protocol the consumer should speak. `"mcp"` = an MCP server endpoint:
|
|
32
|
+
* the backend implements the MCP streamable-HTTP protocol (JSON-RPC over
|
|
33
|
+
* POST), so an MCP-capable client can mount `<base><path>` as an MCP
|
|
34
|
+
* server and this agent's tools become the client's tools. Responses
|
|
35
|
+
* carry `X-Agent-Proof` like every agent service (when the runtime has a
|
|
36
|
+
* serve-proof validator configured) — that proof is what makes it a
|
|
37
|
+
* *trust-attributable* MCP server (see {@link mcpServices}).
|
|
38
|
+
*/
|
|
39
|
+
transport?: 'mcp';
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* The agent's MCP-mountable service endpoints — the `/hello` entries marked
|
|
43
|
+
* `transport: "mcp"`. This is the consumption half of trusted-MCP serving:
|
|
44
|
+
*
|
|
45
|
+
* ```ts
|
|
46
|
+
* const { hello, verification } = await ag.agent.sayHi(agentUrl);
|
|
47
|
+
* // hello.services carries transport: "mcp" on MCP endpoints — sayHi
|
|
48
|
+
* // verified the /hello proof's signer against the on-chain agentSeal.
|
|
49
|
+
* const client = await ag.agent.client(agentUrl); // public handle
|
|
50
|
+
* const mcp = mcpServices(client); // → [{ path: "/api/mcp", … }]
|
|
51
|
+
* // Mount `${client.base}${mcp[0].path}` as a streamable-HTTP MCP server in
|
|
52
|
+
* // any MCP client.
|
|
53
|
+
* ```
|
|
54
|
+
*
|
|
55
|
+
* Per-exchange verification — binding the proof to THIS body, not just the
|
|
56
|
+
* signer. `verifyProof` alone is signer attribution; with the exchange it
|
|
57
|
+
* also checks that the proof's taskHash equals
|
|
58
|
+
* keccak(method ‖ uri ‖ keccak(reqBody) ‖ keccak(respBody) ‖ status)
|
|
59
|
+
* recomputed from YOUR bytes (`taskMatches` in the verdict, required for
|
|
60
|
+
* `ok`). The pieces:
|
|
61
|
+
*
|
|
62
|
+
* ```ts
|
|
63
|
+
* const { response, proof, task } = await client.fetchWithProof(mcp[0].path, {
|
|
64
|
+
* method: 'POST', headers: { 'content-type': 'application/json' },
|
|
65
|
+
* body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
|
|
66
|
+
* });
|
|
67
|
+
* await response.text(); // your own read still works
|
|
68
|
+
* const v = await session.verifyProof(proof!, { task: task! });
|
|
69
|
+
* // v.ok && v.taskMatches → THIS response came from the attested runtime.
|
|
70
|
+
* // (task === null → ok: false, fail closed: the exchange wasn't recorded.)
|
|
71
|
+
* ```
|
|
72
|
+
* `task` is recorded from the actual bytes (response read via clone()), so a
|
|
73
|
+
* genuine proof replayed next to a swapped body fails (`taskMatches: false`).
|
|
74
|
+
* For hand-rolled fetches, pass the `TaskExchange` you captured (method, url,
|
|
75
|
+
* requestBytes, responseBytes, status) — `verifyProof` derives and tries
|
|
76
|
+
* every URI candidate from it. (`taskRevealOf()` returns an array; its
|
|
77
|
+
* element 0 can name the wrong URI form for a trailing-`?` URL.)
|
|
78
|
+
*
|
|
79
|
+
* Note the proxy pins one HTTP method per path, so an MCP route is POST-only:
|
|
80
|
+
* a stateless MCP server (each JSON-RPC request answered in one response,
|
|
81
|
+
* no server-initiated pushes) is the supported shape — and because the proxy
|
|
82
|
+
* buffers the whole response before signing, progress notifications and
|
|
83
|
+
* server→client requests (sampling, elicitation) inside a POST stream are
|
|
84
|
+
* not supported; keep tool calls short and return one JSON response.
|
|
85
|
+
*
|
|
86
|
+
* Two environment notes for generic MCP clients: (1) the proof envelope's
|
|
87
|
+
* `submitter` comes from the `X-Client-Address` request header — generic
|
|
88
|
+
* MCP clients don't send one, so proofs come back with submitter 0x0 and
|
|
89
|
+
* cannot be redeemed in protocols that require a real submitter; set the
|
|
90
|
+
* header through your MCP client's custom-headers option if you need it.
|
|
91
|
+
* (2) browser MCP clients only get to read `X-Agent-Proof` (the only
|
|
92
|
+
* CORS-exposed header) and an OPTIONS preflight to the service path 405s —
|
|
93
|
+
* use a non-browser client for verified MCP.
|
|
94
|
+
*/
|
|
95
|
+
export declare function mcpServices(client: Pick<AgentClient, 'services'>): AgentServiceEntry[];
|
|
96
|
+
/**
|
|
97
|
+
* One framework-declared route, as listed in `/hello`'s `routes` array. A
|
|
98
|
+
* route claims a path prefix (e.g. `/` for a dashboard, `/v1/` for a chat
|
|
99
|
+
* API) and declares how a client should present the owner token (`auth`) and
|
|
100
|
+
* whether responses on it carry a serve-proof (`signed`).
|
|
101
|
+
*/
|
|
102
|
+
export interface AgentRoute {
|
|
103
|
+
prefix: string;
|
|
104
|
+
/** discovery hint, e.g. "dashboard" | "chat" */
|
|
105
|
+
kind?: string;
|
|
106
|
+
/** how to present the token: "bearer" | "none" */
|
|
107
|
+
auth?: string;
|
|
108
|
+
signed: boolean;
|
|
109
|
+
description?: string;
|
|
110
|
+
}
|
|
111
|
+
export interface ChatMessage {
|
|
112
|
+
role: string;
|
|
113
|
+
content: string;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Snapshot of one long-running task (a "response" in OpenAI Responses API
|
|
117
|
+
* terms) on the agent. Returned by {@link AgentClient.task} /
|
|
118
|
+
* {@link AgentClient.cancelTask}.
|
|
119
|
+
*/
|
|
120
|
+
export interface AgentTask {
|
|
121
|
+
id: string;
|
|
122
|
+
status: 'queued' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
|
|
123
|
+
/** Assistant text produced so far (full text once completed). */
|
|
124
|
+
output_text: string;
|
|
125
|
+
error?: {
|
|
126
|
+
message: string;
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
export interface ChatCompletion {
|
|
130
|
+
choices: Array<{
|
|
131
|
+
message: {
|
|
132
|
+
role: string;
|
|
133
|
+
content: string;
|
|
134
|
+
};
|
|
135
|
+
}>;
|
|
136
|
+
[k: string]: unknown;
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* A live handle to an agent. Always carries `base` and the declared
|
|
140
|
+
* `services`/`routes`. Owner affordances (`chat`/`chatStream`) are
|
|
141
|
+
* present only when this handle can authenticate — i.e. it was built with a
|
|
142
|
+
* signer (the `ag` that made it holds an owner key) AND the agent declares the
|
|
143
|
+
* matching route. Their tokens are managed internally: minted on first use and
|
|
144
|
+
* re-minted automatically if the agent rotates them (e.g. after a `reset`), so
|
|
145
|
+
* you never pass or refresh a token by hand. `fetch`/`fetchWithProof` work for
|
|
146
|
+
* any path and never need a token for the public `/api/*` surface. `token`
|
|
147
|
+
* reflects the currently-cached credential, if any.
|
|
148
|
+
*/
|
|
149
|
+
export interface AgentClient {
|
|
150
|
+
readonly token?: string;
|
|
151
|
+
readonly base: string;
|
|
152
|
+
readonly services: AgentServiceEntry[];
|
|
153
|
+
readonly routes: AgentRoute[];
|
|
154
|
+
/**
|
|
155
|
+
* Fetch a path on the agent. `path` is relative to the agent base (leading
|
|
156
|
+
* slash optional). If the longest-prefix route match declares
|
|
157
|
+
* `auth: "bearer"` and this handle holds a token, an
|
|
158
|
+
* `Authorization: Bearer <token>` header is added (unless the caller already
|
|
159
|
+
* set one).
|
|
160
|
+
*/
|
|
161
|
+
fetch(path: string, init?: RequestInit): Promise<Response>;
|
|
162
|
+
/**
|
|
163
|
+
* Like {@link fetch}, but also reads the response's `X-Agent-Proof` (a
|
|
164
|
+
* TEE-signed serve-proof) when present. This is the primary way a third
|
|
165
|
+
* party calls one of the agent's `/api/*` services and captures the proof to
|
|
166
|
+
* verify or submit as on-chain feedback. `proof` is null when the response
|
|
167
|
+
* carries none (e.g. the unsigned owner↔agent chat route).
|
|
168
|
+
*/
|
|
169
|
+
fetchWithProof(path: string, init?: RequestInit): Promise<{
|
|
170
|
+
response: Response;
|
|
171
|
+
proof: ServeProof | null;
|
|
172
|
+
/** The exchange that was actually sent/received, for per-exchange
|
|
173
|
+
* verification: `session.verifyProof(proof, { task })` then binds the
|
|
174
|
+
* proof to THIS response's bytes (taskMatches), not just to the signer.
|
|
175
|
+
* The response body is read via clone(), so `response.json()` etc. still
|
|
176
|
+
* work. null when the request could not be recorded. */
|
|
177
|
+
task: TaskExchange | null;
|
|
178
|
+
}>;
|
|
179
|
+
/**
|
|
180
|
+
* Present only if the agent declares a `kind: "chat"` route and this handle
|
|
181
|
+
* holds the owner token. POSTs an OpenAI-shaped chat request to
|
|
182
|
+
* `<prefix>chat/completions` and returns the full reply. Streams under the
|
|
183
|
+
* hood so a long reasoning turn doesn't hit an idle-timeout hop in front of
|
|
184
|
+
* the agent; the completion is reassembled before returning, so the shape is
|
|
185
|
+
* a plain {@link ChatCompletion}.
|
|
186
|
+
*/
|
|
187
|
+
chat?(messages: ChatMessage[], opts?: {
|
|
188
|
+
model?: string;
|
|
189
|
+
signal?: AbortSignal;
|
|
190
|
+
}): Promise<ChatCompletion>;
|
|
191
|
+
/**
|
|
192
|
+
* Like {@link chat}, but yields each content delta as it is generated — for
|
|
193
|
+
* a live-typing UI. Present under the same conditions as `chat`.
|
|
194
|
+
*
|
|
195
|
+
* for await (const delta of client.chatStream(msgs)) process.stdout.write(delta);
|
|
196
|
+
*
|
|
197
|
+
* Pass `signal` to interrupt a turn in flight: aborting tears down the HTTP
|
|
198
|
+
* connection, which is the OpenAI-conventional cancel signal — the runtime
|
|
199
|
+
* side stops the turn where the framework supports cancellation (dsh does).
|
|
200
|
+
* The generator then throws the abort error (`err.name === "AbortError"`).
|
|
201
|
+
*/
|
|
202
|
+
chatStream?(messages: ChatMessage[], opts?: {
|
|
203
|
+
model?: string;
|
|
204
|
+
signal?: AbortSignal;
|
|
205
|
+
/** Tool-activity progress, when the agent's bridge streams it (SSE
|
|
206
|
+
* ": activity tool/call <name>" comments — dsh does). Labels like
|
|
207
|
+
* "tool/call bash", "tool/result", "turn/end". Advisory: absence just
|
|
208
|
+
* means the bridge doesn't narrate. */
|
|
209
|
+
onActivity?: (label: string) => void;
|
|
210
|
+
/** Per-message reasoning-effort override for thinking models. Only the
|
|
211
|
+
* prime bridge honors it today (other frameworks' HTTP surfaces don't
|
|
212
|
+
* take a per-request level — their default is set at deploy/reset via
|
|
213
|
+
* `thinking`); unsupported bridges ignore it. */
|
|
214
|
+
thinking?: 'low' | 'high' | 'max';
|
|
215
|
+
/** Fires once with the server-side task id, as soon as the agent assigns
|
|
216
|
+
* one. Only on the responses transport (see {@link AgentClient.task}):
|
|
217
|
+
* save it and you can re-attach to this turn after a process restart via
|
|
218
|
+
* {@link AgentClient.followTask}, or stop it via
|
|
219
|
+
* {@link AgentClient.cancelTask}. */
|
|
220
|
+
onTask?: (id: string) => void;
|
|
221
|
+
}): AsyncGenerator<string>;
|
|
222
|
+
/**
|
|
223
|
+
* Poll one task's snapshot (status + text so far). Present only when the
|
|
224
|
+
* agent declares a `kind: "responses"` route — the long-task surface where
|
|
225
|
+
* a turn is owned by a server-side id rather than an HTTP connection, so it
|
|
226
|
+
* survives dropped connections and proxy request-duration caps. On such
|
|
227
|
+
* agents `chat`/`chatStream` already ride this transport transparently
|
|
228
|
+
* (auto-resuming when the connection drops); these methods are for
|
|
229
|
+
* re-attaching later or from elsewhere.
|
|
230
|
+
*/
|
|
231
|
+
task?(id: string): Promise<AgentTask>;
|
|
232
|
+
/**
|
|
233
|
+
* Re-attach to a running (or finished) task and stream its remaining
|
|
234
|
+
* output. `startingAfter` is the last event sequence number already seen
|
|
235
|
+
* (0 = from the beginning — the agent replays buffered events first, then
|
|
236
|
+
* follows live). Ends when the task completes; throws if it failed.
|
|
237
|
+
* Present under the same conditions as {@link task}.
|
|
238
|
+
*/
|
|
239
|
+
followTask?(id: string, opts?: {
|
|
240
|
+
startingAfter?: number;
|
|
241
|
+
signal?: AbortSignal;
|
|
242
|
+
onActivity?: (label: string) => void;
|
|
243
|
+
}): AsyncGenerator<string>;
|
|
244
|
+
/**
|
|
245
|
+
* Stop one task by id — the responses-transport form of {@link interrupt}.
|
|
246
|
+
* Already-executed actions are not rolled back. Present under the same
|
|
247
|
+
* conditions as {@link task}.
|
|
248
|
+
*/
|
|
249
|
+
cancelTask?(id: string): Promise<AgentTask>;
|
|
250
|
+
/**
|
|
251
|
+
* Stop the agent's CURRENT task — whoever started it. Esc semantics: the
|
|
252
|
+
* turn stops issuing new tool calls / output; already-executed actions are
|
|
253
|
+
* NOT rolled back. Also the cure for orphaned turns (a turn whose
|
|
254
|
+
* originating connection died keeps running server-side; only this — or a
|
|
255
|
+
* full /reset — stops it). Present under the same conditions as `chat`.
|
|
256
|
+
* `aborted: false` + note means the agent image predates the endpoint.
|
|
257
|
+
*/
|
|
258
|
+
interrupt?(): Promise<{
|
|
259
|
+
aborted: boolean;
|
|
260
|
+
note?: string;
|
|
261
|
+
}>;
|
|
262
|
+
/**
|
|
263
|
+
* Present only when this handle holds the owner key: fetch the agent's own
|
|
264
|
+
* process log (the framework subprocess stdout/stderr the runtime serves at
|
|
265
|
+
* `/log/agent`). Owner-private — each call signs a fresh `0GSealLog` owner
|
|
266
|
+
* message bound to this agent's URL (audience-bound, see issue #62), so unlike
|
|
267
|
+
* `chat` it needs the wallet, not just a token. Returns the log as text; pass
|
|
268
|
+
* `tail` to keep only the last N lines.
|
|
269
|
+
*/
|
|
270
|
+
logs?(opts?: {
|
|
271
|
+
tail?: number;
|
|
272
|
+
}): Promise<string>;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* Build an {@link AgentClient} from a base URL, the agent's declared surface,
|
|
276
|
+
* and (optionally) a way to authenticate:
|
|
277
|
+
* - `reauth` — mints a fresh owner token (sign + POST `/_seal/auth`). When
|
|
278
|
+
* present, the client can do owner ops; it mints the token lazily on first
|
|
279
|
+
* use and re-mints once on a 401 (the agent rotated it, e.g. after a reset).
|
|
280
|
+
* - `token` — a token to start from (optional; `reauth` still refreshes it).
|
|
281
|
+
* - `logAuth` — signs a fresh `0GSealLog` owner message (for `/log/agent`).
|
|
282
|
+
* Present only when the handle holds a wallet; gates `logs`.
|
|
283
|
+
* With none, the client is public: only `fetch` / `fetchWithProof`, which
|
|
284
|
+
* never attach a token (the `/api/*` surface isn't owner-gated). Owner ops
|
|
285
|
+
* (`chat`/`chatStream`) are attached iff the agent declares the route
|
|
286
|
+
* AND the client can authenticate — that presence is the capability signal.
|
|
287
|
+
*/
|
|
288
|
+
export declare function makeAgentClient(params: {
|
|
289
|
+
base: string;
|
|
290
|
+
services: AgentServiceEntry[];
|
|
291
|
+
routes: AgentRoute[];
|
|
292
|
+
token?: string;
|
|
293
|
+
reauth?: () => Promise<string>;
|
|
294
|
+
logAuth?: () => Promise<{
|
|
295
|
+
message: string;
|
|
296
|
+
signature: string;
|
|
297
|
+
}>;
|
|
298
|
+
/** Address that will redeem serve-proofs from this handle's responses. Sent
|
|
299
|
+
* as X-Client-Address so the TEE binds each proof to this redeemer (front-run
|
|
300
|
+
* protection). Omit for anonymous calls (proofs come back unredeemable). */
|
|
301
|
+
clientAddress?: string;
|
|
302
|
+
/** Per-process client id for the agent's single-driver seat (occupancy.go):
|
|
303
|
+
* ride it on every request so a displaced window is told with a 409 the
|
|
304
|
+
* moment it next speaks. Absent = this client does not participate. */
|
|
305
|
+
instanceId?: string;
|
|
306
|
+
/** Stall threshold in ms for the responses transport: no bytes for this long
|
|
307
|
+
* and the follow stream is torn down and resumed by sequence number.
|
|
308
|
+
* Defaults to 90s (nine missed 10s keepalives). Exposed so tests can drive
|
|
309
|
+
* the recovery in milliseconds; tune only with a reason. */
|
|
310
|
+
stallMs?: number;
|
|
311
|
+
}): AgentClient;
|
|
312
|
+
//# sourceMappingURL=AgentClient.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"AgentClient.d.ts","sourceRoot":"","sources":["../src/AgentClient.ts"],"names":[],"mappings":"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"}
|