@holoscript/core 6.0.3 → 6.1.1

package/dist/self-improvement/index.cjs

@@ -0,0 +1,563 @@
+'use strict';
+
+require('../chunk-HCCQLAA4.cjs');
+var crypto = require('crypto');
+
+// src/self-improvement/SelfImproveHarvester.ts
+var SelfImproveHarvester = class {
+  constructor(config = {}) {
+    this.entries = [];
+    this.outputFile = config.outputFile ?? config.outputDir ?? "memory://self-improvement-harvest.jsonl";
+    this.minQualityScore = config.minQualityScore ?? 0;
+  }
+  harvestFromCycle(instruction, output, testResult, qualityScore, metadata) {
+    if (qualityScore < this.minQualityScore) {
+      return;
+    }
+    this.entries.push({
+      instruction,
+      output,
+      testResult,
+      qualityScore,
+      ...metadata ? { metadata } : {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  getStats() {
+    return {
+      entryCount: this.entries.length,
+      currentFile: this.outputFile
+    };
+  }
+};
+var OUTCOME_SCHEMA_VERSION = "1.0.0";
+function artifactHash(artifact) {
+  return {
+    path: artifact.path,
+    kind: artifact.kind,
+    algorithm: "sha256",
+    hash: crypto.createHash("sha256").update(artifact.content).digest("hex")
+  };
+}
+function artifactHashes(artifacts) {
+  return artifacts.map(artifactHash);
+}
+function validateOutcomeSpec(spec) {
+  const errors = [];
+  if (!spec.id) errors.push("OutcomeSpec.id is required.");
+  if (!Array.isArray(spec.rubric) || spec.rubric.length === 0) {
+    errors.push("OutcomeSpec.rubric must include at least one criterion.");
+  }
+  if (!Number.isFinite(spec.threshold) || spec.threshold <= 0 || spec.threshold > 1) {
+    errors.push("OutcomeSpec.threshold must be in (0, 1].");
+  }
+  if (!Number.isInteger(spec.maxIterations) || spec.maxIterations < 1) {
+    errors.push("OutcomeSpec.maxIterations must be a positive integer.");
+  }
+  if (!Array.isArray(spec.artifacts) || spec.artifacts.length === 0) {
+    errors.push("OutcomeSpec.artifacts must include at least one artifact.");
+  }
+  if (!spec.grader?.id) errors.push("OutcomeSpec.grader.id is required.");
+  if (!Array.isArray(spec.validationCommands)) {
+    errors.push("OutcomeSpec.validationCommands must be an array.");
+  }
+  return errors;
+}
+function cloneArtifacts(artifacts) {
+  return artifacts.map((artifact) => ({ ...artifact }));
+}
+function cloneSpec(spec) {
+  return {
+    ...spec,
+    rubric: spec.rubric.map((criterion) => ({ ...criterion })),
+    artifacts: cloneArtifacts(spec.artifacts),
+    validationCommands: spec.validationCommands.map((command) => ({ ...command })),
+    grader: { ...spec.grader },
+    circuitBreaker: spec.circuitBreaker ? { ...spec.circuitBreaker } : void 0,
+    metadata: spec.metadata ? { ...spec.metadata } : void 0
+  };
+}
+function clampScore(score) {
+  if (!Number.isFinite(score)) return 0;
+  return Math.max(0, Math.min(1, score));
+}
+function scoreFromCriteria(spec, criteria) {
+  if (criteria.length === 0) return 0;
+  const weights = new Map(spec.rubric.map((criterion) => [criterion.id, criterion.weight ?? 1]));
+  const totalWeight = criteria.reduce((sum, criterion) => sum + Math.max(0, weights.get(criterion.criterionId) ?? 1), 0);
+  if (totalWeight === 0) return 0;
+  const weighted = criteria.reduce((sum, criterion) => {
+    const weight = Math.max(0, weights.get(criterion.criterionId) ?? 1);
+    return sum + clampScore(criterion.score) * weight;
+  }, 0);
+  return Math.round(weighted / totalWeight * 1e4) / 1e4;
+}
+function normalizeGrade(spec, grade) {
+  const returned = new Map(
+    grade.criteria.map((criterion) => [
+      criterion.criterionId,
+      {
+        ...criterion,
+        score: clampScore(criterion.score)
+      }
+    ])
+  );
+  const criteria = spec.rubric.map((rubricCriterion) => {
+    const criterion = returned.get(rubricCriterion.id);
+    if (criterion) return criterion;
+    return {
+      criterionId: rubricCriterion.id,
+      score: 0,
+      passed: false,
+      gap: "No grade returned for this rubric criterion."
+    };
+  });
+  return {
+    ...grade,
+    criteria,
+    score: clampScore(grade.score ?? scoreFromCriteria(spec, criteria))
+  };
+}
+function makeContext(specId, role, iteration) {
+  return {
+    role,
+    iteration,
+    contextId: `${specId}:${role}:${iteration}`
+  };
+}
+function validationFallback(command) {
+  return {
+    ...command,
+    passed: true,
+    exitCode: 0
+  };
+}
+function requiredValidationFailed(results) {
+  return results.some((result) => result.required !== false && !result.passed);
+}
+function circuitBreakerTripped(spec, receipts, consecutiveFailures) {
+  const config = spec.circuitBreaker;
+  if (!config) return null;
+  if (config.maxConsecutiveFailures !== void 0 && consecutiveFailures >= config.maxConsecutiveFailures) {
+    return `Circuit breaker tripped after ${consecutiveFailures} consecutive failed iteration(s).`;
+  }
+  if (config.minScoreProgress !== void 0 && receipts.length >= 2) {
+    const latest = receipts[receipts.length - 1];
+    const previous = receipts[receipts.length - 2];
+    if (latest.score - previous.score < config.minScoreProgress) {
+      return `Circuit breaker tripped because score progress ${latest.score - previous.score} was below ${config.minScoreProgress}.`;
+    }
+  }
+  return null;
+}
+var OutcomeLoop = class {
+  constructor(options) {
+    this.options = options;
+  }
+  async run(specInput) {
+    const errors = validateOutcomeSpec(specInput);
+    if (errors.length) {
+      throw new Error(`Invalid OutcomeSpec:
+${errors.join("\n")}`);
+    }
+    const spec = cloneSpec(specInput);
+    const receipts = [];
+    let artifacts = cloneArtifacts(spec.artifacts);
+    let previousGaps = [];
+    let consecutiveFailures = 0;
+    for (let iteration = 1; iteration <= spec.maxIterations; iteration += 1) {
+      const implementerContext = makeContext(spec.id, "implementer", iteration);
+      const implementation = await this.options.implementer({
+        spec: cloneSpec(spec),
+        artifacts: cloneArtifacts(artifacts),
+        previousGaps: previousGaps.map((gap) => ({ ...gap })),
+        context: implementerContext
+      });
+      artifacts = cloneArtifacts(implementation.artifacts);
+      const hashes = artifactHashes(artifacts);
+      const validationResults = await Promise.all(
+        spec.validationCommands.map((command) => {
+          const validationContext = makeContext(spec.id, "validator", iteration);
+          return this.options.validationRunner ? this.options.validationRunner({ ...command }, validationContext) : validationFallback(command);
+        })
+      );
+      const graderContext = makeContext(spec.id, "grader", iteration);
+      const grade = normalizeGrade(
+        spec,
+        await this.options.grader({
+          spec: cloneSpec(spec),
+          artifacts: cloneArtifacts(artifacts),
+          artifactHashes: hashes.map((hash) => ({ ...hash })),
+          validationResults: validationResults.map((result) => ({ ...result })),
+          context: graderContext
+        })
+      );
+      const gaps = grade.criteria.filter((criterion) => !criterion.passed);
+      const passed = grade.score >= spec.threshold && !requiredValidationFailed(validationResults);
+      consecutiveFailures = passed ? 0 : consecutiveFailures + 1;
+      const iterationReceipt = {
+        iteration,
+        score: grade.score,
+        passed,
+        criteria: grade.criteria,
+        gaps,
+        artifactHashes: hashes,
+        validationResults,
+        implementerContextId: implementerContext.contextId,
+        graderContextId: graderContext.contextId,
+        notes: implementation.notes,
+        summary: grade.summary
+      };
+      receipts.push(iterationReceipt);
+      if (passed) {
+        return this.buildReceipt(spec, receipts, "pass", "Outcome threshold passed.");
+      }
+      const breakerReason = circuitBreakerTripped(spec, receipts, consecutiveFailures);
+      if (breakerReason) {
+        return this.buildReceipt(spec, receipts, "circuit_breaker_failure", breakerReason);
+      }
+      previousGaps = gaps.map((gap) => ({ ...gap }));
+    }
+    return this.buildReceipt(
+      spec,
+      receipts,
+      "iteration_cap",
+      `Outcome loop stopped at iteration cap ${spec.maxIterations}.`
+    );
+  }
+  buildReceipt(spec, receipts, status, stoppedReason) {
+    const latest = receipts[receipts.length - 1];
+    return {
+      schemaVersion: OUTCOME_SCHEMA_VERSION,
+      specId: spec.id,
+      status,
+      passed: status === "pass",
+      score: latest?.score ?? 0,
+      threshold: spec.threshold,
+      iterations: receipts.length,
+      iterationCap: spec.maxIterations,
+      artifactHashes: latest?.artifactHashes ?? artifactHashes(spec.artifacts),
+      graderIdentity: { ...spec.grader },
+      validationCommands: spec.validationCommands.map((command) => ({ ...command })),
+      criteria: latest?.criteria ?? [],
+      iterationReceipts: receipts,
+      stoppedReason,
+      timestamp: (this.options.now?.() ?? /* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+};
+function runOutcomeLoop(spec, options) {
+  return new OutcomeLoop(options).run(spec);
+}
+var EXTERNAL_AGENT_RECEIPT_SCHEMA_VERSION = "1.0.0";
+var CLAUDE_MANAGED_AGENTS_PROVIDER_ID = "anthropic.claude-managed-agents";
+var CLAUDE_MANAGED_AGENTS_BETA_HEADER = "managed-agents-2026-04-01";
+function hashText(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+function hashStableJson(value) {
+  return hashText(JSON.stringify(stabilizeForHash(value)));
+}
+function createClaudeManagedAgentsSdkClient(sdk) {
+  return {
+    async createSession(input) {
+      return toManagedAgentSession(
+        await sdk.beta.sessions.create({
+          agent: input.agent,
+          environment_id: input.environmentId,
+          ...input.vaultIds ? { vault_ids: input.vaultIds.slice() } : {},
+          ...input.metadata ? { metadata: { ...input.metadata } } : {}
+        })
+      );
+    },
+    async sendUserEvent(sessionId, event) {
+      await sdk.beta.sessions.events.send(sessionId, { events: [event] });
+    },
+    async retrieveSession(sessionId) {
+      return toManagedAgentSession(await sdk.beta.sessions.retrieve(sessionId));
+    },
+    async listEvents(sessionId) {
+      return toEventList(await sdk.beta.sessions.events.list(sessionId));
+    }
+  };
+}
+function createExternalAgentReceipt(input) {
+  const events = (input.events ?? []).map(toEventReceipt);
+  const artifacts = (input.artifacts ?? []).map(toArtifactReceipt);
+  const outcomes = (input.outcomes ?? []).map(toOutcomeReceipt);
+  const inputArtifactHashes = (input.inputArtifacts ?? []).map(toArtifactReceipt);
+  const validation = (input.validation ?? []).map((result) => ({ ...result }));
+  const request = {
+    ...input.prompt ? { promptHash: hashText(input.prompt) } : {},
+    inputArtifactHashes,
+    ...input.metadata ? { metadataHash: hashStableJson(input.metadata) } : {}
+  };
+  const captureMaterial = {
+    provider: input.provider,
+    agent: input.agent,
+    session: input.session,
+    request,
+    events,
+    outcomes,
+    artifacts
+  };
+  const captureHash = hashStableJson(captureMaterial);
+  return {
+    schemaVersion: EXTERNAL_AGENT_RECEIPT_SCHEMA_VERSION,
+    receiptId: `ext_${captureHash.slice(0, 16)}`,
+    provider: input.provider,
+    ...input.taskId ? { taskId: input.taskId } : {},
+    createdAt: (input.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+    captureHash,
+    agent: { ...input.agent },
+    session: { ...input.session },
+    request,
+    events,
+    outcomes,
+    artifacts,
+    validation,
+    quarantine: {
+      state: "quarantined",
+      reason: "External agent output requires local validation before any memory promotion.",
+      localValidationRequired: input.localValidationRequired ?? true
+    },
+    persistentMemoryWriteAllowed: false,
+    ...input.metadata ? { metadata: { ...input.metadata } } : {}
+  };
+}
+function applyExternalAgentValidation(receipt, validation) {
+  const copiedValidation = validation.map((result) => ({ ...result }));
+  if (copiedValidation.length === 0) {
+    return {
+      ...receipt,
+      validation: [],
+      quarantine: {
+        state: "quarantined",
+        reason: "No local validation evidence attached.",
+        localValidationRequired: true
+      },
+      persistentMemoryWriteAllowed: false
+    };
+  }
+  const requiredFailure = copiedValidation.find((result) => result.required !== false && !result.passed);
+  return {
+    ...receipt,
+    validation: copiedValidation,
+    quarantine: {
+      state: requiredFailure ? "rejected" : "validated",
+      reason: requiredFailure ? `Required validation failed: ${requiredFailure.id ?? requiredFailure.command}.` : "Local validation passed; receipt remains memory-isolated until MemoryReceipt promotion.",
+      localValidationRequired: false
+    },
+    persistentMemoryWriteAllowed: false
+  };
+}
+function promoteExternalAgentReceipt(receipt, memoryReceipt) {
+  if (receipt.quarantine.state !== "validated") {
+    throw new Error("ExternalAgentReceipt must be locally validated before MemoryReceipt promotion.");
+  }
+  if (memoryReceipt.sourceReceiptHash !== receipt.captureHash) {
+    throw new Error("MemoryReceipt source hash must match the external agent capture hash.");
+  }
+  return {
+    ...receipt,
+    quarantine: {
+      state: "promoted",
+      reason: "Promoted by MemoryReceipt reference; adapter still has no direct memory-write capability.",
+      localValidationRequired: false,
+      memoryPromotion: { ...memoryReceipt }
+    },
+    persistentMemoryWriteAllowed: false
+  };
+}
+var ClaudeManagedAgentAdapter = class {
+  constructor(config) {
+    this.backendId = "claude-managed-agent-quarantined";
+    this.config = config;
+  }
+  async launchAndRead(request) {
+    if (!request.prompt.trim()) {
+      throw new Error("ClaudeManagedAgentAdapter.launchAndRead requires a non-empty prompt.");
+    }
+    const session = await this.config.client.createSession({
+      agent: request.agent ?? this.config.agentId,
+      environmentId: request.environmentId ?? this.config.environmentId,
+      vaultIds: request.vaultIds?.slice(),
+      metadata: request.metadata ? { ...request.metadata } : void 0
+    });
+    await this.config.client.sendUserEvent(session.id, {
+      type: "user.message",
+      content: [{ type: "text", text: request.prompt }]
+    });
+    return this.readSession({
+      sessionId: session.id,
+      taskId: request.taskId,
+      prompt: request.prompt,
+      inputArtifacts: request.inputArtifacts,
+      validation: request.validation,
+      metadata: request.metadata
+    });
+  }
+  async readSession(request) {
+    const [session, events, artifacts, outcomes] = await Promise.all([
+      this.config.client.retrieveSession(request.sessionId),
+      this.config.client.listEvents(request.sessionId),
+      this.config.client.listArtifacts?.(request.sessionId) ?? Promise.resolve([]),
+      this.config.client.listOutcomes?.(request.sessionId) ?? Promise.resolve([])
+    ]);
+    const receipt = createExternalAgentReceipt({
+      provider: this.config.provider ?? CLAUDE_MANAGED_AGENTS_PROVIDER_ID,
+      agent: {
+        id: session.agentId ?? this.config.agentId,
+        vendor: "anthropic",
+        label: "Claude Managed Agent",
+        model: this.config.model,
+        betaHeader: CLAUDE_MANAGED_AGENTS_BETA_HEADER
+      },
+      session: {
+        id: session.id,
+        status: session.status,
+        agentId: session.agentId ?? this.config.agentId,
+        environmentId: session.environmentId ?? this.config.environmentId,
+        url: session.url
+      },
+      taskId: request.taskId,
+      prompt: request.prompt,
+      inputArtifacts: request.inputArtifacts,
+      events,
+      artifacts,
+      outcomes,
+      validation: request.validation,
+      metadata: request.metadata,
+      now: this.config.now
+    });
+    return request.validation ? applyExternalAgentValidation(receipt, request.validation) : receipt;
+  }
+  async runBenchmarkCase(input) {
+    const receipt = await this.launchAndRead(input);
+    const firstOutcomeScore = receipt.outcomes.find((outcome) => typeof outcome.score === "number")?.score ?? 0;
+    const score = input.scorer ? input.scorer(receipt) : firstOutcomeScore;
+    return {
+      backendId: this.backendId,
+      receipt,
+      score,
+      passed: receipt.quarantine.state === "validated" || receipt.quarantine.state === "promoted"
+    };
+  }
+};
+function toEventReceipt(event) {
+  return {
+    ...event.id ? { id: event.id } : {},
+    type: event.type,
+    ...event.processedAt ? { processedAt: event.processedAt } : {},
+    ...event.sessionThreadId ? { sessionThreadId: event.sessionThreadId } : {},
+    ...event.summary ? { summary: event.summary } : {},
+    rawHash: hashStableJson(event)
+  };
+}
+function toArtifactReceipt(artifact) {
+  const hasContentHash = Boolean(artifact.contentHash);
+  const hasContent = artifact.content !== void 0;
+  const hash = artifact.contentHash ?? (hasContent ? hashText(artifact.content ?? "") : hashStableJson({
+    id: artifact.id,
+    path: artifact.path,
+    uri: artifact.uri,
+    type: artifact.type,
+    producer: artifact.producer
+  }));
+  return {
+    ...artifact.id ? { id: artifact.id } : {},
+    ...artifact.path ? { path: artifact.path } : {},
+    ...artifact.uri ? { uri: artifact.uri } : {},
+    type: artifact.type,
+    producer: artifact.producer,
+    ...artifact.validator ? { validator: artifact.validator } : {},
+    hash,
+    hashKind: hasContentHash || hasContent ? "sha256-content" : "sha256-descriptor"
+  };
+}
+function toOutcomeReceipt(outcome) {
+  return {
+    id: outcome.id,
+    ...typeof outcome.score === "number" ? { score: clamp01(outcome.score) } : {},
+    ...typeof outcome.passed === "boolean" ? { passed: outcome.passed } : {},
+    ...outcome.rubricHash ? { rubricHash: outcome.rubricHash } : {},
+    ...outcome.summary ? { summary: outcome.summary } : {},
+    ...outcome.criteria ? { criteriaHash: hashStableJson(outcome.criteria) } : {}
+  };
+}
+function toManagedAgentSession(value) {
+  const record = asRecord(value);
+  const id = stringField(record, ["id"]);
+  if (!id) {
+    throw new Error("Claude Managed Agents SDK response did not include a session id.");
+  }
+  return {
+    id,
+    ...stringField(record, ["status"]) ? { status: stringField(record, ["status"]) } : {},
+    ...stringField(record, ["agentId", "agent_id"]) ? { agentId: stringField(record, ["agentId", "agent_id"]) } : {},
+    ...stringField(record, ["environmentId", "environment_id"]) ? { environmentId: stringField(record, ["environmentId", "environment_id"]) } : {},
+    ...stringField(record, ["url"]) ? { url: stringField(record, ["url"]) } : {}
+  };
+}
+function toEventList(value) {
+  const list = Array.isArray(value) ? value : Array.isArray(asRecord(value).data) ? asRecord(value).data : [];
+  return list.map((event) => {
+    const record = asRecord(event);
+    return {
+      id: stringField(record, ["id"]),
+      type: stringField(record, ["type"]) ?? "unknown.event",
+      processedAt: stringField(record, ["processedAt", "processed_at"]),
+      sessionThreadId: stringField(record, ["sessionThreadId", "session_thread_id"]),
+      summary: stringField(record, ["summary"]),
+      payload: event
+    };
+  });
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function stringField(record, keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return void 0;
+}
+function clamp01(value) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(1, value));
+}
+function stabilizeForHash(value) {
+  if (value === null) return null;
+  if (Array.isArray(value)) return value.map((item) => item === void 0 ? null : stabilizeForHash(item));
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value !== "object") return value;
+  const record = value;
+  const normalized = {};
+  for (const key of Object.keys(record).sort()) {
+    const item = record[key];
+    if (item === void 0 || typeof item === "function") continue;
+    normalized[key] = stabilizeForHash(item);
+  }
+  return normalized;
+}
+
+exports.CLAUDE_MANAGED_AGENTS_BETA_HEADER = CLAUDE_MANAGED_AGENTS_BETA_HEADER;
+exports.CLAUDE_MANAGED_AGENTS_PROVIDER_ID = CLAUDE_MANAGED_AGENTS_PROVIDER_ID;
+exports.ClaudeManagedAgentAdapter = ClaudeManagedAgentAdapter;
+exports.EXTERNAL_AGENT_RECEIPT_SCHEMA_VERSION = EXTERNAL_AGENT_RECEIPT_SCHEMA_VERSION;
+exports.OUTCOME_SCHEMA_VERSION = OUTCOME_SCHEMA_VERSION;
+exports.OutcomeLoop = OutcomeLoop;
+exports.SelfImproveHarvester = SelfImproveHarvester;
+exports.applyExternalAgentValidation = applyExternalAgentValidation;
+exports.artifactHash = artifactHash;
+exports.artifactHashes = artifactHashes;
+exports.createClaudeManagedAgentsSdkClient = createClaudeManagedAgentsSdkClient;
+exports.createExternalAgentReceipt = createExternalAgentReceipt;
+exports.hashStableJson = hashStableJson;
+exports.hashText = hashText;
+exports.promoteExternalAgentReceipt = promoteExternalAgentReceipt;
+exports.runOutcomeLoop = runOutcomeLoop;
+exports.validateOutcomeSpec = validateOutcomeSpec;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/self-improvement/index.d.ts

@@ -292,51 +292,3 @@ export class SparsityMonitor {
   [key: string]: any;
 }
 export function createSparsityMonitor(config?: any): SparsityMonitor;
-
-// ── Swarm types ────────────────────────────────────────────────────────────
-export interface ISwarmConfig {
-  algorithm: 'pso' | 'aco' | 'bees' | 'hybrid';
-  populationSize: number;
-  maxIterations: number;
-  convergenceThreshold: number;
-  adaptiveSizing?: boolean;
-}
-export interface ISwarmResult {
-  bestSolution: number[];
-  bestFitness: number;
-  converged: boolean;
-  iterations: number;
-  improvementPercent: number;
-}
-export interface ISwarmCoordinator {
-  optimize(
-    agents: { id: string; capacity: number; load: number }[],
-    tasks: { id: string; complexity: number; priority: number }[],
-    config?: Partial<ISwarmConfig>
-  ): Promise<ISwarmResult>;
-  getRecommendedPopulation(problemSize: number): number;
-}
-
-// ── Swarm types ────────────────────────────────────────────────────────────
-export interface ISwarmConfig {
-  algorithm: 'pso' | 'aco' | 'bees' | 'hybrid';
-  populationSize: number;
-  maxIterations: number;
-  convergenceThreshold: number;
-  adaptiveSizing?: boolean;
-}
-export interface ISwarmResult {
-  bestSolution: number[];
-  bestFitness: number;
-  converged: boolean;
-  iterations: number;
-  improvementPercent: number;
-}
-export interface ISwarmCoordinator {
-  optimize(
-    agents: { id: string; capacity: number; load: number }[],
-    tasks: { id: string; complexity: number; priority: number }[],
-    config?: Partial<ISwarmConfig>
-  ): Promise<ISwarmResult>;
-  getRecommendedPopulation(problemSize: number): number;
-}