Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions agents/pi/admitted.json
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
{
"kind": "tree",
"path": "lib",
"sha256": "fbe13e2031ba2dda14a42634ec1d1cb710bfe5a6f87c3d105e9f71fe2e041e64"
"sha256": "cbb5bf80c669ea3ba0b6fa608181736f88ae61b71502f858b63418f050893349"
},
{
"kind": "skill",
Expand Down Expand Up @@ -74,7 +74,7 @@
{
"kind": "provider",
"path": "agents/pi/near-provider.ts",
"sha256": "2cf2c4d7dd1c2a69e98d7cb8506b58ec7787480ba16257c36f16a023a4ad3ded"
"sha256": "ead5b421867089bf13a0a209bf19ef4d5e65cb32f18634eae83a4482c2f3c630"
},
{
"kind": "provider",
Expand Down
72 changes: 4 additions & 68 deletions agents/pi/near-provider.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,77 +9,15 @@ import { createProvider, envApiKeyAuth } from "@earendil-works/pi-ai";
import { openAICompletionsApi } from "@earendil-works/pi-ai/compat";
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { providers } from "../../lib/config.mjs";
import { ATTESTED_OWNERS, chatSignatureFails, peerStatus, untrusted, decrypt, encrypt, verifyNearModel, withKey } from "../../lib/near.mjs";
import { ATTESTED_OWNERS, chatSignatureFails, untrusted, encrypt, verifyNearModel, withKey } from "../../lib/near.mjs";
import { deviceHeaders } from "../../lib/gift.mjs";
import { saveLeft } from "../../lib/peer.mjs";
import { prepareNearTextTools } from "../../lib/near-tool-boundary.mjs";
import { decryptSse } from "../../lib/near-sse.mjs";
import { tcbFlag } from "../../lib/status.mjs";

const FIELDS = ["content", "reasoning_content", "reasoning"];

// The node appends ": abalone-charge {charge, remaining}" after NEAR's stream. We recompute the charge from
// NEAR's usage and our own price list, and stop the turn if they differ.
// ": abalone-status <text>" from the peer (e.g. "confirming credit" while its next spending window reaches the chain's
// safe head) is shown until the answer starts.
// onNear gets NEAR's own bytes (without the peer's status and charge lines) before [DONE] is released.
// thinkOff: with enable_thinking=false GLM still writes a short thought, then "</think>", into the content (measured on
// NEAR). That prefix is passed on as reasoning, so the answer starts after the marker; with no marker, the buffered
// text is the answer and is sent as content at the end.
function decryptSse(body: ReadableStream<Uint8Array>, ecdh: crypto.ECDH, price?: { input: number; output: number }, onCharge?: (c: any) => void, onStatus?: (s: string | null) => void, onNear?: (raw: Buffer) => Promise<void>, thinkOff = false): ReadableStream<Uint8Array> {
const raw: Buffer[] = [];
let pending = "", usage: any = null, pre = "", split = !thinkOff;
const dec = new TextDecoder(), enc = new TextEncoder();
let held = false, charged = false;
const line = (l: string) => {
// The node's charge line follows NEAR's [DONE]; hold [DONE] back so the client reads (and checks) the charge first.
if ((price || !split) && l === "data: [DONE]") { held = true; return ""; }
if (price && l.startsWith(": abalone-charge ")) {
const c = JSON.parse(l.slice(17));
if (!usage) throw new Error(`Stopped. NEAR reported no usage for that answer, so its charge (${c.charge} µ$, the most it could have cost) cannot be checked here and nothing more will be sent.`);
const expect = Math.ceil(usage.prompt_tokens * price.input + usage.completion_tokens * price.output);
if (c.charge !== expect) throw new Error(`Stopped. The charge for that answer didn't match what was used, so nothing more will be sent.\ndetails: node charged ${c.charge} µ$, usage ${JSON.stringify(usage)} prices to ${expect} µ$`);
onCharge!(c);
charged = true;
return l;
}
if (l.startsWith(": abalone-status ")) { onStatus?.(peerStatus(l)); return ""; }
if (!l.startsWith("data: {")) return l;
onStatus?.(null);
const d = JSON.parse(l.slice(6));
usage = d.usage ?? usage;
for (const c of d.choices ?? []) for (const f of FIELDS) if (typeof c.delta?.[f] === "string" && c.delta[f]) c.delta[f] = decrypt(c.delta[f], ecdh);
for (const c of d.choices ?? []) {
if (split || typeof c.delta?.content !== "string" || !c.delta.content) continue;
const start = pre.length; pre += c.delta.content;
const i = pre.indexOf("</think>");
if (i < 0) { c.delta.reasoning_content = c.delta.content; delete c.delta.content; continue; }
c.delta.reasoning_content = pre.slice(start, Math.max(start, i));
c.delta.content = pre.slice(i + "</think>".length);
split = true;
}
return "data: " + JSON.stringify(d);
};
return body.pipeThrough(new TransformStream({
transform(chunk, ctl) {
if (onNear) raw.push(Buffer.from(chunk));
pending += dec.decode(chunk, { stream: true });
const lines = pending.split("\n");
pending = lines.pop()!;
for (const l of lines) ctl.enqueue(enc.encode(line(l) + "\n"));
},
async flush(ctl) {
if (pending) ctl.enqueue(enc.encode(line(pending)));
if (!split && pre) ctl.enqueue(enc.encode(`data: ${JSON.stringify({ choices: [{ index: 0, delta: { content: pre } }] })}\n\n`));
if (price && !charged) throw new Error("Stopped. The gift node sent no charge for that answer, so nothing more will be sent.");
if (onNear) {
let b = Buffer.concat(raw);
while (b.subarray(0, 17).toString() === ": abalone-status ") b = b.subarray(b.indexOf("\n\n") + 2);
await onNear(b.subarray(0, b.lastIndexOf(": abalone-charge ")));
}
if (held) ctl.enqueue(enc.encode("data: [DONE]\n\n"));
},
}));
}

// Shown in the status strip once a model is verified. Policy (providers.json): gateway and model TCB are reported, not
// gating. The model's out-of-date TCB is red; the gateway's (gw-tcb:) is not, since it sees only ciphertext and metadata.
const RED = (s: string) => `\x1b[31m${s}\x1b[39m`;
Expand All @@ -103,14 +41,12 @@ export async function nearProvider(pi: ExtensionAPI, id: string, gift: Gift | nu

const fetchE2ee: typeof fetch = async (input, init) => {
const body = JSON.parse(String(init!.body));
prepareNearTextTools(body);
if (!verified.has(body.model)) verified.set(body.model, verifyNearModel(cfg.baseUrl, body.model, getReport, cfg.policy).then((v) => (pi.appendEntry("near-attestation", { ...v.profile, provider: id }), ui?.setStatus(id, strip(v.profile, gift)), v)));
// A refusal must reach the user verbatim; the OpenAI client reports a thrown fetch only as "Connection error."
const v = await verified.get(body.model)!.catch((e) => e as Error);
const plain = crypto.createHash("sha256").update(String(init!.body)).digest("hex");
if (v instanceof Error) return new Response(JSON.stringify({ error: { message: v.message } }), { status: 403, headers: { "content-type": "application/json" } });
// Tool definitions and tool-call arguments are not covered by NEAR's E2EE, so they never go to NEAR.
delete body.tools; delete body.tool_choice; delete body.parallel_tool_calls;
if (body.messages.some((m: any) => m.tool_calls || m.role === "tool")) throw new Error("✗ refused: tool calls are not sent to NEAR (their arguments are not end-to-end encrypted)");
for (const m of body.messages) {
if (Array.isArray(m.content)) {
if (m.content.some((p: any) => p.type !== "text")) throw new Error("✗ refused: NEAR E2EE carries text only");
Expand Down
40 changes: 40 additions & 0 deletions docs/protocols/near-adapter.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,46 @@ A refused endpoint identity at the pinned transport is reported as `transport_re
distinct from `access_revoked_or_expired`. Every failure is a stable code; upstream
text, collateral errors and wire payloads never surface.

## Tool confidentiality and execution boundary

This integration encrypts message content and reasoning with the attested model
key. It does not implement NEAR's opt-in all-fields tool protocol. Native tool
schemas (including legacy function definitions) are removed before sending;
structured tool history in either format is refused before admission. The
ordinary and coupon adapters also refuse structured tool calls in responses.

Tools remain available through [the in-content protocol](../../lib/intools.mjs):
the system prompt describes them inside encrypted text, the model returns a tool
request inside encrypted answer text, Abalone executes it locally, and the result
returns as another encrypted message. “Tools off” in the ordinary NEAR status
means native API tools are disabled; it does not mean local tools are disabled.

| Data or action | Current integration boundary |
| --- | --- |
| Tool descriptions, requests and results in message text | Encrypted to/from the attested model |
| Native request tool schemas | Removed before sending |
| Native tool-call history | Refused |
| Native response calls on the coupon route | Refused |
| Native response calls on the ordinary route | Refused before delivery to Pi |
| Local tool execution | Runs on the client under the selected host/sandbox profile |
| Data sent by a tool to an external service | Disclosed to that destination; inference E2EE does not cover its use there |

NEAR's [published agent-loop example](https://github.com/nearai/nearai-cloud-verifier/blob/main/py/encrypted_agent_loop_verifier.py)
uses `X-Encrypt-All-Fields: true` with encryption version 2 and describes encryption
of tool names, arguments, definitions, reasoning and search-result output. Its
server-side search loop is described as running in the confidential VM, with the
query sent to Brave over TLS. This is source evidence checked on 2026-10-14,
not a fresh live test or qualification of every model. The example retrieves a
key from an attestation report; that operation alone is not cryptographic
verification of the key.

Adopting native encrypted tools requires verified key binding, complete field
coverage in both directions, response integrity checks, and refusal of plaintext
or unsupported protocol fallback. Keep the current encrypted-text path until
those properties are qualified. See [integration issue 73](https://github.com/amiller/abalone/issues/73),
[parser issue 56](https://github.com/amiller/abalone/issues/56), and the
[research thread](https://github.com/amiller/awesome-private-inference/issues/23).

## Bounded session lifetime and expiry

An adapter session is a bounded monotonic window set at opening — default 60 seconds,
Expand Down
7 changes: 4 additions & 3 deletions lib/coupon-near.mjs
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
// Host-side NEAR inference for a delivered coupon credential. This does not admit an issuer.
import { prepareNearTextTools, assertNearTextToolReply } from "./near-tool-boundary.mjs";
import crypto from "node:crypto";
import http from "node:http";
import fs from "node:fs";
Expand Down Expand Up @@ -73,8 +74,8 @@ function inferenceBody(bytes, profile, modelPublicKey) {
let body;
try { body = JSON.parse(bytes); } catch { throw fail("request_refused"); }
if (!body || typeof body !== "object" || Array.isArray(body)) throw fail("request_refused");
// Tools are carried in encrypted text by the existing in-content protocol.
for (const key of ["tools", "tool_choice", "parallel_tool_calls"]) delete body[key];
// Refusals stay static and sanitized at the credential boundary.
try { prepareNearTextTools(body); } catch { throw fail("request_refused"); }
const keys = ["model", "messages", "stream", ...["max_tokens", "temperature", "top_p", "chat_template_kwargs", "stream_options"].filter((key) => Object.hasOwn(body, key))];
if (!exact(body, keys) || body.model !== profile.model || body.stream !== true || !Array.isArray(body.messages) || !body.messages.length || body.messages.length > 256) throw fail("request_refused");
if (body.max_tokens !== undefined && (!Number.isSafeInteger(body.max_tokens) || body.max_tokens < 1 || body.max_tokens > profile.maxTokens)) throw fail("request_refused");
Expand Down Expand Up @@ -117,8 +118,8 @@ function plaintextSse(bytes, responseKey) {
let value;
try { value = JSON.parse(line.slice(6)); } catch { throw fail("provider_response_refused"); }
if (value.error || !Array.isArray(value.choices)) throw fail("provider_response_refused");
try { assertNearTextToolReply(value); } catch { throw fail("provider_response_refused"); }
for (const choice of value.choices) {
if (choice.delta?.tool_calls || choice.delta?.function_call) throw fail("provider_response_refused");
for (const field of FIELDS) if (choice.delta?.[field]) {
if (typeof choice.delta[field] !== "string" || !/^(?:[0-9a-f]{2})+$/.test(choice.delta[field])) throw fail("provider_response_refused");
try { choice.delta[field] = decrypt(choice.delta[field], responseKey); } catch { throw fail("provider_response_refused"); }
Expand Down
4 changes: 2 additions & 2 deletions lib/intools.mjs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Tools inside the encrypted content. NEAR's E2EE covers message content but not tool definitions or tool-call
// arguments, so abalone sends NEAR no tools (agents/pi/near-provider.ts). Instead the system prompt defines this text
// Tools inside the encrypted content. Our NEAR integration does not implement its opt-in all-fields tool
// encryption, so abalone sends no native tools (agents/pi/near-provider.ts). Instead the system prompt defines this text
// protocol: the model writes requests as GLM's native <tool_call> blocks (or our older <abalone-tool>{json} line), abalone runs them here in the
// workspace, and the result goes back as the next user turn, which NEAR's E2EE covers like any other message.
import { spawnSync } from "node:child_process";
Expand Down
73 changes: 73 additions & 0 deletions lib/near-sse.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
import { assertNearTextToolReply } from "./near-tool-boundary.mjs";
import { decrypt, peerStatus } from "./near.mjs";

const FIELDS = ["content", "reasoning_content", "reasoning"];

// The node appends ": abalone-charge {charge, remaining}" after NEAR's stream. We recompute the charge from
// NEAR's usage and our own price list, and stop the turn if they differ.
// ": abalone-status <text>" from the peer (e.g. "confirming credit" while its next spending window reaches the chain's
// safe head) is shown until the answer starts.
// onNear gets NEAR's own bytes (without the peer's status and charge lines) before [DONE] is released.
// thinkOff: with enable_thinking=false GLM still writes a short thought, then "</think>", into the content (measured on
// NEAR). That prefix is passed on as reasoning, so the answer starts after the marker; with no marker, the buffered
// text is the answer and is sent as content at the end.
export function decryptSse(body, ecdh, price, onCharge, onStatus, onNear, thinkOff = false) {
const raw = [];
let pending = "", usage = null, pre = "", split = !thinkOff;
const dec = new TextDecoder(), enc = new TextEncoder();
let held = false, charged = false;
const line = (l) => {
if (l.endsWith("\r")) l = l.slice(0, -1);
// SSE permits data: with zero or more spaces. Normalize before inspecting
// JSON so alternative framing cannot bypass native-tool refusal.
if (l.startsWith("data:")) l = "data: " + l.slice(5).trimStart();
// The node's charge line follows NEAR's [DONE]; hold [DONE] back so the client reads (and checks) the charge first.
if ((price || !split) && l === "data: [DONE]") { held = true; return ""; }
if (price && l.startsWith(": abalone-charge ")) {
const c = JSON.parse(l.slice(17));
if (!usage) throw new Error(`Stopped. NEAR reported no usage for that answer, so its charge (${c.charge} µ$, the most it could have cost) cannot be checked here and nothing more will be sent.`);
const expect = Math.ceil(usage.prompt_tokens * price.input + usage.completion_tokens * price.output);
if (c.charge !== expect) throw new Error(`Stopped. The charge for that answer didn't match what was used, so nothing more will be sent.\ndetails: node charged ${c.charge} µ$, usage ${JSON.stringify(usage)} prices to ${expect} µ$`);
onCharge(c);
charged = true;
return l;
}
if (l.startsWith(": abalone-status ")) { onStatus?.(peerStatus(l)); return ""; }
if (!l.startsWith("data: ") || l === "data: [DONE]" || l === "data: ") return l;
onStatus?.(null);
const d = JSON.parse(l.slice(6));
assertNearTextToolReply(d);
usage = d.usage ?? usage;
for (const c of d.choices ?? []) for (const f of FIELDS) if (typeof c.delta?.[f] === "string" && c.delta[f]) c.delta[f] = decrypt(c.delta[f], ecdh);
for (const c of d.choices ?? []) {
if (split || typeof c.delta?.content !== "string" || !c.delta.content) continue;
const start = pre.length; pre += c.delta.content;
const i = pre.indexOf("</think>");
if (i < 0) { c.delta.reasoning_content = c.delta.content; delete c.delta.content; continue; }
c.delta.reasoning_content = pre.slice(start, Math.max(start, i));
c.delta.content = pre.slice(i + "</think>".length);
split = true;
}
return "data: " + JSON.stringify(d);
};
return body.pipeThrough(new TransformStream({
transform(chunk, ctl) {
if (onNear) raw.push(Buffer.from(chunk));
pending += dec.decode(chunk, { stream: true });
const lines = pending.split("\n");
pending = lines.pop();
for (const l of lines) ctl.enqueue(enc.encode(line(l) + "\n"));
},
async flush(ctl) {
if (pending) ctl.enqueue(enc.encode(line(pending)));
if (!split && pre) ctl.enqueue(enc.encode(`data: ${JSON.stringify({ choices: [{ index: 0, delta: { content: pre } }] })}\n\n`));
if (price && !charged) throw new Error("Stopped. The gift node sent no charge for that answer, so nothing more will be sent.");
if (onNear) {
let b = Buffer.concat(raw);
while (b.subarray(0, 17).toString() === ": abalone-status ") b = b.subarray(b.indexOf("\n\n") + 2);
await onNear(b.subarray(0, b.lastIndexOf(": abalone-charge ")));
}
if (held) ctl.enqueue(enc.encode("data: [DONE]\n\n"));
},
}));
}
20 changes: 20 additions & 0 deletions lib/near-tool-boundary.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
// This integration uses encrypted message text for tools, not native API fields.
// Keep request and reply enforcement identical across ordinary and coupon routes.
export function prepareNearTextTools(body) {
if (!Array.isArray(body.messages) || body.messages.some((message) => !message ||
["tool", "function"].includes(message.role) ||
["tool_calls", "function_call", "tool_call_id", "name"].some((field) => Object.hasOwn(message, field)))) {
throw new Error("Stopped. Native tool history is unsupported by this NEAR integration; use tools inside encrypted message text.");
}
for (const field of ["tools", "tool_choice", "parallel_tool_calls", "functions", "function_call"]) delete body[field];
}

export function assertNearTextToolReply(value) {
for (const choice of value.choices ?? []) {
if (["tool_calls", "function_call"].includes(choice.finish_reason) ||
[choice.delta, choice.message].some((message) => message &&
["tool_calls", "function_call", "nearai_tool_result"].some((field) => message[field] != null))) {
throw new Error("Stopped. NEAR returned an unsupported native tool response; no tool from that response will run.");
}
}
}
Loading