@xiashe/sdk 0.1.34 → 0.1.35-superconnector.2

package/README.md

@@ -11,3 +11,31 @@ The SDK wraps:
 - Unified file upload/listing.
 
 It stores local CLI state in `~/.xiashe/config.json` by default.
+
+## Superconnector runtime preview
+
+Version `0.1.35-superconnector.1` adds user-owned non-OAuth credential connection APIs alongside existing OAuth connections, explicit action grants, immutable runtime releases, verified installation, foreground Agent/script execution, remote hosts and result-only recovery. SaaS credentials remain in the platform gateway.
+
+Runtime exports include `installRuntimePackage`, `runRuntimeScript`, `createRuntimeAgentSession`, `createRuntimeAgentHost`, `serveRuntimeScriptHost`, `serveRuntimeMcp`, `retryRuntimeResults` and `retryRuntimeHostResults`. Script execution requires Docker and a pre-pulled official Node image pinned by SHA-256. Runtime container helper files are included in the package.
+
+This is a local test prerelease. Real non-OAuth staging acceptance and native interaction validation remain release gates for this delivery. See the repository's `docs/superconnector-development.md` for setup and acceptance procedures.
+
+`createRuntimeRelease({ ..., signature })` optionally imports a public BYOA v1 P-256 package proof. The backend verifies every delivered file and preserves existing creator ownership and runtime review. Private signing material is rejected before transmission. Sign the exact filtered package; source-package proofs cannot survive changed files.
+
+Script and hybrid contracts support Node `.mjs` and `.js` entrypoints. The pinned container applies Node module semantics to the exact reviewed package; installation never runs dependency or lifecycle scripts.
+
+Use `listRuntimeReleasePage(registryEntryId, { limit: 20, cursor: null })` for complete creator history. Follow `continueCursor` until `isDone`; each page supports 1–50 entries. The older `listRuntimeReleases` array response remains capped at 100.
+
+Optional script `dependencies` declare a Node minimum (`>=18`) and required command names. The pinned container checks these before package code starts, without running probe commands or installing packages.
+
+For an operator-enabled public action, use `grantConnector({ publicAccess: true, actionIds, purpose, releaseId })`. Omit `connectionId`: public grants cannot carry account credentials and still require explicit consent, expiration and the reviewed release scope.
+
+## Non-OAuth API surface
+
+- `getSaasCredentialSetup(provider)` returns sanitized form metadata and the credential submission endpoint.
+- `connectSaasCredentials(provider, { authType, values, requestKey, replaceConnectionId? })` submits API Key or custom credential fields over the dedicated authenticated HTTP route. It does not retry uncertain submissions.
+- `getSaasCredentialStatus(requestKey)` checks only the signed-in user's request; `disconnectSaas(connectionId)` revokes access and schedules upstream deletion.
+- `prepareRuntimeRun(releaseId)` returns reviewed requirements and valid saved choices, without granting access.
+- `launchRuntimeRun({ releaseId, input, connections, publicActionIds, creatorServiceIds, requestKey, targetAgentConnectionId, executionMode? })` validates and grants the explicitly confirmed scope, then queues execution atomically. It stores only declared parameters and connection revisions for this exact release.
+
+Keep `values` out of logs, command arguments, Skill files, runtime inputs and persisted Agent state. A replacement invalidates old approvals; the new connection must be selected and approved again. Creator-provided services use the existing constrained service broker, never transfer the creator's raw credential to a consumer or Agent.

package/container/connector-helper.mjs

@@ -0,0 +1,25 @@
+// Compatibility with BYOA's helper API. No credentials or direct-network fallback.
+import { randomUUID } from 'node:crypto';
+const pending = new Map();
+process.on('message', message => {
+  if (message?.type !== 'action-result') return;
+  const operation = pending.get(message.id);
+  if (!operation) return;
+  pending.delete(message.id);
+  if (pending.size === 0) process.channel?.unref();
+  if (message.error) operation.reject(new Error(message.error));
+  else operation.resolve(message.data);
+});
+process.channel?.unref();
+export function executeAction(actionId, input = {}) {
+  if (!process.send || pending.size >= 8) return Promise.reject(new Error('CONNECTOR_BROKER_UNAVAILABLE'));
+  const id = randomUUID();
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+    process.channel?.ref();
+    process.send({ type: 'action', id, actionId, input });
+  });
+}
+export async function executeActionRaw(actionId, input = {}) {
+  return { success: true, data: await executeAction(actionId, input) };
+}

