nanocodex 0.6.6 → 0.6.7

package/cloud/actions/connection.mjs

@@ -1,3 +1,4 @@
+import { normalizeServices, serviceResource } from '../../services/scope.mjs';
 import {
   connectionRequestFromGrant,
   connectionFromWire,
@@ -57,11 +58,14 @@ const AGENT_VISIBILITY_NAMES = Object.freeze({
 
 export async function connect(client, options) {
   options ??= {};
-  const permission = options.permission ?? "agent.run";
+  const services = normalizeServices(options.capabilities?.services);
+  const permission = options.permission ?? (services ? "services.use" : "agent.run");
+  const standalone = permission === "services.use";
+  if (standalone && !services) throw new TypeError("services.use requires exact service capabilities");
   if (typeof permission !== "string" || permission.length === 0) throw new TypeError("connect permission must be a non-empty string");
   const requestedConnectors = normalizeCloudAccounts(options.capabilities?.cloudAccounts);
-  const agentVisibility = normalizeAgentVisibility(options.capabilities?.agent);
-  const authorization = options.authorization ?? (client.principal ? "hosted" : "access_key");
+  const agentVisibility = normalizeAgentVisibility(options.capabilities?.agent ?? (standalone ? { finalMessages: false, actionSummaries: false } : undefined));
+  const authorization = options.authorization ?? (client.principal || standalone ? "hosted" : "access_key");
   if (authorization !== "access_key" && authorization !== "hosted") {
     throw new TypeError("connect authorization must be access_key or hosted");
   }
@@ -71,6 +75,9 @@ export async function connect(client, options) {
   if (client.principal && options.capabilities?.authorizeAccessKey !== undefined) {
     throw new TypeError("host principal connections cannot request access-key or MPP authority");
   }
+  if (standalone && (authorization !== "hosted" || options.capabilities?.authorizeAccessKey || options.capabilities?.agent || requestedConnectors.includes("chatgpt") || options.tools?.length || options.mcpConnections?.length || options.conversationId)) {
+    throw new TypeError("Standalone services require hosted authorization without agent or payment capabilities");
+  }
   const appToolCatalog = hostedAppToolCatalog(options.tools ?? []);
   const appToolCatalogDigest = appToolCatalog.length === 0
     ? undefined
@@ -79,6 +86,7 @@ export async function connect(client, options) {
   const mcpConnections = normalizeMcpConnections(options.mcpConnections ?? []);
   const focusMcpConnectionId = normalizeMcpFocus(options.focusMcpConnectionId, mcpConnections);
   const exactRequest = connectionRequestFromGrant({
+    services,
     connectors: requestedConnectors,
     mcpConnections,
     permission,
@@ -98,6 +106,8 @@ export async function connect(client, options) {
     conversationId,
     authorization,
     appToolCatalogDigest,
+    services,
+    standalone,
   );
   if (client.principal
     && baseAuth.resources.some((resource) => resource.startsWith(MPP_RESOURCE_PREFIX))) {
@@ -311,10 +321,14 @@ function withConnectionResources(
   conversationId,
   authorization,
   appToolCatalogDigest,
+  services,
+  standalone,
 ) {
   const configured = typeof auth === "object" && auth !== null
     ? (auth.resources ?? []).filter((resource) =>
-      !Object.values(AGENT_VISIBILITY_RESOURCES).includes(resource)
+      !(standalone && (resource.startsWith("urn:nanocodex:agent:") || resource.startsWith(MPP_RESOURCE_PREFIX)))
+      && !resource.startsWith("urn:nanocodex:services:")
+      && !Object.values(AGENT_VISIBILITY_RESOURCES).includes(resource)
       && !resource.startsWith(AGENT_VISIBILITY_RESOURCE_PREFIX)
       && !resource.startsWith(AGENT_CONVERSATION_RESOURCE_PREFIX)
       && !resource.startsWith(CONNECTOR_RESOURCE_PREFIX)
@@ -332,6 +346,7 @@ function withConnectionResources(
     .map(([, value]) => value);
   const resources = [...new Set([
     ...configured,
+    ...(services ? [serviceResource(services)] : []),
     `${APP_RESOURCE_PREFIX}${encodeURIComponent(appId)}`,
     ...(appOrigin ? [`${APP_ORIGIN_RESOURCE_PREFIX}${encodeURIComponent(appOrigin)}`] : []),
     ...(requestedConnectors.length === 0

package/cloud/index.d.mts

@@ -6,7 +6,7 @@ export * as Principal from "./Principal.mjs";
 export * as Transport from "./Transport.mjs";
 export { connectActions } from "./Decorator.mjs";
 export { iframe, popup } from "./Dialog.mjs";
-export { http, mock } from "./Transport.mjs";
+export { http } from "./Transport.mjs";
 export type {
   AccessKey,
   AgentTurn,

package/cloud/index.mjs

@@ -6,4 +6,4 @@ export * as Principal from "./Principal.mjs";
 export * as Transport from "./Transport.mjs";
 export { connectActions } from "./Decorator.mjs";
 export { iframe, popup } from "./Dialog.mjs";
-export { http, mock } from "./Transport.mjs";
+export { http } from "./Transport.mjs";

package/cloud/internal.mjs

@@ -1,3 +1,4 @@
+import { normalizeServices } from '../services/scope.mjs';
 import { InvalidResponseError } from "./Errors.mjs";
 
 const CLOUD_ACCOUNT_PROVIDERS = Object.freeze([
@@ -50,6 +51,11 @@ export function connectionFromWire(value) {
     throw new InvalidResponseError("access-key connections require access-key and MPP authority");
   }
   const capabilities = strings(grant.capabilities, "connection.grant.capabilities");
+  if (grant.permission === "services.use" && (wire.agent_id !== undefined || authorization !== "hosted"
+    || grant.services === undefined || grant.conversation_id !== undefined || grant.app_tool_catalog_digest !== undefined
+    || capabilities.some(value => value === "nanocodex.agent" || value === "chatgpt" || value.startsWith("agent.") || value.startsWith("mcp:")))) {
+    throw new InvalidResponseError("Standalone service grants cannot contain agent or payment authority");
+  }
   const grantMcpConnections = mcpConnections(
     grant.mcp_connections,
     "connection.grant.mcp_connections",
@@ -67,7 +73,7 @@ export function connectionFromWire(value) {
   );
   return Object.freeze({
     ...owner,
-    agentId: string(wire.agent_id, "connection.agent_id"),
+    ...(grant.permission === "services.use" && wire.agent_id === undefined ? {} : { agentId: string(wire.agent_id, "connection.agent_id") }),
     grant: Object.freeze({
       id: hex(grant.id, "connection.grant.id"),
       permission: string(grant.permission, "connection.grant.permission"),
@@ -76,13 +82,14 @@ export function connectionFromWire(value) {
       ...(grant.conversation_id === undefined ? {} : {
         conversationId: agentConversationId(grant.conversation_id, "connection.grant.conversation_id"),
       }),
+      ...(grant.services === undefined ? {} : { services: normalizeServices(grant.services) }),
       capabilities,
       connectors: grantConnectors,
       ...(grantConnectorConnections === undefined ? {} : {
         connectorConnections: grantConnectorConnections,
       }),
       mcpConnections: grantMcpConnections,
-      visibility: agentVisibility(capabilities),
+      visibility: agentVisibility(capabilities, grant.permission === "services.use"),
       ...(grant.app_tool_catalog_digest === undefined ? {} : {
         appToolCatalogDigest: catalogDigest(
           grant.app_tool_catalog_digest,
@@ -135,6 +142,11 @@ export function connectionMatchesRequest(connection, options = {}) {
       return false;
     }
   }
+  if (Object.hasOwn(options.capabilities ?? {}, "services")) {
+    try {
+      if (JSON.stringify(normalizeServices(options.capabilities.services)) !== JSON.stringify(normalizeServices(connection.grant.services))) return false;
+    } catch { return false; }
+  }
   const requestedCloudAccounts = options.capabilities?.cloudAccounts;
   if (requestedCloudAccounts !== undefined) {
     const requested = CLOUD_ACCOUNT_PROVIDERS.filter(
@@ -190,6 +202,7 @@ export function reconnectRequestFromConnection(connection) {
 export function connectionRequestFromGrant(grant) {
   return Object.freeze({
     capabilities: Object.freeze({
+      services: grant.services,
       agent: grant.visibility,
       cloudAccounts: Object.freeze(Object.fromEntries(
         grant.connectors.map((provider) => [provider, true]),
@@ -297,13 +310,14 @@ export function grantFromWire(value) {
     ...(grant.conversation_id === undefined ? {} : {
       conversationId: agentConversationId(grant.conversation_id, "grant.conversation_id"),
     }),
+    ...(grant.services === undefined ? {} : { services: normalizeServices(grant.services) }),
     capabilities,
     connectors: grantConnectors,
     ...(grantConnectorConnections === undefined ? {} : {
       connectorConnections: grantConnectorConnections,
     }),
     mcpConnections: grantMcpConnections,
-    visibility: agentVisibility(capabilities),
+    visibility: agentVisibility(capabilities, grant.permission === "services.use"),
     ...(grant.app_tool_catalog_digest === undefined ? {} : {
       appToolCatalogDigest: catalogDigest(grant.app_tool_catalog_digest, "grant.app_tool_catalog_digest"),
     }),
@@ -329,7 +343,8 @@ const AGENT_VISIBILITY_CAPABILITIES = Object.freeze({
   rawTraces: "agent.trace.read",
 });
 
-function agentVisibility(capabilities) {
+function agentVisibility(capabilities, standalone = false) {
+  if (standalone) return Object.freeze({ finalMessages: false, actionSummaries: false, conversationHistory: false, rawTraces: false });
   const recognized = Object.values(AGENT_VISIBILITY_CAPABILITIES)
     .some((capability) => capabilities.includes(capability));
   const rawTraces = capabilities.includes(AGENT_VISIBILITY_CAPABILITIES.rawTraces);

package/cloud/mercator.mjs

@@ -1,4 +1,4 @@
-import { DEFAULT_MERCATOR_MCP_URL } from "../runtime/tempo-provider.mjs";
+import { DEFAULT_MERCATOR_MCP_URL } from "../runtime/mercator.mjs";
 
 const MERCATOR_ORIGIN = new URL(DEFAULT_MERCATOR_MCP_URL).origin;
 const JOBS_PATH = "/v1/jobs";

package/cloud/mock.d.mts

@@ -0,0 +1,17 @@
+import type { Transport } from "./Transport.mjs";
+
+/**
+ * In-memory Nanocodex Connect API for tests and demos. Requires the optional
+ * `ox` peer dependency, which computes the EIP-191 access-key witness.
+ */
+export const MOCK_ACCOUNT_ADDRESS: `0x${string}`;
+export const MOCK_MACHINE_USD_ADDRESS: `0x${string}`;
+
+export function mock(options?: Readonly<{
+  accountAddress?: `0x${string}` | undefined;
+  appName?: string | undefined;
+  appOrigin?: string | undefined;
+  key?: string | undefined;
+  machineUsdAddress?: `0x${string}` | undefined;
+  name?: string | undefined;
+}>): Transport<"mock">;

package/cloud/mock.mjs

@@ -0,0 +1,392 @@
+// In-memory Nanocodex Connect API for tests and demos. Its prepared access-key
+// witness is the real EIP-191 digest, so this module needs the optional `ox`
+// peer dependency; the core `nanocodex/connect` entry point never imports it.
+import { Hex, PersonalMessage } from "ox";
+
+import { HttpError, InvalidResponseError } from "./Errors.mjs";
+import { from } from "./Transport.mjs";
+
+export const MOCK_ACCOUNT_ADDRESS = "0x8ba1f109551bd432803012645ac136ddd64dba72";
+export const MOCK_MACHINE_USD_ADDRESS = "0x20c0000000000000000000000000000000000001";
+
+export function mock(options = {}) {
+  const accountAddress = options.accountAddress ?? MOCK_ACCOUNT_ADDRESS;
+  const machineUsdAddress = options.machineUsdAddress ?? MOCK_MACHINE_USD_ADDRESS;
+  const appName = options.appName ?? "Acme Workspace";
+  const grants = new Map();
+  let sequence = 0;
+
+  return from({
+    key: options.key ?? "mock",
+    name: options.name ?? "Nanocodex mock",
+    type: "mock",
+    setup({ appId }) {
+      return {
+        baseUrl: "memory://nanocodex",
+        async request(request) {
+          if (request.method === "POST" && request.path === "/v1/connections") {
+            const authorization = request.body?.key_authorization;
+            const keyId = authorization?.keyId ?? authorization?.address;
+            if (typeof keyId !== "string") throw new InvalidResponseError("key authorization is missing keyId");
+            const expiry = authorization.expiry ?? Math.floor(Date.now() / 1000) + 30 * 86_400;
+            const connectors = requestedConnectors(request.body?.requested_connectors);
+            const mcpConnections = requestedMcpConnections(request.body?.requested_mcp_connections);
+            const grantId = mockHex(`${appId}:${accountAddress}:${keyId}`, 32);
+            const connectorConnections = mockConnectorConnections(connectors, grantId);
+            const wire = {
+              grant_token: `mock-grant-${grantId.slice(2)}`,
+              account_address: accountAddress,
+              agent_id: `agent_${grantId.slice(2, 14)}`,
+              grant: {
+                id: grantId,
+                permission: request.body?.permission ?? "agent.run",
+                status: "active",
+                expires_at: expiry,
+                capabilities: [
+                  "nanocodex.agent",
+                  "mercator.boost",
+                  "mpp.mach",
+                  ...connectors,
+                  ...mcpConnections.map(({ id }) => `mcp:${id}`),
+                ],
+                connector_connections: connectorConnections,
+                mcp_connections: mcpConnections,
+              },
+              access_key: {
+                address: keyId,
+                chain_id: String(authorization.chainId ?? 4217),
+                key_id: keyId,
+                key_type: authorization.keyType ?? "p256",
+                limits: authorization.limits ?? [{ token: machineUsdAddress, limit: "10000000", period: 86_400 }],
+                scopes: authorization.scopes ?? [],
+                witness: authorization.witness ?? mockHex(`${grantId}:witness`, 32),
+                expiry,
+                authorization: request.body?.signed_key_authorization ?? "0x01",
+              },
+              mpp: {
+                token: machineUsdAddress,
+                symbol: "MACH",
+                balance_status: "ready",
+                settlement_token: "0x20C000000000000000000000b9537d11c60E8b50",
+                settlement_symbol: "USDC.e",
+                settlement_balance_atomics: "0",
+                limit_atomics: "10000000",
+                max_per_request_atomics: "250000",
+                period: 86_400,
+                balance_atomics: "0",
+                spent_atomics: "0",
+              },
+            };
+            grants.set(grantId, wire);
+            return wire;
+          }
+
+          if (request.method === "GET" && request.path.match(/^\/v1\/grants\/0x[0-9a-f]+$/)) {
+            return requiredGrant(grants, request.path.split("/")[3]);
+          }
+
+          if (request.method === "POST" && request.path === "/v1/connections/prepare") {
+            const permission = request.body?.permission;
+            if (typeof permission !== "string" || permission.length === 0) {
+              throw new TypeError("connection permission must be a non-empty string");
+            }
+            const resources = request.body?.resources ?? [];
+            if (!Array.isArray(resources) || resources.some((resource) => typeof resource !== "string" || resource.length === 0)) {
+              throw new TypeError("connection resources must be non-empty strings");
+            }
+            const connectors = connectorResources(resources);
+            const id = `req_${++sequence}`;
+            const accessPolicy = request.body?.authorize_access_key;
+            const keyId = accessPolicy?.address ?? mockHex(`${appId}:${accountAddress}:${permission}:key`, 20);
+            const tokenLimit = accessPolicy?.limits?.find((limit) => limit.token === machineUsdAddress);
+            const expiry = accessPolicy?.expiry ?? Math.floor(Date.now() / 1000) + 30 * 86_400;
+            const dailyLimit = tokenLimit?.limit ?? "10000000";
+            const period = tokenLimit?.period ?? 86_400;
+            const appOrigin = options.appOrigin ?? "https://app.example";
+            const appUrl = new URL(appOrigin);
+            const nonce = mockHex(`${id}:siwe-nonce`, 8).slice(2);
+            const issuedAt = new Date().toISOString();
+            const authMessage = [
+              `${appUrl.host} wants you to sign in with your Ethereum account:`,
+              "0x0000000000000000000000000000000000000000",
+              "",
+              `${appName} wants to connect your Nanocodex agent.`,
+              "",
+              `URI: ${appUrl.origin}`,
+              "Version: 1",
+              "Chain ID: 4217",
+              `Nonce: ${nonce}`,
+              `Issued At: ${issuedAt}`,
+              ...(resources.length > 0
+                ? ["Resources:", ...resources.map((resource) => `- ${resource}`)]
+                : []),
+            ].join("\n");
+            return {
+              request_id: id,
+              app: { id: appId, name: appName, origin: appOrigin },
+              account_address: accountAddress,
+              auth: {
+                message: authMessage,
+                resources,
+              },
+              permission: {
+                id: permission,
+                title: "Use your Nanocodex agent",
+                description: "Run an app-owned Nanocodex agent with your approved capabilities.",
+                connectors: [
+                  { id: "agent", name: "Nanocodex", detail: "Instantiate the real Nanocodex runtime in this app" },
+                  { id: "mercator", name: "BOOST with Mercator", detail: "Find and compose the right tools, paying per call through MPP" },
+                  ...connectors.map((provider) => ({
+                    id: provider,
+                    name: connectorName(provider),
+                    detail: `Use the connected ${connectorName(provider)} account through the grant`,
+                  })),
+                ],
+              },
+              access_key: {
+                address: keyId,
+                chain_id: accessPolicy?.chainId ?? "4217",
+                key_id: keyId,
+                public_key: accessPolicy?.publicKey ?? mockHex(`${id}:public`, 65),
+                key_type: accessPolicy?.keyType ?? "p256",
+                limits: accessPolicy?.limits ?? [{ token: machineUsdAddress, limit: dailyLimit, period }],
+                scopes: accessPolicy?.scopes ?? [],
+                witness: PersonalMessage.getSignPayload(Hex.fromString(authMessage)),
+                expiry,
+              },
+              mpp: {
+                token: machineUsdAddress,
+                symbol: "MACH",
+                settlement_token: "0x20C000000000000000000000b9537d11c60E8b50",
+                settlement_symbol: "USDC.e",
+                settlement_balance_atomics: "0",
+                limit_atomics: dailyLimit,
+                period,
+                max_per_request_atomics: "250000",
+              },
+            };
+          }
+
+          if (request.method === "POST" && request.path === "/v1/connections/complete") {
+            const prepared = request.body?.prepared;
+            const approval = request.body?.approval;
+            if (!prepared || !approval || approval.approved !== true) {
+              throw new InvalidResponseError("connection approval is malformed");
+            }
+            const approvedCapabilities = approval.capabilities;
+            if (
+              approvedCapabilities?.keyAuthorization?.witness !== prepared.access_key.witness
+              || approvedCapabilities?.personalSign?.message !== prepared.auth.message
+              || typeof approvedCapabilities?.personalSign?.keyAuthorization !== "string"
+              || typeof approvedCapabilities?.signature !== "string"
+            ) {
+              throw new InvalidResponseError("connection approval is not bound to the SIWE challenge and key authorization");
+            }
+            const grantId = mockHex(`${prepared.app.id}:${prepared.account_address}:${prepared.access_key.key_id}`, 32);
+            const wire = {
+              grant_token: `mock-grant-${grantId.slice(2)}`,
+              account_address: prepared.account_address,
+              agent_id: `agent_${grantId.slice(2, 14)}`,
+              grant: {
+                id: grantId,
+                permission: prepared.permission.id,
+                status: "active",
+                expires_at: prepared.access_key.expiry,
+                capabilities: prepared.permission.connectors.map(({ id }) => id),
+              },
+              access_key: prepared.access_key,
+              mpp: {
+                ...prepared.mpp,
+                balance_atomics: "0",
+                balance_status: "ready",
+                spent_atomics: "0",
+              },
+            };
+            grants.set(grantId, wire);
+            return wire;
+          }
+
+          if (request.method === "POST" && request.path === "/v1/connections/disconnect") {
+            return undefined;
+          }
+
+          if (request.method === "GET" && request.path.match(/^\/v1\/grants\/0x[0-9a-f]+\/mpp\/balance$/)) {
+            const wire = requiredGrant(grants, request.path.split("/")[3]);
+            wire.mpp = { ...wire.mpp, balance_status: "ready" };
+            return wire;
+          }
+
+          if (request.method === "POST" && request.path.match(/^\/v1\/grants\/0x[0-9a-f]+\/revoke$/)) {
+            const grantId = request.path.split("/")[3];
+            const wire = requiredGrant(grants, grantId);
+            wire.grant = { ...wire.grant, status: "revoked" };
+            return wire.grant;
+          }
+
+          if (request.method === "GET" && request.path === "/v1/machine-usd/config") {
+            return {
+              chain_id: 4217,
+              min_usd_amount_cents: 500,
+              max_usd_amount_cents: 10_000,
+              stripe_publishable_key: "pk_test_nanocodex",
+              token_address: machineUsdAddress,
+            };
+          }
+
+          if (request.method === "POST" && request.path.match(/^\/v1\/grants\/0x[0-9a-f]+\/fund$/)) {
+            const grantId = request.path.split("/")[3];
+            const wire = requiredActiveGrant(grants, grantId);
+            const usdAmountCents = request.body?.usd_amount_cents;
+            if (!Number.isSafeInteger(usdAmountCents) || usdAmountCents < 500 || usdAmountCents > 10_000) {
+              throw new TypeError("MACH amount must be from 500 through 10000 cents");
+            }
+            const amount = BigInt(usdAmountCents) * 10_000n;
+            wire.mpp = {
+              ...wire.mpp,
+              balance_atomics: String(BigInt(wire.mpp.balance_atomics) + amount),
+            };
+            return {
+              order: {
+                id: `ord_${++sequence}`,
+                status: "complete",
+                usd_amount_cents: usdAmountCents,
+                machine_usd_amount_atomics: String(amount),
+                issuance_transaction_hash: mockHex(`fund:${sequence}`, 32),
+              },
+              connection: wire,
+            };
+          }
+
+          if (request.method === "POST" && request.path.match(/^\/v1\/grants\/0x[0-9a-f]+\/mpp\/charge$/)) {
+            const grantId = request.path.split("/")[3];
+            const wire = requiredActiveGrant(grants, grantId);
+            const amount = BigInt(request.body?.amount_atomics ?? "-1");
+            const max = BigInt(wire.mpp.max_per_request_atomics);
+            const spent = BigInt(wire.mpp.spent_atomics);
+            const limit = BigInt(wire.mpp.limit_atomics);
+            const balance = BigInt(wire.mpp.balance_atomics);
+            if (amount <= 0n) throw new TypeError("MPP amount must be positive");
+            if (amount > max) throw new HttpError(403, "This payment exceeds the per-request permission.", { code: "mpp_request_limit_exceeded" });
+            if (spent + amount > limit) throw new HttpError(403, "This payment exceeds the daily MPP permission.", { code: "mpp_period_limit_exceeded" });
+            if (amount > balance) throw new HttpError(402, "Add MACH before paying for this capability.", { code: "machine_usd_required" });
+            wire.mpp = {
+              ...wire.mpp,
+              balance_atomics: String(balance - amount),
+              spent_atomics: String(spent + amount),
+            };
+            return {
+              receipt: {
+                id: `mpp_${++sequence}`,
+                amount_atomics: String(amount),
+                origin: request.body?.origin,
+                transaction_hash: mockHex(`mpp:${sequence}`, 32),
+              },
+              connection: wire,
+            };
+          }
+
+          throw new HttpError(404, `No mock route for ${request.method ?? "GET"} ${request.path}`, {
+            code: "mock_route_not_found",
+          });
+        },
+      };
+    },
+  });
+}
+
+function requiredGrant(grants, grantId) {
+  const grant = grants.get(grantId);
+  if (!grant) throw new HttpError(404, "Nanocodex grant not found", { code: "grant_not_found" });
+  return grant;
+}
+
+function requestedConnectors(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new TypeError("requested_connectors must be an array");
+  const supported = [
+    "github",
+    "gmail",
+    "gdrive",
+    "gcalendar",
+    "gtasks",
+    "gdocs",
+    "gsheets",
+    "gslides",
+    "gcontacts",
+    "slack",
+    "x",
+    "spotify",
+    "soundcloud",
+  "link",
+    "chatgpt",
+  ];
+  if (value.some((provider) => !supported.includes(provider))) {
+    throw new TypeError("requested_connectors contains an unsupported provider");
+  }
+  return supported.filter((provider) => value.includes(provider));
+}
+
+function requestedMcpConnections(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 16
+    || value.some((id) => typeof id !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(id))
+    || new Set(value).size !== value.length) {
+    throw new TypeError("requested_mcp_connections must contain exact hosted connection IDs");
+  }
+  return value.map((id) => ({ id, name: "MCP connection" }));
+}
+
+function connectorResources(resources) {
+  return requestedConnectors(resources
+    .filter((resource) => resource.startsWith("urn:nanocodex:connector:"))
+    .map((resource) => resource.slice("urn:nanocodex:connector:".length)));
+}
+
+function connectorName(provider) {
+  return ({
+    github: "GitHub",
+    gmail: "Gmail",
+    gdrive: "Google Drive",
+    gcalendar: "Google Calendar",
+    gtasks: "Google Tasks",
+    gdocs: "Google Docs",
+    gsheets: "Google Sheets",
+    gslides: "Google Slides",
+    gcontacts: "Google Contacts",
+    slack: "Slack",
+    x: "X",
+    spotify: "Spotify",
+    soundcloud: "SoundCloud",
+  link: "Stripe Link",
+    chatgpt: "ChatGPT",
+  })[provider];
+}
+
+function mockConnectorConnections(connectors, grantId) {
+  return Object.fromEntries(connectors
+    .filter((connector) => connector !== "chatgpt")
+    .map((connector) => [
+      connector,
+      [mockHex(`${grantId}:${connector}:connection`, 32).slice(2, 45)],
+    ]));
+}
+
+function requiredActiveGrant(grants, grantId) {
+  const grant = requiredGrant(grants, grantId);
+  if (grant.grant.status !== "active") {
+    throw new HttpError(403, "This Nanocodex grant has been revoked.", { code: "grant_revoked" });
+  }
+  return grant;
+}
+
+function mockHex(seed, bytes) {
+  let state = 2166136261;
+  let output = "";
+  for (let index = 0; output.length < bytes * 2; index += 1) {
+    const code = seed.charCodeAt(index % seed.length) + index;
+    state ^= code;
+    state = Math.imul(state, 16777619) >>> 0;
+    output += state.toString(16).padStart(8, "0");
+  }
+  return `0x${output.slice(0, bytes * 2)}`;
+}

package/cloud/types.d.mts

@@ -120,6 +120,7 @@ export type ConnectAgent = Readonly<{
 }>;
 
 export type Grant = Readonly<{
+  services?: import("../services/index.mjs").ServiceCapabilities | undefined;
   id: Hex;
   permission: string;
   status: "active" | "revoked" | "expired";
@@ -153,7 +154,8 @@ export type MppPermission = Readonly<{
 }>;
 
 type ConnectionBase = Readonly<{
-  agentId: string;
+  /** Absent on a standalone services grant. */
+  agentId?: string;
   grant: Grant;
 }>;
 

package/cloudflare/Agent.d.mts

@@ -96,6 +96,8 @@ export function create(owner: create.Owner, options?: create.Options): Promise<c
 export declare namespace create {
   type Owner = DurableObjectOwner;
   type Options = Readonly<{
+    /** Observer-only instant steering; disabled unless explicitly enabled. */
+    instantToolSteering?: boolean | undefined;
     /** Awaited host preservation barrier; scoped to this root, never inherited by children. */
     beforeCompaction?: AgentOptions["beforeCompaction"];
     /** Stable portable state identity. It cannot change after first construction or import. */