@holoscript/holoscript-agent 2.0.0

package/dist/supervisor-config.d.ts

@@ -0,0 +1,26 @@
+import { LLMProviderName } from '@holoscript/llm-provider';
+
+interface AgentSpec {
+    handle: string;
+    brainPath: string;
+    provider: LLMProviderName;
+    model: string;
+    walletEnvKey: string;
+    bearerEnvKey: string;
+    budgetUsdPerDay?: number;
+    scopeTier?: 'cold' | 'warm' | 'hot';
+    enabled?: boolean;
+    tickIntervalMs?: number;
+    enableCommitHook?: boolean;
+    outputDir?: string;
+    workingDir?: string;
+}
+interface SupervisorConfig {
+    agents: AgentSpec[];
+    globalBudgetUsdPerDay?: number;
+    defaultTickIntervalMs?: number;
+}
+declare function loadSupervisorConfig(path: string): SupervisorConfig;
+declare function parseSupervisorConfig(raw: string): SupervisorConfig;
+
+export { type AgentSpec, type SupervisorConfig, loadSupervisorConfig, parseSupervisorConfig };

package/dist/supervisor-config.js

@@ -0,0 +1,109 @@
+// src/supervisor-config.ts
+import { readFileSync } from "fs";
+var VALID_PROVIDERS = /* @__PURE__ */ new Set([
+  "anthropic",
+  "openai",
+  "gemini",
+  "mock",
+  "bitnet",
+  "local-llm"
+]);
+var VALID_TIERS = /* @__PURE__ */ new Set(["cold", "warm", "hot"]);
+var HANDLE_PATTERN = /^[a-z0-9_-]{1,64}$/i;
+function loadSupervisorConfig(path) {
+  return parseSupervisorConfig(readFileSync(path, "utf8"));
+}
+function parseSupervisorConfig(raw) {
+  const data = JSON.parse(raw);
+  if (!isObject(data)) throw new Error("Supervisor config must be a JSON object");
+  if (!Array.isArray(data.agents)) throw new Error("Supervisor config.agents must be an array");
+  if (data.agents.length === 0) throw new Error("Supervisor config.agents must have at least one entry");
+  const seenHandles = /* @__PURE__ */ new Set();
+  const agents = data.agents.map((entry, idx) => validateAgent(entry, idx, seenHandles));
+  const globalBudgetUsdPerDay = optionalNumber(data, "globalBudgetUsdPerDay");
+  const defaultTickIntervalMs = optionalNumber(data, "defaultTickIntervalMs");
+  if (globalBudgetUsdPerDay != null && globalBudgetUsdPerDay <= 0) {
+    throw new Error(`globalBudgetUsdPerDay must be positive, got ${globalBudgetUsdPerDay}`);
+  }
+  if (defaultTickIntervalMs != null && defaultTickIntervalMs < 5e3) {
+    throw new Error(`defaultTickIntervalMs must be >= 5000ms (mesh-friendly), got ${defaultTickIntervalMs}`);
+  }
+  return { agents, globalBudgetUsdPerDay, defaultTickIntervalMs };
+}
+function validateAgent(entry, idx, seen) {
+  if (!isObject(entry)) throw new Error(`agents[${idx}] must be an object`);
+  const handle = requiredString(entry, "handle", `agents[${idx}].handle`);
+  if (!HANDLE_PATTERN.test(handle)) {
+    throw new Error(`agents[${idx}].handle "${handle}" must match ${HANDLE_PATTERN}`);
+  }
+  if (seen.has(handle)) throw new Error(`Duplicate agent handle: "${handle}"`);
+  seen.add(handle);
+  const provider = requiredString(entry, "provider", `agents[${idx}].provider`);
+  if (!VALID_PROVIDERS.has(provider)) {
+    throw new Error(
+      `agents[${idx}].provider "${provider}" not in [${[...VALID_PROVIDERS].join(", ")}]`
+    );
+  }
+  const scopeTier = optionalString(entry, "scopeTier");
+  if (scopeTier && !VALID_TIERS.has(scopeTier)) {
+    throw new Error(`agents[${idx}].scopeTier "${scopeTier}" must be cold | warm | hot`);
+  }
+  const budgetUsdPerDay = optionalNumber(entry, "budgetUsdPerDay");
+  if (budgetUsdPerDay != null && budgetUsdPerDay <= 0) {
+    throw new Error(`agents[${idx}].budgetUsdPerDay must be positive, got ${budgetUsdPerDay}`);
+  }
+  const tickIntervalMs = optionalNumber(entry, "tickIntervalMs");
+  if (tickIntervalMs != null && tickIntervalMs < 5e3) {
+    throw new Error(`agents[${idx}].tickIntervalMs must be >= 5000ms, got ${tickIntervalMs}`);
+  }
+  return {
+    handle,
+    brainPath: requiredString(entry, "brainPath", `agents[${idx}].brainPath`),
+    provider,
+    model: requiredString(entry, "model", `agents[${idx}].model`),
+    walletEnvKey: requiredString(entry, "walletEnvKey", `agents[${idx}].walletEnvKey`),
+    bearerEnvKey: requiredString(entry, "bearerEnvKey", `agents[${idx}].bearerEnvKey`),
+    budgetUsdPerDay,
+    scopeTier,
+    enabled: optionalBoolean(entry, "enabled"),
+    tickIntervalMs,
+    enableCommitHook: optionalBoolean(entry, "enableCommitHook"),
+    outputDir: optionalString(entry, "outputDir"),
+    workingDir: optionalString(entry, "workingDir")
+  };
+}
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function requiredString(obj, key, label) {
+  const v = obj[key];
+  if (typeof v !== "string" || v.trim().length === 0) {
+    throw new Error(`${label} is required and must be a non-empty string`);
+  }
+  return v.trim();
+}
+function optionalString(obj, key) {
+  const v = obj[key];
+  if (v === void 0 || v === null) return void 0;
+  if (typeof v !== "string") throw new Error(`${key} must be a string when present`);
+  return v.trim();
+}
+function optionalNumber(obj, key) {
+  const v = obj[key];
+  if (v === void 0 || v === null) return void 0;
+  if (typeof v !== "number" || !Number.isFinite(v)) {
+    throw new Error(`${key} must be a finite number when present`);
+  }
+  return v;
+}
+function optionalBoolean(obj, key) {
+  const v = obj[key];
+  if (v === void 0 || v === null) return void 0;
+  if (typeof v !== "boolean") throw new Error(`${key} must be a boolean when present`);
+  return v;
+}
+export {
+  loadSupervisorConfig,
+  parseSupervisorConfig
+};
+//# sourceMappingURL=supervisor-config.js.map