package/container/driver.mjs

@@ -0,0 +1,50 @@
+// Runs only inside the disposable, network-disabled container.
+import { spawn } from 'node:child_process';
+import { collectOutputs } from './outputs.mjs';
+import readline from 'node:readline';
+import { accessSync, statSync, constants } from 'node:fs';
+const emit = value => process.stdout.write(JSON.stringify(value) + '\n');
+const lines = readline.createInterface({ input: process.stdin });
+let child;
+let initialized = false;
+lines.on('line', line => {
+  try {
+    const message = JSON.parse(line);
+    if (message.type === 'init' && !initialized) {
+      initialized = true;
+      const { entry, input, runId, version, name, maxOutputBytes, outputs: specifications, dependencies } = message;
+      const env = { PATH: '/usr/local/bin:/usr/bin:/bin', HOME: '/work', USERPROFILE: '/work', TMPDIR: '/work', TEMP: '/work', TMP: '/work',
+        PROJECT_DIR: '/work', JOB_ID: runId, WORKER_ID: 'xiashe-container', SKILL_VERSION: version, SKILL_NAME: name,
+        SKILL_PARAMETERS: JSON.stringify(input), USER_INPUT: typeof input === 'string' ? input : typeof input?.userInput === 'string' ? input.userInput : '',
+        CONNECTOR_HELPER_PATH: '/runtime/connector-helper.mjs', SC_BROKER_URL: 'ipc://xiashe' };
+      if (dependencies !== undefined) {
+        if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies) ||
+            Object.keys(dependencies).some(key => !['node', 'commands'].includes(key)) ||
+            dependencies.node !== undefined && (typeof dependencies.node !== 'string' || !/^>=\d{1,6}$/.test(dependencies.node)) ||
+            dependencies.commands !== undefined && (!Array.isArray(dependencies.commands) || dependencies.commands.length > 20 || dependencies.commands.some(command => typeof command !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(command)))) throw new Error('INVALID_RUNTIME_DEPENDENCIES');
+        if (dependencies.node && Number(process.versions.node.split('.')[0]) < Number(dependencies.node.slice(2))) throw new Error('NODE_REQUIREMENT_NOT_MET');
+        for (const command of dependencies.commands ?? []) {
+          const found = env.PATH.split(':').some(directory => {
+            try { const file = directory + '/' + command; accessSync(file, constants.X_OK); return statSync(file).isFile(); }
+            catch { return false; }
+          });
+          if (!found) throw new Error('COMMAND_REQUIREMENT_NOT_MET');
+        }
+      }
+      child = spawn(process.execPath, ['/package/' + entry], { cwd: '/work', env, stdio: ['ignore', 'pipe', 'pipe', 'ipc'] });
+      child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
+      child.stdout.on('data', data => emit({ type: 'log', stream: 'stdout', text: data.toString('utf8') }));
+      child.stderr.on('data', data => emit({ type: 'log', stream: 'stderr', text: data.toString('utf8') }));
+      child.on('message', value => emit(value));
+      child.on('error', () => { emit({ type: 'error', code: 'SCRIPT_START_FAILED' }); process.exitCode = 1; lines.close(); process.stdin.destroy(); });
+      child.on('close', async code => {
+        try {
+          if (code !== 0) throw new Error('SCRIPT_EXIT_FAILED');
+          const result = await collectOutputs(specifications, maxOutputBytes);
+          emit({ type: 'result', result });
+        } catch (error) { emit({ type: 'error', code: error.message }); process.exitCode = 1; }
+        lines.close(); process.stdin.destroy();
+      });
+    } else if (message.type === 'action-result' && child?.connected) child.send(message);
+  } catch (error) { emit({ type: 'error', code: ['INVALID_RUNTIME_DEPENDENCIES', 'NODE_REQUIREMENT_NOT_MET', 'COMMAND_REQUIREMENT_NOT_MET'].includes(error.message) ? error.message : 'BROKER_PROTOCOL_ERROR' }); process.exitCode = 1; lines.close(); process.stdin.destroy(); }
+});

