@0gfoundation/0g-agentdna 0.0.0-stage → 0.2.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.
Files changed (206) hide show
  1. package/GUIDE.md +975 -0
  2. package/LICENSE +21 -0
  3. package/MIGRATION.md +84 -0
  4. package/MIGRATION.zh.md +70 -0
  5. package/PROVIDERS.md +273 -0
  6. package/PROVIDERS.zh.md +234 -0
  7. package/README.md +334 -2
  8. package/dist/AgentClient.d.ts +312 -0
  9. package/dist/AgentClient.d.ts.map +1 -0
  10. package/dist/AgentClient.js +715 -0
  11. package/dist/AgentClient.js.map +1 -0
  12. package/dist/AgenticID.d.ts +823 -0
  13. package/dist/AgenticID.d.ts.map +1 -0
  14. package/dist/AgenticID.js +1188 -0
  15. package/dist/AgenticID.js.map +1 -0
  16. package/dist/AgenticIDClient.d.ts +68 -0
  17. package/dist/AgenticIDClient.d.ts.map +1 -0
  18. package/dist/AgenticIDClient.js +198 -0
  19. package/dist/AgenticIDClient.js.map +1 -0
  20. package/dist/AttestorClient.d.ts +465 -0
  21. package/dist/AttestorClient.d.ts.map +1 -0
  22. package/dist/AttestorClient.js +1030 -0
  23. package/dist/AttestorClient.js.map +1 -0
  24. package/dist/Providers.d.ts +72 -0
  25. package/dist/Providers.d.ts.map +1 -0
  26. package/dist/Providers.js +182 -0
  27. package/dist/Providers.js.map +1 -0
  28. package/dist/ReputationClient.d.ts +213 -0
  29. package/dist/ReputationClient.d.ts.map +1 -0
  30. package/dist/ReputationClient.js +708 -0
  31. package/dist/ReputationClient.js.map +1 -0
  32. package/dist/SandboxClient.d.ts +107 -0
  33. package/dist/SandboxClient.d.ts.map +1 -0
  34. package/dist/SandboxClient.js +200 -0
  35. package/dist/SandboxClient.js.map +1 -0
  36. package/dist/ServeProof.d.ts +161 -0
  37. package/dist/ServeProof.d.ts.map +1 -0
  38. package/dist/ServeProof.js +230 -0
  39. package/dist/ServeProof.js.map +1 -0
  40. package/dist/ServeSession.d.ts +180 -0
  41. package/dist/ServeSession.d.ts.map +1 -0
  42. package/dist/ServeSession.js +336 -0
  43. package/dist/ServeSession.js.map +1 -0
  44. package/dist/Settings.d.ts +179 -0
  45. package/dist/Settings.d.ts.map +1 -0
  46. package/dist/Settings.js +247 -0
  47. package/dist/Settings.js.map +1 -0
  48. package/dist/abi.d.ts +2216 -0
  49. package/dist/abi.d.ts.map +1 -0
  50. package/dist/abi.js +1248 -0
  51. package/dist/abi.js.map +1 -0
  52. package/dist/cli/commands/cells.d.ts +34 -0
  53. package/dist/cli/commands/cells.d.ts.map +1 -0
  54. package/dist/cli/commands/cells.js +66 -0
  55. package/dist/cli/commands/cells.js.map +1 -0
  56. package/dist/cli/commands/doctor.d.ts +15 -0
  57. package/dist/cli/commands/doctor.d.ts.map +1 -0
  58. package/dist/cli/commands/doctor.js +236 -0
  59. package/dist/cli/commands/doctor.js.map +1 -0
  60. package/dist/cli/commands/interactive.d.ts +107 -0
  61. package/dist/cli/commands/interactive.d.ts.map +1 -0
  62. package/dist/cli/commands/interactive.js +3034 -0
  63. package/dist/cli/commands/interactive.js.map +1 -0
  64. package/dist/cli/commands/list.d.ts +31 -0
  65. package/dist/cli/commands/list.d.ts.map +1 -0
  66. package/dist/cli/commands/list.js +115 -0
  67. package/dist/cli/commands/list.js.map +1 -0
  68. package/dist/cli/commands/providers.d.ts +3 -0
  69. package/dist/cli/commands/providers.d.ts.map +1 -0
  70. package/dist/cli/commands/providers.js +21 -0
  71. package/dist/cli/commands/providers.js.map +1 -0
  72. package/dist/cli/commands/settings.d.ts +22 -0
  73. package/dist/cli/commands/settings.d.ts.map +1 -0
  74. package/dist/cli/commands/settings.js +188 -0
  75. package/dist/cli/commands/settings.js.map +1 -0
  76. package/dist/cli/commands/status.d.ts +16 -0
  77. package/dist/cli/commands/status.d.ts.map +1 -0
  78. package/dist/cli/commands/status.js +148 -0
  79. package/dist/cli/commands/status.js.map +1 -0
  80. package/dist/cli/commands/update.d.ts +21 -0
  81. package/dist/cli/commands/update.d.ts.map +1 -0
  82. package/dist/cli/commands/update.js +95 -0
  83. package/dist/cli/commands/update.js.map +1 -0
  84. package/dist/cli/config.d.ts +73 -0
  85. package/dist/cli/config.d.ts.map +1 -0
  86. package/dist/cli/config.js +239 -0
  87. package/dist/cli/config.js.map +1 -0
  88. package/dist/cli/env.d.ts +36 -0
  89. package/dist/cli/env.d.ts.map +1 -0
  90. package/dist/cli/env.js +74 -0
  91. package/dist/cli/env.js.map +1 -0
  92. package/dist/cli/envelope.d.ts +33 -0
  93. package/dist/cli/envelope.d.ts.map +1 -0
  94. package/dist/cli/envelope.js +62 -0
  95. package/dist/cli/envelope.js.map +1 -0
  96. package/dist/cli/errors.d.ts +48 -0
  97. package/dist/cli/errors.d.ts.map +1 -0
  98. package/dist/cli/errors.js +81 -0
  99. package/dist/cli/errors.js.map +1 -0
  100. package/dist/cli/inference.d.ts +21 -0
  101. package/dist/cli/inference.d.ts.map +1 -0
  102. package/dist/cli/inference.js +60 -0
  103. package/dist/cli/inference.js.map +1 -0
  104. package/dist/cli/logo.d.ts +21 -0
  105. package/dist/cli/logo.d.ts.map +1 -0
  106. package/dist/cli/logo.js +131 -0
  107. package/dist/cli/logo.js.map +1 -0
  108. package/dist/cli/main.d.ts +14 -0
  109. package/dist/cli/main.d.ts.map +1 -0
  110. package/dist/cli/main.js +223 -0
  111. package/dist/cli/main.js.map +1 -0
  112. package/dist/cli/proofs.d.ts +67 -0
  113. package/dist/cli/proofs.d.ts.map +1 -0
  114. package/dist/cli/proofs.js +133 -0
  115. package/dist/cli/proofs.js.map +1 -0
  116. package/dist/cli/ref.d.ts +39 -0
  117. package/dist/cli/ref.d.ts.map +1 -0
  118. package/dist/cli/ref.js +48 -0
  119. package/dist/cli/ref.js.map +1 -0
  120. package/dist/cli/sdk.d.ts +24 -0
  121. package/dist/cli/sdk.d.ts.map +1 -0
  122. package/dist/cli/sdk.js +65 -0
  123. package/dist/cli/sdk.js.map +1 -0
  124. package/dist/cli/settings.d.ts +66 -0
  125. package/dist/cli/settings.d.ts.map +1 -0
  126. package/dist/cli/settings.js +137 -0
  127. package/dist/cli/settings.js.map +1 -0
  128. package/dist/cli/tokenize.d.ts +61 -0
  129. package/dist/cli/tokenize.d.ts.map +1 -0
  130. package/dist/cli/tokenize.js +157 -0
  131. package/dist/cli/tokenize.js.map +1 -0
  132. package/dist/cli/types.d.ts +25 -0
  133. package/dist/cli/types.d.ts.map +1 -0
  134. package/dist/cli/types.js +8 -0
  135. package/dist/cli/types.js.map +1 -0
  136. package/dist/constants.d.ts +107 -0
  137. package/dist/constants.d.ts.map +1 -0
  138. package/dist/constants.js +74 -0
  139. package/dist/constants.js.map +1 -0
  140. package/dist/context.d.ts +108 -0
  141. package/dist/context.d.ts.map +1 -0
  142. package/dist/context.js +64 -0
  143. package/dist/context.js.map +1 -0
  144. package/dist/index.d.ts +45 -0
  145. package/dist/index.d.ts.map +1 -0
  146. package/dist/index.js +118 -0
  147. package/dist/index.js.map +1 -0
  148. package/dist/provider-catalog.json +23 -0
  149. package/dist/seal.d.ts +47 -0
  150. package/dist/seal.d.ts.map +1 -0
  151. package/dist/seal.js +145 -0
  152. package/dist/seal.js.map +1 -0
  153. package/dist/secretEnv.d.ts +119 -0
  154. package/dist/secretEnv.d.ts.map +1 -0
  155. package/dist/secretEnv.js +199 -0
  156. package/dist/secretEnv.js.map +1 -0
  157. package/dist/taskHash.d.ts +39 -0
  158. package/dist/taskHash.d.ts.map +1 -0
  159. package/dist/taskHash.js +119 -0
  160. package/dist/taskHash.js.map +1 -0
  161. package/dist/types.d.ts +336 -0
  162. package/dist/types.d.ts.map +1 -0
  163. package/dist/types.js +19 -0
  164. package/dist/types.js.map +1 -0
  165. package/package.json +75 -4
  166. package/scripts/sync-providers.cjs +8 -0
  167. package/src/AgentClient.ts +897 -0
  168. package/src/AgenticID.ts +1382 -0
  169. package/src/AgenticIDClient.ts +238 -0
  170. package/src/AttestorClient.ts +1306 -0
  171. package/src/Providers.ts +176 -0
  172. package/src/ReputationClient.ts +821 -0
  173. package/src/SandboxClient.ts +227 -0
  174. package/src/ServeProof.ts +290 -0
  175. package/src/ServeSession.ts +421 -0
  176. package/src/Settings.ts +296 -0
  177. package/src/abi.ts +1282 -0
  178. package/src/cli/commands/cells.ts +61 -0
  179. package/src/cli/commands/doctor.ts +235 -0
  180. package/src/cli/commands/interactive.ts +2715 -0
  181. package/src/cli/commands/list.ts +117 -0
  182. package/src/cli/commands/providers.ts +16 -0
  183. package/src/cli/commands/settings.ts +197 -0
  184. package/src/cli/commands/status.ts +170 -0
  185. package/src/cli/commands/update.ts +86 -0
  186. package/src/cli/config.ts +225 -0
  187. package/src/cli/env.ts +90 -0
  188. package/src/cli/envelope.ts +57 -0
  189. package/src/cli/errors.ts +114 -0
  190. package/src/cli/inference.ts +57 -0
  191. package/src/cli/logo.ts +125 -0
  192. package/src/cli/main.ts +235 -0
  193. package/src/cli/proofs.ts +160 -0
  194. package/src/cli/ref.ts +58 -0
  195. package/src/cli/sdk.ts +65 -0
  196. package/src/cli/settings.ts +153 -0
  197. package/src/cli/tokenize.ts +131 -0
  198. package/src/cli/types.ts +27 -0
  199. package/src/constants.ts +106 -0
  200. package/src/context.ts +161 -0
  201. package/src/index.ts +129 -0
  202. package/src/provider-catalog.json +23 -0
  203. package/src/seal.ts +163 -0
  204. package/src/secretEnv.ts +250 -0
  205. package/src/taskHash.ts +100 -0
  206. 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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"}