Skip to content

armgit / ODS

Public Imported from GitHub
0

ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.

16.3 KB
Raw Blame
// Registration composition, not installation authority. The parent launcher must
// qualify the deployment environment, source/runtime bytes and executable paths.
// Never derive executable authority from editable plugin configuration.
import {createManagedProviderBootstrap} from './provider-bootstrap.mjs';
import {createManagedCommandAdmission} from './managed-command-admission.mjs';

export const DEPLOYMENT_ENV = 'PIXEL_ODS_PROVIDER_DEPLOYMENT';
export const requiredManagedHooks = Object.freeze([
  'before_model_resolve', 'before_agent_run', 'agent_end',
  'before_command_run', 'before_tool_call', 'after_tool_call', 'gateway_stop',
]);
const blocked = () => ({outcome: 'block', reason: 'managed-admission-unavailable'});
const unavailable = () => ({providerOverride: 'ods-policy', modelOverride: 'unavailable'});
const error = () => new Error('ODS managed runtime unavailable or cleanup incomplete');
const own = (value, key) => value && Object.hasOwn(value, key);

function canonical(value, depth = 0) {
  if (depth > 32) throw error();
  if (value === null || ['string', 'boolean'].includes(typeof value) ||
      typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
  if (Array.isArray(value)) return '[' + value.map(item => canonical(item, depth + 1)).join(',') + ']';
  if (!value || typeof value !== 'object' ||
      ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw error();
  return '{' + Object.keys(value).sort().map(key => {
    const descriptor = Object.getOwnPropertyDescriptor(value, key);
    if (!descriptor?.enumerable || !('value' in descriptor)) throw error();
    return JSON.stringify(key) + ':' + canonical(descriptor.value, depth + 1);
  }).join(',') + '}';
}

function authority(config) {
  const agents = config?.agents?.list;
  if (!Array.isArray(agents)) throw error();
  const pixels = agents.filter(agent => agent?.id === 'pixel');
  if (pixels.length !== 1) throw error();
  const pixel = pixels[0], defaults = config.agents.defaults ?? {};
  const plugin = config.plugins?.entries?.['pixel-ods'];
  const value = canonical({enabled: plugin?.enabled ?? null, hooks: plugin?.hooks ?? null,
    binding: plugin?.config?.managedProvider ?? null,
    provider: config.models?.providers?.['ods-policy'] ?? null,
    model: pixel.model ?? null, globalTools: config.tools ?? null,
    agentTools: pixel.tools ?? null, sandbox: pixel.sandbox ?? null,
    defaultSandbox: defaults.sandbox ?? null, workspace: pixel.workspace ?? null,
    defaultWorkspace: defaults.workspace ?? null});
  if (Buffer.byteLength(value) > 1024 * 1024) throw error();
  return value;
}

function requireHooks(raw) {
  if (typeof raw !== 'string' || Buffer.byteLength(raw) > 16384) throw error();
  let policy;
  try { policy = JSON.parse(raw); } catch { throw error(); }
  const entries = policy?.plugins?.filter(entry => entry.id === 'pixel-ods');
  if (policy?.version !== 1 || entries?.length !== 1 ||
      !Array.isArray(entries[0].hooks) ||
      requiredManagedHooks.some(hook => !entries[0].hooks.includes(hook))) throw error();
}

export function createManagedRuntimeRegistry({environment = process.env,
  createRouting = createManagedProviderBootstrap,
  createCommands = createManagedCommandAdmission, controlTimeoutMs = 5000} = {}) {
  if (!Number.isSafeInteger(controlTimeoutMs) || controlTimeoutMs < 1 || controlTimeoutMs > 60000) throw error();
  let current, poisoned = false;
  const registered = new WeakSet();
  function refuse() {
    poisoned = true;
    if (current) void current.shutdown().catch(() => {});
    throw error();
  }
  function register(api, accessRuntime) {
    // Metadata/tool discovery must not instantiate or dispose the active owner.
    if (api.registrationMode !== 'full') {
      if (api.registrationMode === undefined &&
          (own(api.pluginConfig, 'managedProvider') || environment[DEPLOYMENT_ENV] !== undefined)) refuse();
      return null;
    }
    const raw = environment[DEPLOYMENT_ENV];
    const requested = own(api.pluginConfig, 'managedProvider');
    if (poisoned) throw error();
    if (!requested && raw === undefined) {
      if (current) refuse();
      return null;
    }
    if (!requested || typeof raw !== 'string' || !raw || Buffer.byteLength(raw) > 16384 ||
        typeof api.runtime?.config?.current !== 'function' ||
        !['registerProvider', 'on', 'registerRuntimeLifecycle'].every(key => typeof api[key] === 'function')) refuse();
    if (accessRuntime.status().available !== true) refuse();
    try { requireHooks(environment.OPENCLAW_REQUIRED_PLUGINS); } catch { refuse(); }
    if (current) {
      if (current.accessRuntime !== accessRuntime || current.deploymentText !== raw ||
          canonical(api.pluginConfig.managedProvider) !== current.binding || !current.valid()) refuse();
    } else {
      try {
        const deployment = JSON.parse(raw);
        if (canonical(deployment.binding) !== canonical(api.pluginConfig.managedProvider)) refuse();
        const readConfig = () => api.runtime.config.current();
        const baseline = authority(readConfig());
        const routing = createRouting({deployment, readConfig});
        const commands = createCommands({accessRuntime});
        const selected = new Map(), selecting = new Set();
        const transitionFailures = new WeakMap();
        let closed = false, failed = false, cleanupFailed = false, closing;
        const isPixel = context => !(typeof context?.agentId === 'string' && context.agentId !== 'pixel');
        const probe = context => accessRuntime.isProbe(context) === true;
        const transitionError = code => {
          const failure = error(); transitionFailures.set(failure, code); return failure;
        };
        function shutdown() {
          closed = true;
          if (!closing) {
            const close = fn => {try { return Promise.resolve(fn()); } catch { return Promise.reject(error()); }};
            closing = Promise.all([close(() => routing.shutdown()), close(() => commands.shutdown())])
              .then(() => { selected.clear(); }, () => {failed = true; throw error();});
            void closing.catch(() => {});
          }
          return closing;
        }
        function valid() {
          if (closed || failed) return false;
          try {
            if (accessRuntime.status().available !== true) throw error();
            requireHooks(environment.OPENCLAW_REQUIRED_PLUGINS);
            if (environment[DEPLOYMENT_ENV] === raw && authority(readConfig()) === baseline) return true;
          } catch { /* A missing/ambiguous current snapshot cannot authorize work. */ }
          failed = true; void shutdown(); return false;
        }
        async function finish(event, context) {
          if (cleanupFailed) throw error();
          try {
            const owner = selected.get(context?.runId ?? event?.runId);
            if (owner && ['runId', 'sessionId', 'sessionKey', 'agentId'].some(key => owner[key] !== (context?.[key] ?? null))) throw error();
            if (!probe(context)) await routing.agentEnd(event, context);
            accessRuntime.finish({runId: event?.runId}, context);
            selected.delete(context?.runId ?? event?.runId);
          } catch { cleanupFailed = true; failed = true; void shutdown(); throw error(); }
        }
        async function admit(event, context) {
          if (!valid()) return blocked();
          try {
            const access = accessRuntime.admit(undefined, context);
            if (access?.outcome !== 'pass') { await finish(event, context); return access ?? blocked(); }
            const decision = probe(context) ? access : await routing.beforeAgentRun(event, context);
            if (!valid() || decision?.outcome === 'block') {
              await finish(event, context); return blocked();
            }
            return decision ?? access;
          } catch {
            try { await finish(event, context); } catch { /* Do not clear an unknown owner hold. */ }
            return blocked();
          }
        }
        async function select(event, context) {
          if (!valid()) return unavailable();
          if (probe(context)) return undefined;
          if (!isPixel(context)) return routing.beforeModelResolve(event, context);
          if (!['idle', 'busy'].includes(accessRuntime.status().phase)) return unavailable();
          if (typeof context?.runId !== 'string' || !context.runId) return unavailable();
          const pending = {sessionKey: context.sessionKey};
          selecting.add(pending);
          const identity = Object.fromEntries(['runId', 'sessionId', 'sessionKey', 'agentId'].map(key => [key, context[key] ?? null]));
          const previous = selected.get(context.runId);
          if (previous && canonical(previous) !== canonical(identity)) {
            selecting.delete(pending); failed = true; void shutdown(); return unavailable();
          }
          selected.set(context.runId, identity);
          try {
            const decision = await routing.beforeModelResolve(event, context);
            if (decision?.providerOverride === 'ods-policy' && decision.modelOverride === 'unavailable') {
              await finish(event, context);
            }
            return valid() ? decision : unavailable();
          } catch {
            try { await finish(event, context); } catch { /* Keep uncertain cleanup held. */ }
            return unavailable();
          } finally { selecting.delete(pending); }
        }
        function assertTransition() {
          const command = commands.status();
          if (!valid() || selected.size || selecting.size || command.active || command.unknown || command.closed) throw error();
        }
        function status() {
          const base = accessRuntime.status(), command = commands.status();
          const activity = {...base.activity, selected: selected.size, selecting: selecting.size,
            commands: command.active, commandCleanupUnknown: command.unknown};
          if (!valid() || command.unknown || command.closed) return {...base, activity, available: false, phase: 'unavailable', revision: null};
          // Preserve the public access status shape. Count extra reservations
          // conservatively; never expose the deployment, route or credentials.
          const active = Math.max(base.active, command.active, selected.size + selecting.size);
          return {...base, activity, active, phase: active && base.phase === 'idle' ? 'busy' : base.phase};
        }
        function heldControlSnapshot() {
          const base = accessRuntime.status(), command = commands.status();
          if (base.available !== true || base.phase !== 'held' || base.active !== 0 ||
              selected.size || selecting.size || cleanupFailed || command.active || command.unknown) throw error();
          return base;
        }
        async function readControlStatus() {
          const normal = status();
          if (normal.available) return normal;
          let timer;
          try {
            // Configuration replacement intentionally invalidates the old
            // provider. Preserve ONLY an already-held management channel, and
            // only after that same provider/command owner has fully drained.
            // This never revives registration, inference, tools, or probes.
            const before = heldControlSnapshot();
            await Promise.race([shutdown(), new Promise((_, reject) => {
              timer = setTimeout(() => reject(error()), controlTimeoutMs);
            })]);
            const after = heldControlSnapshot();
            if (after.revision !== before.revision || after.pid !== before.pid) throw error();
            return after;
          } catch { return {...accessRuntime.status(), available: false, phase: 'unavailable', revision: null}; }
          finally { clearTimeout(timer); }
        }
        async function acquireTransition(token, revision) {
          if (valid()) {
            try { assertTransition(); }
            catch { throw transitionError('managed-transition-busy'); }
          } else {
            const held = await readControlStatus();
            if (!held.available || held.phase !== 'held' || accessRuntime.owns(token) !== true) {
              throw transitionError('managed-transition-invalid-owner');
            }
          }
          try { return await accessRuntime.acquire(token, revision); }
          catch { throw transitionError('managed-transition-access-owner-refused'); }
        }
        const maintenanceAuthority = {};
        async function acquireMaintenance(token, revision) {
          // Maintenance may not reuse an invalidated provider's management
          // fallback. That path is reserved for real transitions and reproof.
          assertTransition();
          return accessRuntime.acquireMaintenance(token, revision, maintenanceAuthority);
        }
        function releaseMaintenance(token) {
          try { assertTransition(); }
          catch {
            // Discard captured proof without opening the held admission gate.
            accessRuntime.acquire(token, accessRuntime.status().revision);
            throw error();
          }
          return accessRuntime.releaseMaintenance(token, maintenanceAuthority);
        }
        async function qualifyTransition(token, revision) {
          // A managed config hot reload deliberately poisons the old provider
          // owner, but an already-held model transaction must still be able to
          // run its fixed access proof and release.  Reuse only the drained
          // control channel; never revive inference, tools, or provider work.
          const held = await readControlStatus();
          if (held.available !== true || held.phase !== 'held' || held.active !== 0 ||
              held.revision !== revision || accessRuntime.owns(token) !== true) {
            throw transitionError('managed-transition-invalid-owner');
          }
          return held;
        }
        current = {accessRuntime, deploymentText: raw, binding: canonical(deployment.binding),
          routing, commands, valid, shutdown, admit, finish, select, assertTransition, status,
          readControlStatus, acquireTransition, acquireMaintenance, releaseMaintenance, qualifyTransition,
          classifyTransitionError: failure => transitionFailures.get(failure) ?? null,
          readRegistration() {
            assertTransition();
            // Report this successfully registered owner, not an editable config
            // echo. This does not attest any provider request or model response.
            return {status: 'active', binding: JSON.parse(current.binding)};
          },
          beforeCommandRun(event, context) {
            // The access proof deliberately executes two fixed, internally
            // prepared commands while admission is held.  Feeding those
            // commands back through ordinary managed command admission makes
            // the shared access owner reject its own proof.  Only the access
            // runtime can identify this unforgeable run; user-supplied hints
            // do not bypass command accounting.
            if (probe(context)) return undefined;
            if (!valid()) return {action: 'block', reason: 'ods-command-admission-unavailable'};
            return commands.beforeCommandRun(event, context);
          },
          cleanup(context) {
            if (context?.sessionKey || context?.runId) {
              // Session reset/delete is not proof that its runner or subprocess
              // exited. Do not release activity or shut down unrelated sessions.
              if (selecting.size || [...selected.values()].some(owner =>
                owner.runId === context.runId || owner.sessionKey === context.sessionKey)) throw error();
              return;
            }
            return shutdown();
          }};
      } catch { refuse(); }
    }
    if (!registered.has(api)) {
      try {
        api.registerProvider(current.routing.provider);
        api.on('before_model_resolve', current.select);
        api.on('before_agent_run', current.admit, current.routing.beforeAgentRunOptions);
        api.on('agent_end', current.finish, {timeoutMs: 125000});
        api.on('before_command_run', current.beforeCommandRun, {timeoutMs: 6000});
        api.on('gateway_stop', current.shutdown, {timeoutMs: 125000});
        api.registerRuntimeLifecycle({id: 'ods-managed-runtime', cleanup: current.cleanup});
        registered.add(api);
      } catch { refuse(); }
    }
    return current;
  }
  return {register};
}