Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// okx-chat-bot: configuration, resolved once at boot.
//
// Everything here is env-driven so the same image runs on Cloud Run, on a plain
// VM, and locally with no code change. The defaults are the production posture:
// state persisted to GCS, heartbeat on, session probed every minute.
import { existsSync } from 'node:fs';
import { homedir, hostname } from 'node:os';
import { join } from 'node:path';
const num = (v, fallback) => {
const n = Number(v);
return Number.isFinite(n) && n > 0 ? n : fallback;
};
/**
* Every AI lane this host could authenticate through, best first.
*
* There used to be exactly one. That is a chain with a single rung, and on
* 2026-09-04 the rung snapped: the GCP project's Vertex access started answering
* `PERMISSION_DENIED: Lightning dunning decision is deny` (a billing hold that
* reads like an IAM fault) and the host sat on that one dead lane, unable to
* author a single reply, while other credentials the project holds went
* unconsidered. Whichever lane is funded should be the lane that serves, and the
* host should move to it by itself.
*
* Order is a policy, not a preference:
*
* vertex GCP credits, authenticated by the runtime service account.
* No secret exists to leak, rotate or forget, and the spend
* lands on the pool the platform already prefers.
* anthropic-key a first-party ANTHROPIC_API_KEY.
* anthropic-gateway any Anthropic-wire-format gateway. The deploy points it
* at three.ws's own we-pay proxy (the free model chain,
* metered against a dedicated platform agent); OpenRouter
* serves one too. Opt-in: it only exists when an operator
* sets its base URL and token.
* anthropic-oauth an interactive `claude` login on a developer host.
* openai-key the codex CLI on OPENAI_API_KEY.
*
* Every lane carries the env its CLI needs, so electing one is applying that
* overlay and respawning the daemon. A `null` value means "unset this", which is
* what lets the gateway lane switch Vertex off for the subsession it spawns.
*
* @param {NodeJS.ProcessEnv} env
* @param {string} home where a CLI keeps an interactive login
* @returns {Array<{ id: string, provider: string, transport: string, reason: string, env: Record<string,string|null> }>}
*/
export function providerLanes(env = process.env, home = env.OKX_BOT_HOME || homedir()) {
const lanes = [];
const onVertex =
(env.CLAUDE_CODE_USE_VERTEX === '1' || env.CLAUDE_CODE_USE_VERTEX === 'true') &&
!!(env.ANTHROPIC_VERTEX_PROJECT_ID || env.GOOGLE_CLOUD_PROJECT);
if (onVertex) {
lanes.push({
id: 'vertex',
provider: 'claude',
transport: 'vertex',
reason: 'Vertex AI, authenticated by the runtime service account (no key to rotate)',
credentialed: true,
env: {},
});
}
if (env.ANTHROPIC_API_KEY) {
lanes.push({
id: 'anthropic-key',
provider: 'claude',
transport: 'api-key',
reason: 'ANTHROPIC_API_KEY present',
credentialed: true,
env: { CLAUDE_CODE_USE_VERTEX: null, ANTHROPIC_BASE_URL: null },
});
}
const gateway = gatewayLane(env);
if (gateway) lanes.push(gateway);
if (env.CLAUDE_CODE_OAUTH_TOKEN) {
lanes.push({
id: 'anthropic-oauth-token',
provider: 'claude',
transport: 'api-key',
reason: 'CLAUDE_CODE_OAUTH_TOKEN present',
credentialed: true,
env: { CLAUDE_CODE_USE_VERTEX: null, ANTHROPIC_BASE_URL: null },
});
}
if (existsSync(join(home, '.claude', '.credentials.json'))) {
lanes.push({
id: 'anthropic-login',
provider: 'claude',
transport: 'oauth-login',
reason: 'claude CLI holds an interactive login',
credentialed: true,
env: {},
});
}
if (env.OPENAI_API_KEY) {
lanes.push({
id: 'openai-key',
provider: 'codex',
transport: 'api-key',
reason: 'OPENAI_API_KEY present',
credentialed: true,
env: {},
});
}
return lanes;
}
/**
* The Anthropic-compatible gateway lane, or null when none is configured.
*
* `claude` speaks one wire format and reads its endpoint from ANTHROPIC_BASE_URL,
* so any service that serves `/v1/messages` is a usable lane for the same agentic
* CLI the adapter already spawns. That keeps the task lifecycle intact, which a
* one-shot completion responder would break.
*
* Deliberately opt-in: whatever the base URL names meters or bills this host's
* calls (three.ws's own proxy against a dedicated agent's budget, a third-party
* gateway per token), so it must be a decision an operator made, never something
* the host picks up from an unrelated key that happened to be on the service.
*/
function gatewayLane(env) {
const base = (env.OKX_BOT_ANTHROPIC_BASE_URL || '').trim().replace(/\/+$/, '');
const token = (env.OKX_BOT_ANTHROPIC_AUTH_TOKEN || '').trim();
if (!base || !token) return null;
const model = (env.OKX_BOT_ANTHROPIC_MODEL || '').trim();
let label = base;
try {
label = new URL(base).host;
} catch {
/* a malformed base URL still names itself in the reason */
}
return {
id: 'anthropic-gateway',
provider: 'claude',
transport: 'gateway',
reason: `Anthropic-compatible gateway at ${label}${model ? ` (${model})` : ''}`,
credentialed: true,
env: {
CLAUDE_CODE_USE_VERTEX: null,
ANTHROPIC_BASE_URL: base,
ANTHROPIC_AUTH_TOKEN: token,
ANTHROPIC_API_KEY: null,
...(model ? { ANTHROPIC_MODEL: model, ANTHROPIC_SMALL_FAST_MODEL: model } : {}),
},
};
}
/**
* Narrow the chain to what an explicit pin allows.
*
* A pin names a provider CLI, not a lane, so `OKX_BOT_AI_PROVIDER=claude` keeps
* every Anthropic lane and drops codex. A pin naming a provider with no lane at
* all still returns an honest, uncredentialed single entry rather than silently
* electing something the operator did not ask for.
*/
export function pinnedLanes(lanes, pinned) {
if (!pinned) return lanes;
const kept = lanes.filter((l) => l.provider === pinned);
if (kept.length) return kept.map((l) => ({ ...l, reason: `pinned by OKX_BOT_AI_PROVIDER (${l.reason})` }));
const external = pinned !== 'claude' && pinned !== 'codex';
return [
{
id: `${pinned}-pinned`,
provider: pinned,
transport: external ? 'external' : 'none',
reason: external
? 'pinned by OKX_BOT_AI_PROVIDER (provider supplies its own auth)'
: `pinned by OKX_BOT_AI_PROVIDER (no ${pinned === 'claude' ? 'Anthropic' : 'OpenAI'} credential)`,
env: {},
credentialed: external,
},
];
}
/**
* Resolve the whole chain: the lanes to try, in order, and which one leads.
*
* `credentialed` on a lane only answers "is a credential configured". Whether it
* still WORKS is a different question, and on this project the two answers have
* differed in both directions: the GCP project's Vertex access and the OpenAI key
* are each present and each refuse to serve. electProvider() in provider.js asks
* each lane's own API, and its verdict is what readiness is judged on.
*
* The adapter does NOT read a reply out of the CLI's stdout: the spawned AI
* subsession sends the reply itself through the `okx-a2a` CLI and drives the task
* lifecycle (accept / negotiate / deliver). So every lane must spawn a genuinely
* agentic CLI with tool access, never a one-shot completion call.
*
* @returns {{ lanes: Array<object>, head: object }}
*/
export function resolveProviderChain(env = process.env, home = env.OKX_BOT_HOME || homedir()) {
const pinned = (env.OKX_BOT_AI_PROVIDER || '').trim().toLowerCase();
const lanes = pinnedLanes(providerLanes(env, home), pinned);
if (lanes.length) return { lanes, head: lanes[0] };
return {
lanes: [],
head: {
id: 'none',
provider: 'claude',
transport: 'none',
reason: 'no AI-provider credential found, chat replies will fail until one is set',
env: {},
credentialed: false,
},
};
}
export function resolveHost(env = process.env) {
if (env.K_SERVICE) {
return { label: `cloudrun:${env.K_SERVICE}${env.K_REVISION ? ` (${env.K_REVISION})` : ''}`, durable: true };
}
const explicit = (env.OKX_BOT_HOST_LABEL || '').trim();
if (explicit) return { label: explicit, durable: env.OKX_BOT_HOST_DURABLE === '1' };
if (env.CODESPACE_NAME) return { label: `codespace:${env.CODESPACE_NAME}`, durable: false };
return { label: `local:${hostname()}`, durable: false };
}
/**
* Point the config at one lane of the chain.
*
* Every consumer (the heartbeat, the health body, cliEnv) reads the flat
* `provider*` fields, so electing a lane is one mutation here rather than a
* plumbing change in five files. Called at boot with the head of the chain and
* again whenever a probe elects a different one.
*
* @param {ReturnType<loadConfig>} cfg
* @param {{ id: string, provider: string, transport: string, reason: string, env: object }} lane
*/
export function applyLane(cfg, lane) {
cfg.activeLane = lane;
cfg.provider = lane.provider;
cfg.providerTransport = lane.transport;
cfg.providerReason = lane.reason;
cfg.providerCredentialed = lane.credentialed === true;
return cfg;
}
export function loadConfig(env = process.env) {
const home = env.OKX_BOT_HOME || homedir();
const chain = resolveProviderChain(env, home);
const host = resolveHost(env);
return {
// HOME for both CLIs. Everything durable lands under it:
// $home/.okx-agent-task/ daemon state, sqlite, XMTP db, AI workspace
// $home/.onchainos/ wallet keyring, session, machine identity
home,
port: num(env.PORT, 0),
agentId: env.OKX_BOT_AGENT_ID || '2632',
// The XMTP daemon binary the supervisor owns. Overridable so a host that
// installed it under a different name (or a test that needs a spawn to
// fail) does not have to patch the supervisor.
daemonBin: env.OKX_BOT_DAEMON_BIN || 'okx-a2a',
// Durable state. Cloud Run's filesystem is in-memory and dies with the
// revision, so the tree above is tarred to GCS and restored on boot.
// Unset bucket = ephemeral mode (local dev, or a host with a real disk).
stateBucket: (env.OKX_BOT_STATE_BUCKET || '').trim(),
stateObject: env.OKX_BOT_STATE_OBJECT || 'okx-chat-bot/state.tar.gz',
// The lanes this host may authenticate through, best first, and the one it
// is currently using. A single-rung chain is what left the host sitting on
// a dead Vertex credential for days; see providerLanes().
chain: chain.lanes,
activeLane: chain.head,
provider: chain.head.provider,
providerTransport: chain.head.transport,
providerReason: chain.head.reason,
providerCredentialed: chain.head.credentialed === true,
// How often the provider's own API is asked whether the credential still
// works. A configured credential is not a working one: on this project the
// GCP billing hold and the OpenAI account both answer "denied" to a key
// that is present and well-formed. Kept slow because it is a real call.
providerProbeMs: num(env.OKX_BOT_PROVIDER_PROBE_MS, 15 * 60_000),
// Where this process runs, and whether that place stays up on its own.
// Reported on every beat so /api/healthz can tell a durable host from a
// stopgap instead of calling both "online".
host: host.label,
hostDurable: host.durable,
// Where the AI subsession's briefing and skills come from. Baked into the
// image at /app; regenerated at boot so a redeploy always ships the live
// catalog rather than whatever the last snapshot happened to contain.
repoRoot: env.OKX_BOT_REPO_ROOT || '/app',
heartbeatMs: num(env.OKX_BOT_HEARTBEAT_MS, 30_000),
// The single-writer lease (lease.js). Required whenever state is shared
// through the bucket, because that is when a second host could write it.
// The TTL bounds how long a host that died without releasing blocks its
// successor; renewal runs well inside it so a slow query never loses it.
leaseRequired: !!(env.OKX_BOT_STATE_BUCKET || '').trim(),
leaseTtlMs: num(env.OKX_BOT_LEASE_TTL_MS, 120_000),
leaseRenewMs: num(env.OKX_BOT_LEASE_RENEW_MS, 20_000),
leasePollMs: num(env.OKX_BOT_LEASE_POLL_MS, 5_000),
// A host built before the lease existed is recognised by its heartbeat and
// waited out until that beat is this old: three missed beats at the default
// cadence, so one slow write never reads as the host having gone.
legacyBeatStaleMs: num(env.OKX_BOT_LEGACY_BEAT_STALE_MS, 3 * num(env.OKX_BOT_HEARTBEAT_MS, 30_000)),
sessionProbeMs: num(env.OKX_BOT_SESSION_PROBE_MS, 60_000),
snapshotMs: num(env.OKX_BOT_SNAPSHOT_MS, 5 * 60_000),
// A logged-out session needs a human. Alert on the transition, then at most
// this often while it stays out, so one OTP expiry doesn't page all night.
alertRepeatMs: num(env.OKX_BOT_ALERT_REPEAT_MS, 6 * 60 * 60_000),
// Restart backoff for the daemon child, capped.
restartBaseMs: num(env.OKX_BOT_RESTART_BASE_MS, 2_000),
restartMaxMs: num(env.OKX_BOT_RESTART_MAX_MS, 60_000),
};
}
export function paths(cfg) {
const agentTask = join(cfg.home, '.okx-agent-task');
return {
agentTask,
onchainos: join(cfg.home, '.onchainos'),
workspace: join(agentTask, 'workspace'),
skills: join(agentTask, 'workspace', '.claude', 'skills'),
logs: join(agentTask, 'logs'),
lock: join(agentTask, 'run', 'daemon.lock'),
};
}