package/dist/supervisor-config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/supervisor-config.ts"],"sourcesContent":["import { readFileSync } from 'node:fs';\nimport type { LLMProviderName } from '@holoscript/llm-provider';\n\nexport interface AgentSpec {\n  handle: string;\n  brainPath: string;\n  provider: LLMProviderName;\n  model: string;\n  walletEnvKey: string;\n  bearerEnvKey: string;\n  budgetUsdPerDay?: number;\n  scopeTier?: 'cold' | 'warm' | 'hot';\n  enabled?: boolean;\n  tickIntervalMs?: number;\n  enableCommitHook?: boolean;\n  outputDir?: string;\n  workingDir?: string;\n}\n\nexport interface SupervisorConfig {\n  agents: AgentSpec[];\n  globalBudgetUsdPerDay?: number;\n  defaultTickIntervalMs?: number;\n}\n\nconst VALID_PROVIDERS: ReadonlySet<LLMProviderName> = new Set([\n  'anthropic',\n  'openai',\n  'gemini',\n  'mock',\n  'bitnet',\n  'local-llm',\n]);\n\nconst VALID_TIERS: ReadonlySet<string> = new Set(['cold', 'warm', 'hot']);\nconst HANDLE_PATTERN = /^[a-z0-9_-]{1,64}$/i;\n\nexport function loadSupervisorConfig(path: string): SupervisorConfig {\n  return parseSupervisorConfig(readFileSync(path, 'utf8'));\n}\n\nexport function parseSupervisorConfig(raw: string): SupervisorConfig {\n  const data = JSON.parse(raw) as unknown;\n  if (!isObject(data)) throw new Error('Supervisor config must be a JSON object');\n  if (!Array.isArray(data.agents)) throw new Error('Supervisor config.agents must be an array');\n  if (data.agents.length === 0) throw new Error('Supervisor config.agents must have at least one entry');\n\n  const seenHandles = new Set<string>();\n  const agents: AgentSpec[] = data.agents.map((entry, idx) => validateAgent(entry, idx, seenHandles));\n\n  const globalBudgetUsdPerDay = optionalNumber(data, 'globalBudgetUsdPerDay');\n  const defaultTickIntervalMs = optionalNumber(data, 'defaultTickIntervalMs');\n  if (globalBudgetUsdPerDay != null && globalBudgetUsdPerDay <= 0) {\n    throw new Error(`globalBudgetUsdPerDay must be positive, got ${globalBudgetUsdPerDay}`);\n  }\n  if (defaultTickIntervalMs != null && defaultTickIntervalMs < 5000) {\n    throw new Error(`defaultTickIntervalMs must be >= 5000ms (mesh-friendly), got ${defaultTickIntervalMs}`);\n  }\n\n  return { agents, globalBudgetUsdPerDay, defaultTickIntervalMs };\n}\n\nfunction validateAgent(entry: unknown, idx: number, seen: Set<string>): AgentSpec {\n  if (!isObject(entry)) throw new Error(`agents[${idx}] must be an object`);\n  const handle = requiredString(entry, 'handle', `agents[${idx}].handle`);\n  if (!HANDLE_PATTERN.test(handle)) {\n    throw new Error(`agents[${idx}].handle \"${handle}\" must match ${HANDLE_PATTERN}`);\n  }\n  if (seen.has(handle)) throw new Error(`Duplicate agent handle: \"${handle}\"`);\n  seen.add(handle);\n\n  const provider = requiredString(entry, 'provider', `agents[${idx}].provider`);\n  if (!VALID_PROVIDERS.has(provider as LLMProviderName)) {\n    throw new Error(\n      `agents[${idx}].provider \"${provider}\" not in [${[...VALID_PROVIDERS].join(', ')}]`\n    );\n  }\n\n  const scopeTier = optionalString(entry, 'scopeTier');\n  if (scopeTier && !VALID_TIERS.has(scopeTier)) {\n    throw new Error(`agents[${idx}].scopeTier \"${scopeTier}\" must be cold | warm | hot`);\n  }\n\n  const budgetUsdPerDay = optionalNumber(entry, 'budgetUsdPerDay');\n  if (budgetUsdPerDay != null && budgetUsdPerDay <= 0) {\n    throw new Error(`agents[${idx}].budgetUsdPerDay must be positive, got ${budgetUsdPerDay}`);\n  }\n  const tickIntervalMs = optionalNumber(entry, 'tickIntervalMs');\n  if (tickIntervalMs != null && tickIntervalMs < 5000) {\n    throw new Error(`agents[${idx}].tickIntervalMs must be >= 5000ms, got ${tickIntervalMs}`);\n  }\n\n  return {\n    handle,\n    brainPath: requiredString(entry, 'brainPath', `agents[${idx}].brainPath`),\n    provider: provider as LLMProviderName,\n    model: requiredString(entry, 'model', `agents[${idx}].model`),\n    walletEnvKey: requiredString(entry, 'walletEnvKey', `agents[${idx}].walletEnvKey`),\n    bearerEnvKey: requiredString(entry, 'bearerEnvKey', `agents[${idx}].bearerEnvKey`),\n    budgetUsdPerDay,\n    scopeTier: scopeTier as 'cold' | 'warm' | 'hot' | undefined,\n    enabled: optionalBoolean(entry, 'enabled'),\n    tickIntervalMs,\n    enableCommitHook: optionalBoolean(entry, 'enableCommitHook'),\n    outputDir: optionalString(entry, 'outputDir'),\n    workingDir: optionalString(entry, 'workingDir'),\n  };\n}\n\nfunction isObject(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}\n\nfunction requiredString(obj: Record<string, unknown>, key: string, label: string): string {\n  const v = obj[key];\n  if (typeof v !== 'string' || v.trim().length === 0) {\n    throw new Error(`${label} is required and must be a non-empty string`);\n  }\n  return v.trim();\n}\n\nfunction optionalString(obj: Record<string, unknown>, key: string): string | undefined {\n  const v = obj[key];\n  if (v === undefined || v === null) return undefined;\n  if (typeof v !== 'string') throw new Error(`${key} must be a string when present`);\n  return v.trim();\n}\n\nfunction optionalNumber(obj: Record<string, unknown>, key: string): number | undefined {\n  const v = obj[key];\n  if (v === undefined || v === null) return undefined;\n  if (typeof v !== 'number' || !Number.isFinite(v)) {\n    throw new Error(`${key} must be a finite number when present`);\n  }\n  return v;\n}\n\nfunction optionalBoolean(obj: Record<string, unknown>, key: string): boolean | undefined {\n  const v = obj[key];\n  if (v === undefined || v === null) return undefined;\n  if (typeof v !== 'boolean') throw new Error(`${key} must be a boolean when present`);\n  return v;\n}\n"],"mappings":"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","names":[]}

