chainlesschain 0.166.18 → 0.166.21

package/src/lib/app-server/server.js

@@ -7,8 +7,12 @@ import {
   createRolloutStore,
 } from "./rollout-store-factory.js";
 import { AppServerGraphRuntime } from "./graph-runtime.js";
+import { captureAgentSkillOutcomeIndex } from "../evolution/agent-evolution-runtime-composition-brand.js";
+import { captureSkillVectorAuthority } from "../skill-vector-authority.js";
 import { compileGraphDefinition } from "../graph-kernel/compiler.js";
 import { createCliContextMemoryRuntime } from "../context-memory-kernel/runtime.js";
+import { isEvolutionWorkbenchCliHost } from "../evolution/evolution-workbench-cli-host.js";
+import { isGovernedKnowledgeReviewHost } from "../evolution/governed-knowledge-review-host.js";
 import {
   contextPlanCreatedNotification,
   memoryDeletionNotification,
@@ -145,6 +149,10 @@ export class CcAppServer {
     transport = "stdio",
     graphRuntime = null,
     evolutionCompositionFactory = null,
+    skillOutcomeIndex = null,
+    skillVectorAuthority = null,
+    evolutionWorkbenchHost = null,
+    governedKnowledgeReviewHost = null,
     contextMemoryRuntimeFactory = createCliContextMemoryRuntime,
   } = {}) {
     if (typeof send !== "function") {
@@ -166,9 +174,47 @@ export class CcAppServer {
       throw new TypeError("contextMemoryRuntimeFactory must be a function");
     }
     this.contextMemoryRuntimeFactory = contextMemoryRuntimeFactory;
-    if (graphRuntime && evolutionCompositionFactory) {
+    if (
+      evolutionWorkbenchHost !== null &&
+      !isEvolutionWorkbenchCliHost(evolutionWorkbenchHost)
+    ) {
+      throw new TypeError(
+        "CcAppServer evolutionWorkbenchHost must be a branded Workbench host",
+      );
+    }
+    this.evolutionWorkbenchHost = evolutionWorkbenchHost;
+    if (
+      governedKnowledgeReviewHost !== null &&
+      !isGovernedKnowledgeReviewHost(governedKnowledgeReviewHost)
+    ) {
+      throw new TypeError(
+        "CcAppServer governedKnowledgeReviewHost must be a branded review host",
+      );
+    }
+    this.governedKnowledgeReviewHost = governedKnowledgeReviewHost;
+    this.skillOutcomeIndex =
+      skillOutcomeIndex === null
+        ? null
+        : captureAgentSkillOutcomeIndex(skillOutcomeIndex);
+    this.skillVectorAuthority =
+      skillVectorAuthority === null
+        ? null
+        : captureSkillVectorAuthority(skillVectorAuthority);
+    if (
+      this.skillOutcomeIndex !== null &&
+      this.skillVectorAuthority !== null &&
+      this.skillOutcomeIndex.tenantId !== this.skillVectorAuthority.tenantId
+    ) {
+      throw new TypeError(
+        "App Server retrieval authorities must share one tenant",
+      );
+    }
+    if (
+      graphRuntime &&
+      (evolutionCompositionFactory || skillOutcomeIndex || skillVectorAuthority)
+    ) {
       throw new TypeError(
-        "graphRuntime and evolutionCompositionFactory cannot both be provided",
+        "graphRuntime and host-owned Graph authorities cannot both be provided",
       );
     }
     this.graphRuntime =
@@ -178,6 +224,8 @@ export class CcAppServer {
         now,
         createId,
         evolutionCompositionFactory,
+        skillOutcomeIndex: this.skillOutcomeIndex,
+        skillVectorAuthority: this.skillVectorAuthority,
         executeNode: (context) => this._executeGraphNode(context),
         requestHumanTask: (context) => this._requestHumanTask(context),
         onEvent: (event) => {
@@ -353,6 +401,18 @@ export class CcAppServer {
       "memory/decide": () => this._memoryDecide(message.params),
       "memory/delete": () => this._memoryDelete(message.params),
       "memory/reconcile": () => this._memoryReconcile(message.params),
+      "evolution/workbench/list": () =>
+        this._evolutionWorkbenchList(message.params),
+      "evolution/workbench/compare": () =>
+        this._evolutionWorkbenchCompare(message.params),
+      "evolution/workbench/review": () =>
+        this._evolutionWorkbenchReview(message.params),
+      "evolution/workbench/rollback": () =>
+        this._evolutionWorkbenchRollback(message.params),
+      "evolution/knowledge/conflicts": () =>
+        this._governedKnowledgeConflicts(message.params),
+      "evolution/knowledge/merge": () =>
+        this._governedKnowledgeMerge(message.params),
     };
     const handler = handlers[method];
     if (!handler) {
@@ -400,6 +460,20 @@ export class CcAppServer {
       websocket: { stability: "experimental" },
       limits: this.requestQueue.snapshot(),
       graphRuntime: this.graphRuntime.runtimeClaims(),
+      evolutionWorkbench: {
+        available: this.evolutionWorkbenchHost !== null,
+        methods:
+          this.evolutionWorkbenchHost === null
+            ? []
+            : ["list", "compare", "review", "rollback"],
+      },
+      governedKnowledgeReview: {
+        available: this.governedKnowledgeReviewHost !== null,
+        methods:
+          this.governedKnowledgeReviewHost === null
+            ? []
+            : ["conflicts", "merge"],
+      },
       schema: {
         id: APP_SERVER_SCHEMA.$id,
         version: APP_SERVER_PROTOCOL_VERSION,
@@ -415,6 +489,91 @@ export class CcAppServer {
     return runtime;
   }
 
+  _requireEvolutionWorkbenchHost() {
+    if (this.evolutionWorkbenchHost === null) {
+      throw new JsonRpcError(
+        JSON_RPC_ERROR.NOT_FOUND,
+        "Evolution Workbench is not configured for this App Server",
+      );
+    }
+    return this.evolutionWorkbenchHost;
+  }
+
+  _evolutionWorkbenchList(rawParams = {}) {
+    const params = requireObject(rawParams);
+    return this._requireEvolutionWorkbenchHost().list({
+      query: typeof params.query === "string" ? params.query : "",
+      status: params.status ?? null,
+      offset: params.offset ?? 0,
+      limit: params.limit ?? 100,
+    });
+  }
+
+  _evolutionWorkbenchCompare(rawParams) {
+    const params = requireObject(rawParams);
+    return this._requireEvolutionWorkbenchHost().compare(
+      requiredString(params.leftPacketDigest, "leftPacketDigest"),
+      requiredString(params.rightPacketDigest, "rightPacketDigest"),
+    );
+  }
+
+  _evolutionWorkbenchReview(rawParams) {
+    const params = requireObject(rawParams);
+    if (!Array.isArray(params.packetDigests)) {
+      throw new JsonRpcError(
+        JSON_RPC_ERROR.INVALID_PARAMS,
+        "packetDigests must be an array",
+      );
+    }
+    return this._requireEvolutionWorkbenchHost().review({
+      packetDigests: params.packetDigests,
+      decision: requiredString(params.decision, "decision"),
+      reason: requiredString(params.reason, "reason"),
+    });
+  }
+
+  _evolutionWorkbenchRollback(rawParams) {
+    const params = requireObject(rawParams);
+    return this._requireEvolutionWorkbenchHost().rollback({
+      fromPacketDigest: requiredString(
+        params.fromPacketDigest,
+        "fromPacketDigest",
+      ),
+      toPacketDigest: requiredString(params.toPacketDigest, "toPacketDigest"),
+      reason: requiredString(params.reason, "reason"),
+    });
+  }
+
+  _requireGovernedKnowledgeReviewHost() {
+    if (this.governedKnowledgeReviewHost === null) {
+      throw new JsonRpcError(
+        JSON_RPC_ERROR.NOT_FOUND,
+        "Governed knowledge review is not configured for this App Server",
+      );
+    }
+    return this.governedKnowledgeReviewHost;
+  }
+
+  _governedKnowledgeConflicts(rawParams = {}) {
+    const params = requireObject(rawParams);
+    return this._requireGovernedKnowledgeReviewHost().list({
+      cursor: params.cursor ?? 0,
+      limit: params.limit ?? 50,
+    });
+  }
+
+  _governedKnowledgeMerge(rawParams) {
+    const params = requireObject(rawParams);
+    return this._requireGovernedKnowledgeReviewHost().merge({
+      conflictEnvelopeDigest: requiredString(
+        params.conflictEnvelopeDigest,
+        "conflictEnvelopeDigest",
+      ),
+      mergedRecord: requireObject(params.mergedRecord, "mergedRecord"),
+      reason: requiredString(params.reason, "reason"),
+    });
+  }
+
   async _contextPlan(rawParams) {
     const params = requireObject(rawParams);
     const runtime = this._contextMemoryRuntime({
@@ -612,6 +771,8 @@ export class CcAppServer {
     input,
     signal,
     evolutionIngress,
+    skillOutcomeIndex,
+    skillVectorAuthority,
   }) {
     const threadId = `graph-agent:${runId}:${nodeId}`;
     const turn = { id: attempt.id, threadId };
@@ -622,9 +783,17 @@ export class CcAppServer {
     try {
       const turnOptions = { ...(input?.options || {}) };
       delete turnOptions.evolutionIngress;
+      delete turnOptions.skillOutcomeIndex;
+      delete turnOptions.skillVectorAuthority;
       if (evolutionIngress !== null && evolutionIngress !== undefined) {
         turnOptions.evolutionIngress = evolutionIngress;
       }
+      if (skillOutcomeIndex !== null && skillOutcomeIndex !== undefined) {
+        turnOptions.skillOutcomeIndex = skillOutcomeIndex;
+      }
+      if (skillVectorAuthority !== null && skillVectorAuthority !== undefined) {
+        turnOptions.skillVectorAuthority = skillVectorAuthority;
+      }
       const result = await this.kernel.startTurn({
         threadId,
         turnId: attempt.id,
@@ -866,11 +1035,20 @@ export class CcAppServer {
   async _runTurn(active, input, options) {
     const { turn } = active;
     try {
+      const turnOptions = { ...options };
+      delete turnOptions.skillOutcomeIndex;
+      delete turnOptions.skillVectorAuthority;
+      if (this.skillOutcomeIndex !== null) {
+        turnOptions.skillOutcomeIndex = this.skillOutcomeIndex;
+      }
+      if (this.skillVectorAuthority !== null) {
+        turnOptions.skillVectorAuthority = this.skillVectorAuthority;
+      }
       const result = await this.kernel.startTurn({
         threadId: turn.threadId,
         turnId: turn.id,
         input,
-        options,
+        options: turnOptions,
         emit: (event) => this._emitKernelEvent(turn, event),
         requestApproval: (event) => this._requestApproval(turn, event),
       });

package/src/lib/app-server/websocket-transport.js

@@ -398,6 +398,8 @@ export class WebSocketAppServerHost extends EventEmitter {
           kernel: this.kernelFactory?.(),
           evolutionCompositionFactory:
             this.options.evolutionCompositionFactory ?? null,
+          skillOutcomeIndex: this.options.skillOutcomeIndex ?? null,
+          skillVectorAuthority: this.options.skillVectorAuthority ?? null,
           transport: "websocket",
           maxQueuedRequests: this.options.maxQueuedRequests,
           maxQueuedRequestBytes: this.options.maxQueuedRequestBytes,

package/src/lib/evolution/agent-evolution-runtime-composition-brand.js

@@ -2,6 +2,7 @@ export const AGENT_EVOLUTION_RUNTIME_COMPOSITION_SCHEMA =
   "chainlesschain.agent-evolution-runtime-composition/v1";
 
 const COMPOSITIONS = new WeakSet();
+const SKILL_OUTCOME_INDEXES = new WeakSet();
 
 export function sealAgentEvolutionRuntimeComposition(fields) {
   const composition = Object.freeze({
@@ -20,3 +21,19 @@ export function captureAgentEvolutionRuntimeComposition(value) {
   }
   return value;
 }
+
+export function sealAgentSkillOutcomeIndex(fields) {
+  const index = Object.freeze({
+    schema: "chainlesschain.agent-skill-outcome-index/v1",
+    ...fields,
+  });
+  SKILL_OUTCOME_INDEXES.add(index);
+  return index;
+}
+
+export function captureAgentSkillOutcomeIndex(value) {
+  if (!SKILL_OUTCOME_INDEXES.has(value)) {
+    throw new TypeError("a branded Agent Skill outcome index is required");
+  }
+  return value;
+}

package/src/lib/evolution/agent-evolution-runtime-composition.js

@@ -18,11 +18,17 @@ import {
   createEvolutionLedgerFileBackend,
 } from "./evolution-ledger-file-backend.js";
 import { EvolutionRunLedgerAdapter } from "./evolution-run-ledger-adapter.js";
+import { EvolutionWorkbenchMetricsLedgerAdapter } from "./evolution-workbench-metrics-ledger-adapter.js";
+import { captureSkillOutcomeSourceCatalogAuthority } from "./skill-outcome-source-catalog-authority.js";
 import {
   captureAgentEvolutionIngress,
   createAgentEvolutionIngress,
 } from "./agent-evolution-ingress.js";
-import { sealAgentEvolutionRuntimeComposition } from "./agent-evolution-runtime-composition-brand.js";
+import {
+  captureAgentEvolutionRuntimeComposition,
+  sealAgentSkillOutcomeIndex,
+  sealAgentEvolutionRuntimeComposition,
+} from "./agent-evolution-runtime-composition-brand.js";
 
 export {
   AGENT_EVOLUTION_RUNTIME_COMPOSITION_SCHEMA,
@@ -46,6 +52,9 @@ const ARTIFACT_AUTHORITY_KEYS = new Set([
   "envelopeSigner",
   "envelopeVerifier",
 ]);
+const SKILL_OUTCOME_SOURCE_KEYS = new Set(["composition", "skillName"]);
+const SKILL_OUTCOME_CATALOG_ENTRY_KEYS = new Set(["runId", "skillNames"]);
+const MAX_SKILL_OUTCOME_SOURCES = 128;
 
 function exactRecord(value, keys, label) {
   if (
@@ -346,6 +355,27 @@ export function createAgentEvolutionRuntimeComposition({
     ledgerArtifactResolver,
     now: clock,
   });
+  const skillOutcomeReaders = new Map();
+  const createSkillOutcomeReader = Object.freeze((skillNameInput) => {
+    const skillName = identifier(skillNameInput, "skillName");
+    const cached = skillOutcomeReaders.get(skillName);
+    if (cached) return cached;
+    const reader = new EvolutionWorkbenchMetricsLedgerAdapter({
+      descriptor: {
+        tenantId,
+        artifactTenantId: tenantId,
+        evolutionRunId: runId,
+        skillName,
+        audience,
+        purpose: "evolution-ledger",
+      },
+      artifactPorts,
+      ledger: backend.ledger,
+      ledgerArtifactResolver,
+    }).createOutcomeReader();
+    skillOutcomeReaders.set(skillName, reader);
+    return reader;
+  });
   const evolutionIngress = createAgentEvolutionIngress({
     evidenceAdapter,
     runAdapter,
@@ -361,9 +391,143 @@ export function createAgentEvolutionRuntimeComposition({
     tenantId,
     runId,
     evolutionIngress,
+    createSkillOutcomeReader,
     loadRun: Object.freeze(() => runAdapter.load()),
     ledgerDescriptor: backend.descriptor,
     storage,
   });
   return composition;
 }
+
+export function assembleAgentSkillOutcomeIndex({ sources } = {}) {
+  if (
+    !Array.isArray(sources) ||
+    utilTypes.isProxy(sources) ||
+    sources.length < 1 ||
+    sources.length > MAX_SKILL_OUTCOME_SOURCES
+  ) {
+    throw new TypeError("Skill outcome index sources are invalid or unbounded");
+  }
+  let tenantId = null;
+  const sourceIds = new Set();
+  const readers = sources.map((input, index) => {
+    const source = exactRecord(
+      input,
+      SKILL_OUTCOME_SOURCE_KEYS,
+      `sources[${index}]`,
+    );
+    const composition = captureAgentEvolutionRuntimeComposition(
+      source.composition,
+    );
+    const skillName = identifier(
+      source.skillName,
+      `sources[${index}].skillName`,
+    );
+    if (tenantId === null) tenantId = composition.tenantId;
+    if (composition.tenantId !== tenantId) {
+      throw new Error("Skill outcome index sources crossed a tenant boundary");
+    }
+    const sourceId = `${composition.runId}\0${skillName}`;
+    if (sourceIds.has(sourceId)) {
+      throw new Error("Skill outcome index sources contain a duplicate");
+    }
+    sourceIds.add(sourceId);
+    if (typeof composition.createSkillOutcomeReader !== "function") {
+      throw new TypeError(
+        "Agent evolution composition lacks an outcome reader",
+      );
+    }
+    return composition.createSkillOutcomeReader(skillName);
+  });
+  return sealAgentSkillOutcomeIndex({
+    tenantId,
+    readers: Object.freeze(readers),
+  });
+}
+
+export async function assembleAgentSkillOutcomeIndexFromCatalog({
+  tenantId: tenantIdInput,
+  catalogAuthority: catalogAuthorityInput,
+  openComposition,
+} = {}) {
+  const tenantId = identifier(tenantIdInput, "tenantId");
+  const catalogAuthority = captureSkillOutcomeSourceCatalogAuthority(
+    catalogAuthorityInput,
+  );
+  if (
+    typeof openComposition !== "function" ||
+    utilTypes.isProxy(openComposition)
+  ) {
+    throw new TypeError("Skill outcome composition opener is invalid");
+  }
+  const loaded = await catalogAuthority.loadCatalog();
+  if (
+    loaded?.authenticated !== true ||
+    loaded.durable !== true ||
+    loaded.tenantId !== tenantId ||
+    !Array.isArray(loaded.entries)
+  ) {
+    throw new Error("Skill outcome source catalog authority is invalid");
+  }
+  const catalog = loaded.entries;
+  const runIds = new Set();
+  let sourceCount = 0;
+  const normalizedCatalog = catalog.map((input, index) => {
+    const entry = exactRecord(
+      input,
+      SKILL_OUTCOME_CATALOG_ENTRY_KEYS,
+      `catalog[${index}]`,
+    );
+    const runId = identifier(entry.runId, `catalog[${index}].runId`);
+    if (runIds.has(runId)) {
+      throw new TypeError(
+        "Skill outcome source catalog contains a duplicate run",
+      );
+    }
+    runIds.add(runId);
+    if (
+      !Array.isArray(entry.skillNames) ||
+      utilTypes.isProxy(entry.skillNames) ||
+      entry.skillNames.length < 1 ||
+      entry.skillNames.length > MAX_SKILL_OUTCOME_SOURCES
+    ) {
+      throw new TypeError(
+        `catalog[${index}].skillNames is invalid or unbounded`,
+      );
+    }
+    const skillNames = entry.skillNames.map((skillName, skillIndex) =>
+      identifier(skillName, `catalog[${index}].skillNames[${skillIndex}]`),
+    );
+    if (new Set(skillNames).size !== skillNames.length) {
+      throw new TypeError(
+        "Skill outcome source catalog contains a duplicate Skill",
+      );
+    }
+    sourceCount += skillNames.length;
+    if (sourceCount > MAX_SKILL_OUTCOME_SOURCES) {
+      throw new TypeError(
+        "Skill outcome source catalog is invalid or unbounded",
+      );
+    }
+    return Object.freeze({ runId, skillNames: Object.freeze(skillNames) });
+  });
+  const sources = [];
+  for (const entry of normalizedCatalog) {
+    const context = Object.freeze({ tenantId, runId: entry.runId });
+    const composition = captureAgentEvolutionRuntimeComposition(
+      await openComposition(context),
+    );
+    if (
+      composition.tenantId !== tenantId ||
+      composition.runId !== entry.runId
+    ) {
+      throw new TypeError(
+        "Skill outcome catalog opener returned an unbound composition",
+      );
+    }
+    for (const skillName of entry.skillNames) {
+      sources.push(Object.freeze({ composition, skillName }));
+    }
+  }
+  return assembleAgentSkillOutcomeIndex({ sources });
+}