package/container/outputs.mjs

@@ -0,0 +1,78 @@
+import { constants } from 'node:fs';
+import { lstat, open, readdir, realpath } from 'node:fs/promises';
+
+const safePath = value => typeof value === 'string' && value.length <= 240 && !/[\\\u0000-\u001f]/.test(value) && !/^[A-Za-z]:/.test(value) &&
+  value.split('/').every(part => part && part !== '.' && part !== '..');
+
+/** Linux container only: inspect the opened descriptor, then perform bounded reads. */
+export async function collectOutputs(specifications, maxOutputBytes) {
+  let size = 0, count = 0;
+  async function read(relative, required = true) {
+    if (!safePath(relative)) throw new Error('OUTPUT_UNSAFE_FILE');
+    const parts = relative.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      const stat = await lstat('/work/' + parts.slice(0, i).join('/')).catch(error => {
+        if (error.code === 'ENOENT') { if (!required) return null; throw new Error('OUTPUT_MISSING'); }
+        throw new Error('OUTPUT_UNSAFE_FILE');
+      });
+      if (!stat) return null;
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('OUTPUT_UNSAFE_FILE');
+    }
+    const handle = await open('/work/' + relative, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch(error => {
+      if (error.code === 'ENOENT') { if (!required) return null; throw new Error('OUTPUT_MISSING'); }
+      throw new Error('OUTPUT_UNSAFE_FILE');
+    });
+    if (!handle) return null;
+    try {
+      const actual = await realpath('/proc/self/fd/' + handle.fd);
+      const stat = await handle.stat();
+      if (!actual.startsWith('/work/') || !stat.isFile() || stat.nlink !== 1) throw new Error('OUTPUT_UNSAFE_FILE');
+      if (++count > 100 || stat.size > maxOutputBytes - size) throw new Error('OUTPUT_LIMIT');
+      const bytes = Buffer.alloc(maxOutputBytes - size + 1);
+      let length = 0;
+      while (length < bytes.length) {
+        const { bytesRead } = await handle.read(bytes, length, bytes.length - length, null);
+        if (!bytesRead) break;
+        length += bytesRead;
+      }
+      size += length;
+      if (size > maxOutputBytes) throw new Error('OUTPUT_LIMIT');
+      return bytes.subarray(0, length);
+    } finally { await handle.close(); }
+  }
+  let outputs;
+  if (specifications === undefined) {
+    outputs = [];
+    const walk = async (directory, prefix = '') => {
+      for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const relative = prefix + entry.name;
+        if (entry.isDirectory()) {
+          if (relative.split('/').length > 10) throw new Error('OUTPUT_LIMIT');
+          await walk(directory + '/' + entry.name, relative + '/');
+        } else {
+          const bytes = await read(relative);
+          outputs.push({ path: relative, encoding: 'base64', content: bytes.toString('base64') });
+        }
+      }
+    };
+    await walk('/work');
+  } else {
+    if (!specifications || typeof specifications !== 'object' || Array.isArray(specifications) || Object.keys(specifications).length > 100) throw new Error('INVALID_RUNTIME_OUTPUTS');
+    outputs = {};
+    for (const [name, spec] of Object.entries(specifications)) {
+      if (!name.trim() || name.length > 128 || /[\u0000-\u001f]/.test(name) || ['constructor', 'prototype', '__proto__'].includes(name) || !spec || !['text', 'markdown', 'json', 'file'].includes(spec.type)) throw new Error('INVALID_RUNTIME_OUTPUTS');
+      const bytes = await read(spec.path, spec.required !== false);
+      if (!bytes) continue;
+      let content;
+      if (spec.type !== 'file') {
+        try { content = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('OUTPUT_INVALID_TEXT'); }
+        if (spec.type === 'json') { try { JSON.parse(content); } catch { throw new Error('OUTPUT_INVALID_JSON'); } }
+      }
+      outputs[name] = { type: spec.type, path: spec.path, sizeBytes: bytes.length,
+        ...(spec.type === 'file' ? { encoding: 'base64', content: bytes.toString('base64') } : { content }) };
+    }
+  }
+  const result = { outputs };
+  if (Buffer.byteLength(JSON.stringify(result)) > maxOutputBytes) throw new Error('OUTPUT_LIMIT');
+  return result;
+}