package/dist/supervisor.d.ts

@@ -0,0 +1,53 @@
+import { ILLMProvider } from '@holoscript/llm-provider';
+import { AgentSpec, SupervisorConfig } from './supervisor-config.js';
+import { AgentIdentity } from './types.js';
+
+interface ProviderFactory {
+    (spec: AgentSpec, identity: AgentIdentity): Promise<ILLMProvider> | ILLMProvider;
+}
+interface SupervisorAgentStatus {
+    handle: string;
+    state: 'starting' | 'running' | 'crashed' | 'over-budget' | 'stopped';
+    spentUsd: number;
+    remainingUsd: number;
+    lastTickAt?: string;
+    lastError?: string;
+    restarts: number;
+}
+interface SupervisorStatus {
+    globalSpentUsd: number;
+    globalRemainingUsd: number;
+    globalBudgetExhausted: boolean;
+    agents: SupervisorAgentStatus[];
+}
+interface SupervisorOptions {
+    config: SupervisorConfig;
+    providerFactory: ProviderFactory;
+    meshApiBase?: string;
+    teamId: string;
+    stateDir?: string;
+    auditLogPath?: string;
+    logger?: (event: Record<string, unknown>) => void;
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+}
+declare class Supervisor {
+    private readonly opts;
+    private readonly agents;
+    private stopped;
+    private globalBudgetUsdPerDay?;
+    private readonly auditLog?;
+    constructor(opts: SupervisorOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    status(): SupervisorStatus;
+    tickOnce(handle: string): Promise<SupervisorAgentStatus>;
+    private bootAgent;
+    private buildCommitHook;
+    private identityFromSpec;
+    private spawnLoop;
+    private runOneTick;
+    private log;
+}
+
+export { type ProviderFactory, Supervisor, type SupervisorAgentStatus, type SupervisorOptions, type SupervisorStatus };