super-dsh 0.1.11 → 0.1.12

package/superd-hub/dist/foreign-agy.js

@@ -0,0 +1,110 @@
+/** Antigravity native plugin: tool catalog via stdio, delivery via the owned CLI. */
+import { mkdir, readFile, readdir, writeFile, rename, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const owner = 'super-dsh:agy-hub-plugin:v1\n';
+// t and earlier test installers appended a second LF; recognize that exact
+// owned legacy form while rewriting the marker canonically below.
+const isOwner = (marker) => marker === owner || marker === owner + '\n';
+const jobs = new Map();
+async function serialized(home, work) {
+    const key = resolve(home);
+    const current = (jobs.get(key) ?? Promise.resolve()).catch(() => { }).then(work);
+    jobs.set(key, current);
+    try {
+        return await current;
+    }
+    finally {
+        if (jobs.get(key) === current)
+            jobs.delete(key);
+    }
+}
+async function atomic(path, content) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, content, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+// Only MCP's synchronous catalog/call surface is used. Incoming A2A delivery
+// never uses MCP notifications: the Hub already owns the live CLI stdin.
+const serverModule = String.raw `const {readFileSync}=require('node:fs');
+const {join}=require('node:path');
+const {createInterface}=require('node:readline');
+const publicConfig=()=>JSON.parse(readFileSync(join(__dirname,'connection.json'),'utf8'));
+async function request(m){
+ if(m.method==='initialize')return {protocolVersion:m.params?.protocolVersion??'2024-11-05',capabilities:{tools:{}},serverInfo:{name:'superd-hub',version:'1.0.0'}};
+ if(m.method==='ping')return {};
+ if(m.method==='tools/list')return {tools:[publicConfig().definition]};
+ if(m.method==='tools/call'){
+  if(m.params?.name!=='superd-hub')throw Object.assign(new Error('Unknown tool'),{code:-32602});
+  try {
+   const privateSession=process.env.SUPERD_HUB_SESSION;
+   const config=privateSession?JSON.parse(privateSession):publicConfig();
+   const url=new URL(config.url);
+   if(url.protocol!=='http:'||url.hostname!=='127.0.0.1'||url.pathname!=='/tool')throw new Error('Hub requires a same-machine loopback URL');
+   const headers={'content-type':'application/json'};
+   if(privateSession)headers.authorization='Bearer '+config.token;
+   const response=await fetch(url,{method:'POST',headers,body:JSON.stringify(m.params.arguments??{}),signal:AbortSignal.timeout(120000)});
+   const envelope=await response.json();
+   return {content:[{type:'text',text:JSON.stringify(envelope.error?{error:envelope.error}:envelope.result)}],isError:!response.ok||!!envelope.error};
+  }catch(error){return {content:[{type:'text',text:'[E_HUB_UNAVAILABLE] '+error.message+'. Open or resume through Super D.'}],isError:true};}
+ }
+ throw Object.assign(new Error('Method not found'),{code:-32601});
+}
+for await (const line of createInterface({input:process.stdin,crlfDelay:Infinity})){
+ let m;try{m=JSON.parse(line)}catch{process.stdout.write(JSON.stringify({jsonrpc:'2.0',id:null,error:{code:-32700,message:'Parse error'}})+'\n');continue;}
+ if(m.id===undefined)continue;
+ try{const result=await request(m);process.stdout.write(JSON.stringify({jsonrpc:'2.0',id:m.id,result})+'\n');}
+ catch(error){process.stdout.write(JSON.stringify({jsonrpc:'2.0',id:m.id,error:{code:error.code??-32603,message:error.message}})+'\n');}
+}
+`;
+// CJS permits the installed helper to run without a package dependency or loader.
+const server = serverModule.replace('for await (const line', ';(async()=>{for await (const line') + '})().catch(()=>process.exitCode=1);\n';
+export async function refreshAgyNativeEndpoint(endpoint, nativeHome) {
+    await serialized(nativeHome, async () => {
+        const directory = join(nativeHome, 'plugins', 'superd-hub');
+        if (!isOwner(await readFile(join(directory, '.superd-owner'), 'utf8').catch(() => '')))
+            return;
+        const config = JSON.parse(await readFile(join(directory, 'connection.json'), 'utf8'));
+        const url = await endpoint();
+        if (url !== undefined)
+            await atomic(join(directory, 'connection.json'), JSON.stringify({ url, definition: config.definition }) + '\n');
+    });
+}
+export async function prepareAgyNativePlugin(binding, nativeHome, stagingDirectory, install) {
+    const transport = await binding.transport();
+    if (transport === undefined)
+        return undefined;
+    return serialized(nativeHome, async () => {
+        const directory = join(nativeHome, 'plugins', 'superd-hub');
+        const entries = await readdir(directory).catch((error) => { if (error.code !== 'ENOENT')
+            throw error; return []; });
+        if (entries.length > 0 && !isOwner(await readFile(join(directory, '.superd-owner'), 'utf8').catch(() => '')))
+            throw new Error(`Refusing to overwrite unowned native plugin directory: ${directory}`);
+        await mkdir(stagingDirectory, { recursive: true, mode: 0o700 });
+        const files = {
+            '.superd-owner': owner,
+            'plugin.json': JSON.stringify({ name: 'superd-hub', description: 'Substrate Hub facility for Super D conversations' }),
+            'connection.json': JSON.stringify({ url: transport.url, definition: transport.definition }),
+            'server.cjs': server,
+            'mcp_config.json': JSON.stringify({ mcpServers: { 'superd-hub': { command: process.execPath, args: [join(directory, 'server.cjs')] } } }),
+        };
+        const payload = (name, content) => name === '.superd-owner' ? content : content + '\n';
+        for (const [name, content] of Object.entries(files))
+            await atomic(join(stagingDirectory, name), payload(name, content));
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        for (const [name, content] of Object.entries(files))
+            await atomic(join(directory, name), payload(name, content));
+        await install(stagingDirectory);
+        // The official installer may skip non-customization helper files; ensure
+        // our own staged payload is present, with no capability written publicly.
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        for (const [name, content] of Object.entries(files))
+            await atomic(join(directory, name), payload(name, content));
+        return JSON.stringify(transport);
+    });
+}

package/superd-hub/dist/foreign-claude.d.ts

@@ -0,0 +1,4 @@
+import type { ForeignHubBinding } from './foreign-hub.js';
+export declare function refreshClaudeNativeEndpoint(endpoint: () => Promise<string | undefined>, nativeHome: string): Promise<void>;
+/** Incrementally enable our owned native plugin; never persist a session capability. */
+export declare function prepareClaudeNativePlugin(binding: Pick<ForeignHubBinding, 'transport'>, nativeHome: string): Promise<string | undefined>;

package/superd-hub/dist/foreign-claude.js

@@ -0,0 +1,160 @@
+/** Claude's native Mods API: one tool and an addressed, background inbox. */
+import { mkdir, readFile, readdir, writeFile, rename, rm } from 'node:fs/promises';
+import { join, resolve, delimiter } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const owner = 'super-dsh:claude-hub-mod:v1\n';
+const preparing = new Map();
+async function serialized(home, work) {
+    const key = resolve(home);
+    const current = (preparing.get(key) ?? Promise.resolve()).catch(() => { }).then(work);
+    preparing.set(key, current);
+    try {
+        return await current;
+    }
+    finally {
+        if (preparing.get(key) === current)
+            preparing.delete(key);
+    }
+}
+async function atomicWrite(path, content) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, content, { mode: 0o600, flag: 'wx' });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+// Runs inside Claude's Mod sandbox. No Node imports, MCP process, prompt
+// injection or turn hooks. Native unaddressed sessions register the tool but
+// do not poll; the post office itself reports E_HUB_ADDRESS_REQUIRED.
+const moduleSource = String.raw `async function connection($) {
+    const privateConfig = await $.env.get("SUPERD_HUB_SESSION");
+    const config = JSON.parse(privateConfig || await $.fs.read($.plugin.root + "/connection.json"));
+    if (!config.url.startsWith("http://127.0.0.1:")) throw new Error("Super D Hub requires same-machine loopback HTTP");
+    return { config, addressed: Boolean(privateConfig) };
+  }
+  function headers(config, addressed) {
+    return { "Content-Type": "application/json", ...(addressed ? { Authorization: "Bearer " + config.token } : {}) };
+  }
+export function register(on) {
+  let timer;
+  let receiving = false;
+  let submitted;
+  const queued = new Map();
+  on("session.start", async ($, e, next) => {
+    timer?.cancel();
+    const { config, addressed } = await connection($);
+    await $.tool.register(config.definition);
+    if (addressed) timer = $.clock.every(250, async () => {
+      if (receiving) return;
+      receiving = true;
+      try {
+        for (const [id, pending] of queued) if (pending.aborted) { queued.delete(id); submitted = undefined; }
+        const url = config.url.replace(/\/tool$/, "/inbox");
+        const response = await $.http.fetch(url, { method: "GET", headers: headers(config, true) });
+        if (response.status === 401 || response.status === 403) { timer?.cancel(); return; }
+        if (!response.ok) return;
+        const message = JSON.parse(response.text).message;
+        if (!message) return;
+        if (submitted !== message.id) {
+          const marker = "[superd-hub:inbox message=" + message.id + "]";
+          queued.set(message.id, { marker, url, config, confirmed: false, aborted: false });
+          const outcome = await $.prompt.submit({ text: marker + "\n" + message.text });
+          if (outcome && "drop" in outcome) { queued.delete(message.id); return; }
+          submitted = message.id;
+        }
+        // An unconfirmed turn is cancelled before its model runs and remains
+        // in the inbox to retry; never ACK it or send a late start receipt.
+        if (!queued.get(message.id)?.confirmed) return;
+        // Ack only after the runtime has accepted the plugin's prompt. If the
+        // ack fails, retry it without submitting the same prompt twice.
+        const ack = await $.http.fetch(url, { method: "POST", headers: headers(config, true), body: JSON.stringify({ ack: message.id }) });
+        if (ack.ok) { submitted = undefined; queued.delete(message.id); }
+      } catch (_) {
+        // A temporary offline post office leaves the message queued there.
+      } finally { receiving = false; }
+    });
+    return next(e);
+  });
+  // This receipt binds the Hub's source message to its actual native turn;
+  // a different user/plugin turn cannot claim it by happening to run first.
+  on("turn.start", async ($, e, next) => {
+    for (const [id, pending] of queued) {
+      if (!e.text.includes(pending.marker)) continue;
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          const response = await $.http.fetch(pending.url, { method: "POST", headers: headers(pending.config, true), body: JSON.stringify({ started: id }) });
+          if (response.ok) { pending.confirmed = true; break; }
+          if (response.status === 401 || response.status === 403) break;
+        } catch (_) {}
+      }
+      if (!pending.confirmed) {
+        pending.aborted = true;
+        await $.turn.abort({ turnId: e.turnId });
+      }
+      break;
+    }
+    return next(e);
+  });
+  on("tool.call", { tool: "mcp__superd-hub__superd-hub" }, async ($, e) => {
+    try {
+      const { config, addressed } = await connection($);
+      const { tool, tool_use_id, agentId, consent, ...args } = e;
+      const response = await $.http.fetch(config.url, { method: "POST", headers: headers(config, addressed), body: JSON.stringify(args) });
+      const envelope = JSON.parse(response.text);
+      return { result: JSON.stringify(envelope.error ? { error: envelope.error } : envelope.result) };
+    } catch (error) {
+      return { result: JSON.stringify({ error: "[E_HUB_UNAVAILABLE] " + String(error) + ". Open or resume this conversation through Super D." }) };
+    }
+  });
+}
+`;
+export async function refreshClaudeNativeEndpoint(endpoint, nativeHome) {
+    await serialized(nativeHome, async () => {
+        const directory = join(nativeHome, 'plugins', 'superd-hub');
+        if (await readFile(join(directory, '.superd-owner'), 'utf8').catch(() => '') !== owner)
+            return;
+        const config = JSON.parse(await readFile(join(directory, 'connection.json'), 'utf8'));
+        const url = await endpoint();
+        if (url !== undefined)
+            await atomicWrite(join(directory, 'connection.json'), JSON.stringify({ url, definition: config.definition }) + '\n');
+    });
+}
+/** Incrementally enable our owned native plugin; never persist a session capability. */
+export async function prepareClaudeNativePlugin(binding, nativeHome) {
+    const transport = await binding.transport();
+    if (transport === undefined)
+        return undefined;
+    return serialized(nativeHome, async () => {
+        const directory = join(nativeHome, 'plugins', 'superd-hub');
+        const entries = await readdir(directory).catch(error => {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return [];
+        });
+        if (entries.length > 0 && await readFile(join(directory, '.superd-owner'), 'utf8').catch(() => '') !== owner) {
+            throw new Error(`Refusing to overwrite unowned native plugin directory: ${directory}`);
+        }
+        const settingsPath = join(nativeHome, 'settings.json');
+        const settings = JSON.parse(await readFile(settingsPath, 'utf8').catch(error => {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return '{}';
+        }));
+        const paths = (settings.env?.['CLAUDE_CODE_PLUGIN_DIRS'] ?? '').split(delimiter).filter(Boolean);
+        if (!paths.includes(directory))
+            paths.push(directory);
+        await mkdir(join(directory, '.claude-plugin'), { recursive: true, mode: 0o700 });
+        await mkdir(join(directory, 'hooks'), { recursive: true, mode: 0o700 });
+        await atomicWrite(join(directory, '.superd-owner'), owner);
+        await atomicWrite(join(directory, 'connection.json'), JSON.stringify({ url: transport.url, definition: transport.definition }) + '\n');
+        await atomicWrite(join(directory, '.claude-plugin', 'plugin.json'), JSON.stringify({ name: 'superd-hub', version: '1.0.0', description: 'Substrate Hub facility for Super D conversations' }) + '\n');
+        await atomicWrite(join(directory, 'hooks', 'hooks.json'), JSON.stringify({ modules: ['./register.js'] }) + '\n');
+        await atomicWrite(join(directory, 'hooks', 'register.js'), moduleSource);
+        settings.env = { ...settings.env, CLAUDE_CODE_PLUGIN_DIRS: paths.join(delimiter) };
+        await atomicWrite(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        return JSON.stringify(transport);
+    });
+}

package/superd-hub/dist/foreign-extension.d.ts

@@ -0,0 +1,10 @@
+/** Shared Pi / OMP native extension. No runtime imports or ambient home changes. */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export interface ForeignExtensionConfig {
+    url: string;
+    token: string;
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export declare function createForeignExtension(config: ForeignExtensionConfig): (api: ExtensionAPI) => void;

package/superd-hub/dist/foreign-extension.js

@@ -0,0 +1,27 @@
+export function createForeignExtension(config) {
+    return (api) => {
+        api.registerTool({
+            name: config.name,
+            label: 'Super D Hub',
+            description: config.description,
+            promptSnippet: 'Use the Super D Hub for agent messaging, runtime status, and remote execution.',
+            parameters: config.parameters,
+            async execute(_callId, args, signal) {
+                const response = await fetch(config.url, {
+                    method: 'POST',
+                    headers: { authorization: `Bearer ${config.token}`, 'content-type': 'application/json' },
+                    body: JSON.stringify(args),
+                    ...(signal === undefined ? {} : { signal }),
+                }).catch((error) => {
+                    if (signal?.aborted)
+                        throw error;
+                    throw new Error('[E_HUB_UNAVAILABLE] Super D Hub connection is unavailable. Restart Super D, then resume this conversation to renew its session binding.');
+                });
+                const body = await response.json();
+                if (!response.ok)
+                    throw new Error(body.error ?? `Super D Hub returned HTTP ${response.status}`);
+                return { content: [{ type: 'text', text: JSON.stringify(body.result) }], details: body.result };
+            },
+        });
+    };
+}

package/superd-hub/dist/foreign-hub.d.ts

@@ -0,0 +1,27 @@
+import type { A2aAgentHandle } from './a2a-delivery.js';
+import { type HubToolDeps } from './hub-tool.js';
+export interface ForeignToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ForeignHubBinding {
+    definition(): ForeignToolDefinition | undefined;
+    execute(args: unknown, signal?: AbortSignal): Promise<unknown>;
+    transport(): Promise<ForeignHubTransport | undefined>;
+    enqueue(text: string): Promise<string>;
+    onTurnStarted(listener: (id: string) => void): () => void;
+    extensionPath(): Promise<string | undefined>;
+    dispose(): void;
+}
+export interface ForeignHubTransport {
+    url: string;
+    token: string;
+    definition: ForeignToolDefinition;
+}
+export declare function foreignAgentHandle(home: string, sessionId: string): A2aAgentHandle | undefined;
+/** Register exactly the assembly used by the DSH-native Hub tool. */
+export declare function registerForeignHubHost(home: string, deps: Omit<HubToolDeps, 'initiatorOf'>): () => Promise<void>;
+/** Public native-plugin endpoint; publishing it never grants a caller identity. */
+export declare function foreignHubEndpoint(home: string): Promise<string | undefined>;
+export declare function bindForeignHub(runtime: string, sessionId: string, worldHome: string, getAgent: () => A2aAgentHandle | undefined): ForeignHubBinding;

package/superd-hub/dist/foreign-hub.js

@@ -0,0 +1,243 @@
+/** Session-bound facility bridge. Host-owned transport; drafts perform no I/O. */
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { rmSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { createSuperdHubTool } from './hub-tool.js';
+import { localA2aInitiator } from './a2a-host.js';
+const hosts = new Map();
+// Delivery is a separate in-memory registration: passive resume must be
+// reachable before runtime/tool materialization, without minting capabilities.
+const deliveryBindings = new Map();
+export function foreignAgentHandle(home, sessionId) {
+    const key = resolve(home);
+    if (!hosts.has(key))
+        return undefined;
+    for (const session of deliveryBindings.values()) {
+        if (session.home === key && session.sessionId === sessionId)
+            return session.getAgent();
+    }
+    return undefined;
+}
+/** Register exactly the assembly used by the DSH-native Hub tool. */
+export function registerForeignHubHost(home, deps) {
+    const key = resolve(home);
+    const host = { home: key, deps, sessions: new Map(), closed: false };
+    hosts.set(key, host);
+    return async () => {
+        host.closed = true;
+        host.sessions.clear();
+        if (hosts.get(key) === host)
+            hosts.delete(key);
+        if (host.server !== undefined) {
+            host.server.closeAllConnections();
+            await new Promise((done) => host.server.close(() => done()));
+        }
+    };
+}
+async function listen(host) {
+    if (host.closed)
+        throw new Error('[E_HUB_CLOSED] Super D Hub binding is closed');
+    if (host.listening !== undefined)
+        return host.listening;
+    const server = createServer(async (request, response) => {
+        const send = (status, body) => {
+            response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+            response.end(JSON.stringify(body));
+        };
+        const token = request.headers.authorization?.replace(/^Bearer /, '');
+        if (token === undefined) {
+            send(403, { error: '[E_HUB_ADDRESS_REQUIRED] This native session has no Substrate Hub address. Open or resume the conversation through Super D; a plugin alone does not register a mailbox.' });
+            return;
+        }
+        const bound = token === undefined ? undefined : host.sessions.get(token);
+        if (host.closed || bound === undefined) {
+            send(401, { error: '[E_HUB_BINDING] Unknown or expired Super D Hub session binding' });
+            return;
+        }
+        if (request.method === 'GET' && request.url === '/inbox') {
+            send(200, { message: bound.inbox[0] ?? null });
+            return;
+        }
+        if (request.method !== 'POST' || !['/tool', '/inbox'].includes(request.url ?? '')) {
+            send(405, { error: 'Use POST /tool, GET /inbox or POST /inbox' });
+            return;
+        }
+        const controller = new AbortController();
+        response.on('close', () => { if (!response.writableEnded)
+            controller.abort(); });
+        try {
+            let body = '';
+            for await (const chunk of request) {
+                body += chunk.toString();
+                if (Buffer.byteLength(body) > 65_536) {
+                    send(413, { error: 'Super D Hub arguments exceed 64 KiB' });
+                    return;
+                }
+            }
+            const args = JSON.parse(body);
+            if (request.url === '/inbox') {
+                if (typeof args?.started === 'string') {
+                    if (!bound.unstarted.has(args.started) && !bound.started.has(args.started)) {
+                        send(409, { error: '[E_HUB_INBOX_START] Unknown message' });
+                        return;
+                    }
+                    if (bound.unstarted.has(args.started)) {
+                        bound.onTurnStarted(args.started);
+                        bound.unstarted.delete(args.started);
+                        bound.started.add(args.started);
+                        if (bound.started.size > 128)
+                            bound.started.delete(bound.started.values().next().value);
+                    }
+                    send(200, { started: true });
+                    return;
+                }
+                if (typeof args?.ack !== 'string' || args.ack !== bound.inbox[0]?.id) {
+                    send(409, { error: '[E_HUB_INBOX_ACK] Message is not the current inbox item' });
+                    return;
+                }
+                bound.inbox.shift();
+                send(200, { acknowledged: true });
+            }
+            else
+                send(200, { result: await bound.execute(args, controller.signal) });
+        }
+        catch (error) {
+            if (!response.writableEnded)
+                send(400, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    host.server = server;
+    host.listening = new Promise((accept, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (address === null || typeof address === 'string') {
+                reject(new Error('Super D Hub loopback listener has no address'));
+                return;
+            }
+            server.unref();
+            accept(`http://127.0.0.1:${address.port}/tool`);
+        });
+    });
+    return host.listening;
+}
+/** Public native-plugin endpoint; publishing it never grants a caller identity. */
+export async function foreignHubEndpoint(home) {
+    const host = hosts.get(resolve(home));
+    return host === undefined || host.closed ? undefined : listen(host);
+}
+export function bindForeignHub(runtime, sessionId, worldHome, getAgent) {
+    const home = resolve(worldHome);
+    const hostHome = dirname(home).endsWith('/agents') ? dirname(dirname(home)) : home;
+    const deliveryKey = Symbol('foreign-hub-delivery');
+    deliveryBindings.set(deliveryKey, { home: hostHome, sessionId, getAgent });
+    let attached;
+    let tool;
+    let token;
+    let path;
+    let preparing;
+    let disposed = false;
+    const inbox = [];
+    const unstarted = new Set();
+    const started = new Set();
+    const turnListeners = new Set();
+    const attach = () => {
+        if (disposed)
+            throw new Error('[E_HUB_BINDING] Super D Hub session binding is closed');
+        const host = hosts.get(hostHome);
+        if (host === undefined || host.closed)
+            return undefined;
+        if (attached !== host) {
+            if (attached !== undefined && token !== undefined)
+                attached.sessions.delete(token);
+            attached = host;
+            token = randomUUID();
+            tool = createSuperdHubTool({ ...host.deps, initiatorOf: () => localA2aInitiator(host.home, runtime, sessionId) });
+            host.sessions.set(token, { runtime, sessionId, getAgent, execute: binding.execute, inbox, unstarted, started, onTurnStarted: id => { for (const listener of turnListeners)
+                    listener(id); } });
+        }
+        return tool;
+    };
+    const binding = {
+        definition() {
+            const current = attach();
+            return current === undefined ? undefined : { name: current.name, description: current.description, inputSchema: current.parameters };
+        },
+        async execute(args, signal = new AbortController().signal) {
+            const current = attach();
+            if (current === undefined)
+                throw new Error('[E_HUB_UNAVAILABLE] Super D Hub is not running for this session; reconnect through Super D');
+            // A host tool context, with identity supplied by the binding rather than model arguments.
+            const exec = {
+                callId: randomUUID(), rootCallId: randomUUID(), name: current.name, arguments: args,
+                agent: { id: sessionId }, signal, token: Symbol('foreign-hub-call'),
+                deferContext() { }, concludeTurn() { },
+            };
+            return current.execute(args, exec);
+        },
+        async transport() {
+            const definition = binding.definition();
+            if (definition === undefined)
+                return undefined;
+            const host = attached;
+            const capability = token;
+            const url = await listen(host);
+            if (disposed)
+                throw new Error('[E_HUB_BINDING] Super D Hub session binding is closed');
+            return { url, token: capability, definition };
+        },
+        async enqueue(text) {
+            if (attach() === undefined)
+                throw new Error('[E_HUB_UNAVAILABLE] Super D Hub is not running for this session');
+            if (Buffer.byteLength(text) > 65_536 || inbox.length >= 128 || unstarted.size >= 128)
+                throw new Error('[E_HUB_INBOX_FULL] Hub inbox is full or the message exceeds 64 KiB');
+            const id = randomUUID();
+            unstarted.add(id);
+            inbox.push({ id, text });
+            return id;
+        },
+        onTurnStarted(listener) { turnListeners.add(listener); return () => turnListeners.delete(listener); },
+        async extensionPath() {
+            if (preparing !== undefined)
+                return preparing;
+            const definition = binding.definition();
+            if (definition === undefined)
+                return undefined;
+            const host = attached;
+            const capability = token;
+            preparing = (async () => {
+                const url = await listen(host);
+                if (disposed)
+                    throw new Error('[E_HUB_BINDING] Super D Hub session binding is closed');
+                const directory = join(home, 'hub-extensions');
+                await mkdir(directory, { recursive: true, mode: 0o700 });
+                const wrapper = join(directory, `${capability}.mjs`);
+                const config = { url, token: capability, name: definition.name, description: definition.description, parameters: definition.inputSchema };
+                const entry = new URL('./foreign-extension.js', import.meta.url).href;
+                await writeFile(wrapper, `import { createForeignExtension } from ${JSON.stringify(entry)};\nexport default createForeignExtension(${JSON.stringify(config)});\n`, { mode: 0o600 });
+                if (disposed) {
+                    rmSync(wrapper, { force: true });
+                    throw new Error('[E_HUB_BINDING] Super D Hub session binding is closed');
+                }
+                path = wrapper;
+                return wrapper;
+            })();
+            return preparing;
+        },
+        dispose() {
+            disposed = true;
+            inbox.length = 0;
+            unstarted.clear();
+            started.clear();
+            turnListeners.clear();
+            deliveryBindings.delete(deliveryKey);
+            if (attached !== undefined && token !== undefined)
+                attached.sessions.delete(token);
+            if (path !== undefined)
+                rmSync(path, { force: true });
+        },
+    };
+    return binding;
+}

package/superd-hub/dist/foreign-native.d.ts

@@ -0,0 +1,4 @@
+import type { ForeignHubBinding } from './foreign-hub.js';
+/** Called by the Hub host at mount, independently of any agent/tool use. */
+export declare function refreshHermesNativeEndpoint(endpoint: () => Promise<string | undefined>, nativeHome: string): Promise<void>;
+export declare function prepareHermesNativePlugin(binding: Pick<ForeignHubBinding, 'transport'>, nativeHome: string, enable: (key: string) => Promise<unknown>): Promise<string | undefined>;