package/index.mjs

@@ -5,8 +5,16 @@ import os from 'node:os';
 import path from 'node:path';
 import { ConvexHttpClient } from 'convex/browser';
 import { anyApi as api } from 'convex/server';
+export { installRuntimePackage, runtimePrincipal, writeRuntimeRecord } from './runtime.mjs';
+export { reportRuntimeResult, retryRuntimeResults } from './runtimeOutbox.mjs';
+export { runRuntimeScript } from './runtimeScript.mjs';
+export { serveRuntimeScriptHost, retryRuntimeHostResults } from './runtimeHost.mjs';
+export { createRuntimeAgentHost } from './runtimeAgentHost.mjs';
+export { createRuntimeAgentSession } from './runtimeAgent.mjs';
+export { serveRuntimeMcp } from './runtimeMcp.mjs';
 
-export const VERSION = '0.1.34';
+export const VERSION = '0.1.35-superconnector.2';
+export { probeRuntimeGateway, runtimeSetupTemplate } from './runtimeSetup.mjs';
 
 export const DEFAULTS = {
   cn: {
@@ -226,6 +234,11 @@ function envProfile(profile) {
 
 function normalizeConvexError(error) {
   const message = error instanceof Error ? error.message : String(error || '');
+  // Convex validation errors embed the full submitted object, including session tokens.
+  // Never attach the original exception/stack as details for these errors.
+  if (/ArgumentValidationError/.test(message)) {
+    return new XiasheError('The server rejected the request arguments.', { code: 'CONVEX_INVALID_ARGUMENTS' });
+  }
   if (/fetch failed|failed to fetch|network request failed|econnrefused|enotfound|eai_again/i.test(message)) {
   return new XiasheError('Unable to reach Convex deployment.', {
       code: 'CONVEX_NETWORK_UNAVAILABLE',
@@ -443,6 +456,291 @@ export class XiasheClient {
     return this.query(api.connections.listForUser, this.authArgs());
   }
 
+  async listSaasProviders() {
+    return this.query(api.saasConnections.providers, this.authArgs());
+  }
+
+  async listSaasConnections() {
+    return this.query(api.saasConnections.list, this.authArgs());
+  }
+  async getSaasCredentialSetup(provider) {
+    return this.action(api.saasConnections.credentialSetupForProvider, this.authArgs({ provider }));
+  }
+
+  async getSaasCredentialStatus(requestKey) {
+    return this.query(api.saasConnections.credentialConnectionStatus, this.authArgs({ requestKey }));
+  }
+
+  async connectSaasCredentials(provider, { authType, values, requestKey, replaceConnectionId } = {}) {
+    if (!requestKey || !['api_key', 'custom_credential'].includes(authType) || !values || typeof values !== 'object' || Array.isArray(values))
+      throw new XiasheError('Provide credential values, auth type and a stable request key.', { code: 'INVALID_CONNECTION_REQUEST' });
+    const setup = await this.getSaasCredentialSetup(provider);
+    if (!setup.submissionEndpoint) throw new XiasheError('Credential endpoint is not configured.', { code: 'CONNECTION_SETUP_UNAVAILABLE' });
+    const url = new URL(setup.submissionEndpoint);
+    const rpc = new URL(this.profile.convexUrl);
+    const local = ['localhost', '127.0.0.1', '[::1]'];
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/superconnector/connections/credentials' ||
+        url.protocol !== 'https:' && !(url.protocol === 'http:' && local.includes(url.hostname) && local.includes(rpc.hostname)))
+      throw new XiasheError('Invalid credential endpoint.', { code: 'CONNECTION_SETUP_UNAVAILABLE' });
+    const body = JSON.stringify(this.authArgs({ provider, authType, values, requestKey, ...(replaceConnectionId ? { replaceConnectionId } : {}) }));
+    if (Buffer.byteLength(body) > 65536) throw new XiasheError('Credential input is too large.', { code: 'INVALID_CONNECTION_REQUEST' });
+    let response;
+    try {
+      response = await fetch(url, { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(60000),
+        headers: { 'content-type': 'application/json' }, body });
+    } catch {
+      throw new XiasheError('Connection result is unconfirmed. Check status with the same request key; do not create a new request.', { code: 'CONNECTION_RESULT_UNCONFIRMED' });
+    }
+    let result;
+    try { result = await response.json(); } catch {
+      throw new XiasheError('Connection result is unconfirmed. Check request status.', { code: 'CONNECTION_RESULT_UNCONFIRMED' });
+    }
+    if (!response.ok || !['CONNECTED', 'CONNECTION_REQUEST_EXISTS'].includes(result.code) || typeof result.connectionId !== 'string')
+      throw new XiasheError('Connection was not confirmed. Check request status before retrying.', { code: 'CONNECTION_NOT_CONFIRMED' });
+    return { connectionId: result.connectionId, requestKey };
+  }
+  async listSaasAuthorizationRequests() {
+    return this.query(api.saasConnections.requests, this.authArgs());
+  }
+
+  async connectSaas(provider, requestKey = createIdempotencyKey(), { authorizationOptionIds = [], reauthorizeConnectionId } = {}) {
+    return this.action(api.saasConnections.start, this.authArgs({ provider, requestKey, authorizationOptionIds,
+      ...(reauthorizeConnectionId ? { reauthorizeConnectionId } : {}) }));
+  }
+
+  async reauthorizeSaas(connectionId, { authorizationOptionIds = [], requestKey = createIdempotencyKey() } = {}) {
+    const connection = (await this.listSaasConnections()).find(row => row.id === connectionId);
+    if (!connection) throw new XiasheError('Connection not found.', { code: 'CONNECTION_NOT_FOUND' });
+    return this.connectSaas(connection.provider, requestKey, { authorizationOptionIds, reauthorizeConnectionId: connectionId });
+  }
+
+  async pollSaasAuthorization(id) {
+    return this.action(api.saasConnections.poll, this.authArgs({ id }));
+  }
+
+  async cancelSaasAuthorization(id) {
+    return this.mutation(api.saasConnections.cancelAuthorization, this.authArgs({ id }));
+  }
+
+  async disconnectSaas(connectionId) {
+    return this.mutation(api.saasConnections.disconnect, this.authArgs({ connectionId }));
+  }
+
+  async listConnectorActions() {
+    return this.query(api.superconnector.actions, this.authArgs());
+  }
+
+  async getConnectorActionDefinition(actionId) {
+    return this.action(api.superconnector.actionDefinition, this.authArgs({ actionId }));
+  }
+
+  async listConnectorGrants() {
+    return this.query(api.superconnector.grants, this.authArgs());
+  }
+
+  async grantConnector({ connectionId, publicAccess, creatorServiceId, actionIds, purpose, duration = 'once', releaseId }) {
+    return this.mutation(api.superconnector.grant, this.authArgs({ ...(creatorServiceId ? { creatorServiceId } : {}), ...(connectionId ? { connectionId } : {}), ...(publicAccess === undefined ? {} : { publicAccess }), actionIds, purpose, duration, ...(releaseId ? { releaseId } : {}) }));
+  }
+
+  async revokeConnectorGrant(grantId) {
+    return this.mutation(api.superconnector.revokeGrant, this.authArgs({ grantId }));
+  }
+
+  // Callers must persist requestKey before dispatch and reuse it on transport retries.
+  async executeConnector({ grantId, actionId, input = {}, requestKey, parentRunId, leaseToken }) {
+    if (typeof requestKey !== 'string' || !requestKey.trim()) throw new XiasheError('A stable requestKey is required.', { code: 'INVALID_INPUT' });
+    return this.mutation(api.superconnector.execute, this.authArgs({ grantId, actionId, inputJson: JSON.stringify(input), requestKey,
+      ...(parentRunId ? { parentRunId, leaseToken } : {}) }));
+  }
+
+  async listSkillRuns() {
+    return this.query(api.superconnector.listRuns, this.authArgs());
+  }
+
+  async getSkillRun(runId) {
+    return this.query(api.superconnector.getRun, this.authArgs({ runId }));
+  }
+
+  async cancelSkillRun(runId) {
+    return this.mutation(api.superconnector.cancel, this.authArgs({ runId }));
+  }
+
+  async listCreatorServices(releaseId) {
+    return this.query(api.skillRuntimeReleases.services, this.authArgs({ releaseId }));
+  }
+
+  async createCreatorService({ policy, ...options }) {
+    return this.mutation(api.skillRuntimeReleases.createService, this.authArgs({ ...options, policyJson: JSON.stringify(policy) }));
+  }
+
+  async revokeCreatorService(serviceId) {
+    return this.mutation(api.skillRuntimeReleases.revokeService, this.authArgs({ serviceId }));
+  }
+
+  async getCreatorServiceDefinition(serviceId) {
+    return this.query(api.superconnector.serviceDefinition, this.authArgs({ serviceId }));
+  }
+
+  async listRuntimeReleases(registryEntryId) {
+    return this.query(api.skillRuntimeReleases.list, this.authArgs({ registryEntryId }));
+  }
+
+  async listRuntimeReleasePage(registryEntryId, { cursor = null, limit = 20 } = {}) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50 || cursor !== null && typeof cursor !== 'string')
+      throw new XiasheError('Use a page size from 1 to 50 and a returned cursor.', { code: 'INPUT_LIMIT' });
+    return this.query(api.skillRuntimeReleases.listPage, this.authArgs({ registryEntryId, paginationOpts: { numItems: limit, cursor } }));
+  }
+
+  async createRuntimeRelease({ registryEntryId, artifactId, version, contract, signature }) {
+    if (signature !== undefined) {
+      try {
+        const allowed = ['algorithm', 'keyId', 'publicJwk', 'signature', 'signedAt', 'manifest', 'packageHash', 'fileCount'];
+        const publicKey = JSON.parse(signature.publicJwk);
+        if (Object.keys(signature).some(key => !allowed.includes(key)) || Object.keys(publicKey).some(key => !['kty', 'crv', 'x', 'y', 'ext', 'key_ops', 'alg', 'use'].includes(key)) || Buffer.byteLength(JSON.stringify(signature)) > 200000) throw new Error();
+      } catch { throw new XiasheError('Provide a public signature envelope without private keys.', { code: 'INVALID_RUNTIME_SIGNATURE' }); }
+    }
+    return this.mutation(api.skillRuntimeReleases.create, this.authArgs({ registryEntryId, artifactId, version, contractJson: JSON.stringify(contract), ...(signature === undefined ? {} : { signatureJson: JSON.stringify(signature) }) }));
+  }
+
+  async createConfiguredRuntimeRelease({ registryEntryId, artifactId, version, accountSource, contract, services }) {
+    return this.mutation(api.skillRuntimeReleases.createConfigured, this.authArgs({ registryEntryId, artifactId, version, ...(accountSource ? { accountSource } : {}),
+      contractJson: JSON.stringify(contract), services: services.map(({ policy, ...service }) => ({ ...service, policyJson: JSON.stringify(policy) })) }));
+  }
+
+  async getRuntimeRelease(releaseId) {
+    return this.query(api.skillRuntimeReleases.get, this.authArgs({ releaseId }));
+  }
+
+  async downloadRuntimePackage(releaseId) {
+    const release = await this.getRuntimeRelease(releaseId);
+    return this.downloadVerifiedRuntimePackage(release, this.authArgs({ releaseId: release.id }));
+  }
+
+  async downloadVerifiedRuntimePackage(release, credentials) {
+    if (!release?.packageEndpoint) throw new XiasheError('Runtime package endpoint is not configured.', { code: 'RUNTIME_PACKAGE_UNAVAILABLE' });
+    const url = new URL(release.packageEndpoint);
+    const rpc = new URL(this.profile.convexUrl);
+    const local = ['localhost', '127.0.0.1', '[::1]'];
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/superconnector/package' ||
+        url.protocol !== 'https:' && !(url.protocol === 'http:' && local.includes(url.hostname) && local.includes(rpc.hostname)))
+      throw new XiasheError('Invalid runtime package endpoint.', { code: 'RUNTIME_PACKAGE_UNAVAILABLE' });
+    const response = await fetch(url, { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(60000),
+      headers: { 'content-type': 'application/json' }, body: JSON.stringify(credentials) });
+    if (!response.ok || !response.body || response.headers.get('x-artifact-sha256') !== release.artifactSha256)
+      throw new XiasheError('Runtime package download failed.', { code: 'RUNTIME_PACKAGE_UNAVAILABLE' });
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of response.body) {
+      size += chunk.byteLength;
+      if (size > 100 * 1024 * 1024) throw new XiasheError('Package is too large.', { code: 'PACKAGE_LIMIT' });
+      chunks.push(chunk);
+    }
+    const bytes = Buffer.concat(chunks);
+    if (createHash('sha256').update(bytes).digest('hex') !== release.artifactSha256)
+      throw new XiasheError('Package checksum mismatch.', { code: 'PACKAGE_CHECKSUM_MISMATCH' });
+    return { release, bytes };
+  }
+
+  async prepareRuntimeRun(releaseId) {
+    return this.query(api.runtimeLaunch.preparation, this.authArgs({ releaseId }));
+  }
+
+  async launchRuntimeRun({ releaseId, input = {}, connections = [], publicActionIds = [], creatorServiceIds = [], requestKey, targetAgentConnectionId, executionMode }) {
+    if (!requestKey || !targetAgentConnectionId) throw new XiasheError('A stable request key and host are required.', { code: 'INVALID_INPUT' });
+    return this.mutation(api.runtimeLaunch.start, this.authArgs({ releaseId, inputJson: JSON.stringify(input), connections, publicActionIds, creatorServiceIds, requestKey, targetAgentConnectionId,
+      ...(executionMode ? { executionMode } : {}) }));
+  }
+
+  async startRuntimeRun({ releaseId, input = {}, grantIds = [], requestKey, targetAgentConnectionId, executionMode }) {
+    if (!requestKey) throw new XiasheError('A stable requestKey is required.', { code: 'INVALID_INPUT' });
+    return this.mutation(api.skillRuntimeRuns.start, this.authArgs({ releaseId, inputJson: JSON.stringify(input), grantIds, requestKey,
+      ...(targetAgentConnectionId ? { targetAgentConnectionId } : {}), ...(executionMode ? { executionMode } : {}) }));
+  }
+
+  async listRuntimeHosts() {
+    return this.query(api.runtimeHosts.list, this.authArgs());
+  }
+
+  runtimeHostAuth(extra = {}) {
+    const runtimeToken = this.profile.agent?.runtimeToken;
+    if (!runtimeToken) throw new XiasheError('Connect this Agent before starting a remote executor.', { code: 'HOST_AUTH_REQUIRED' });
+    return { ...extra, runtimeToken };
+  }
+
+  async announceRuntimeHost({ hostLeaseToken, modes }) {
+    return this.mutation(api.runtimeHosts.announce, this.runtimeHostAuth({ hostLeaseToken, modes }));
+  }
+
+  async runtimeHostIdentity() {
+    return this.mutation(api.runtimeHosts.identity, this.runtimeHostAuth());
+  }
+
+  async stopRuntimeHost(hostLeaseToken) {
+    return this.mutation(api.runtimeHosts.stop, this.runtimeHostAuth({ hostLeaseToken }));
+  }
+
+  async pendingRuntimeHostRuns(hostLeaseToken) {
+    return this.mutation(api.runtimeHosts.pending, this.runtimeHostAuth({ hostLeaseToken }));
+  }
+
+  async claimRuntimeHostRun({ hostLeaseToken, runId, leaseToken }) {
+    return this.mutation(api.runtimeHosts.claim, this.runtimeHostAuth({ hostLeaseToken, runId, leaseToken }));
+  }
+
+  async heartbeatRuntimeHostRun({ hostLeaseToken, runId, leaseToken, progressPercent, message }) {
+    return this.mutation(api.runtimeHosts.heartbeatRun, this.runtimeHostAuth({ hostLeaseToken, runId, leaseToken,
+      ...(progressPercent === undefined ? {} : { progressPercent }), ...(message === undefined ? {} : { message }) }));
+  }
+
+  async finishRuntimeHostRun({ runId, leaseToken, eventId, status, resultJson }) {
+    return this.mutation(api.runtimeHosts.finishRun, this.runtimeHostAuth({ runId, leaseToken, eventId, status, resultJson }));
+  }
+
+  async runtimeHostRunStatus(runId) {
+    return this.mutation(api.runtimeHosts.status, this.runtimeHostAuth({ runId }));
+  }
+
+  async runtimeHostRunContext({ hostLeaseToken, runId, leaseToken }) {
+    return this.mutation(api.runtimeHosts.context, this.runtimeHostAuth({ hostLeaseToken, runId, leaseToken }));
+  }
+
+  async downloadRuntimeHostPackage({ hostLeaseToken, runId, leaseToken }) {
+    const context = await this.runtimeHostRunContext({ hostLeaseToken, runId, leaseToken });
+    const downloaded = await this.downloadVerifiedRuntimePackage(context.release,
+      this.runtimeHostAuth({ remote: true, hostLeaseToken, runId, leaseToken }));
+    return { ...downloaded, context };
+  }
+
+  async executeRuntimeHostAction({ hostLeaseToken, runId, leaseToken, actionId, input = {}, requestKey }) {
+    return this.mutation(api.runtimeHosts.execute, this.runtimeHostAuth({ hostLeaseToken, runId, leaseToken,
+      actionId, inputJson: JSON.stringify(input), requestKey }));
+  }
+
+  async runtimeHostActionDefinition({ hostLeaseToken, runId, leaseToken, actionId }) {
+    return this.action(api.runtimeHosts.actionDefinition, this.runtimeHostAuth({ hostLeaseToken, runId, leaseToken, actionId }));
+  }
+
+  async runtimeHostActionStatus({ runId, actionRunId }) {
+    return this.mutation(api.runtimeHosts.actionStatus, this.runtimeHostAuth({ runId, actionRunId }));
+  }
+
+  async cancelRuntimeHostRun({ hostLeaseToken, runId, leaseToken }) {
+    return this.mutation(api.runtimeHosts.cancelRun, this.runtimeHostAuth({ hostLeaseToken, runId, leaseToken }));
+  }
+
+  async claimRuntimeRun({ runId, workerId, leaseToken }) {
+    return this.mutation(api.skillRuntimeRuns.claim, this.authArgs({ runId, workerId, leaseToken }));
+  }
+
+  async heartbeatRuntimeRun({ runId, leaseToken, progressPercent, message }) {
+    return this.mutation(api.skillRuntimeRuns.heartbeat, this.authArgs({ runId, leaseToken,
+      ...(progressPercent === undefined ? {} : { progressPercent }), ...(message === undefined ? {} : { message }) }));
+  }
+
+  async finishRuntimeRun({ runId, leaseToken, eventId, status, resultJson }) {
+    return this.mutation(api.skillRuntimeRuns.finish, this.authArgs({ runId, leaseToken, eventId, status, resultJson }));
+  }
+
   async resolveConnection(selector) {
     const rows = await this.listConnections();
     const needle = String(selector || '').trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/sdk",
-  "version": "0.1.34",
+  "version": "0.1.35-superconnector.2",
   "type": "module",
   "main": "index.mjs",
   "exports": {
@@ -11,5 +11,10 @@
   },
   "engines": {
     "node": ">=20"
-  }
+  },
+  "files": [
+    "*.mjs",
+    "container/*.mjs",
+    "README.md"
+  ]
 }