chainlesschain 0.166.16 → 0.166.18

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

@@ -6,6 +6,7 @@ import {
 import { createGraphAuthorityBinding } from "../graph-kernel/authority.js";
 import { GraphEventStore } from "../graph-kernel/event-store.js";
 import { GraphKernel } from "../graph-kernel/runtime.js";
+import { captureAgentEvolutionRuntimeComposition } from "../evolution/agent-evolution-runtime-composition-brand.js";
 import {
   diffGraphTrace,
   locateBlockedRoot,
@@ -143,11 +144,18 @@ export class AppServerGraphRuntime {
     now = Date.now,
     createId = randomUUID,
     onEvent = null,
+    evolutionCompositionFactory = null,
     writerLeaseTtlMs = 24 * 60 * 60 * 1000,
   } = {}) {
     if (typeof executeNode !== "function") {
       throw new TypeError("AppServerGraphRuntime requires executeNode()");
     }
+    if (
+      evolutionCompositionFactory !== null &&
+      typeof evolutionCompositionFactory !== "function"
+    ) {
+      throw new TypeError("evolutionCompositionFactory must be a function");
+    }
     this.eventStore = eventStore;
     this.rolloutStore = eventStore.rolloutStore;
     this.executeNode = executeNode;
@@ -156,12 +164,88 @@ export class AppServerGraphRuntime {
     this.now = now;
     this.createId = createId;
     this.onEvent = typeof onEvent === "function" ? onEvent : null;
+    this.evolutionCompositionFactory = evolutionCompositionFactory;
     this.writerLeaseTtlMs = writerLeaseTtlMs;
     this.runs = new Map();
     this.drives = new Map();
     this.active = new Map();
   }
 
+  async _prepareEvolution(entry) {
+    if (!this.evolutionCompositionFactory) return null;
+    if (!entry.evolutionCompositionPromise) {
+      const context = Object.freeze({
+        mode: "graph",
+        runId: entry.runId,
+        originSurface: entry.originSurface,
+        revisionDigest: entry.compiled.revisionDigest,
+        authorityMode: entry.authorityMode,
+      });
+      entry.evolutionCompositionPromise = Promise.resolve()
+        .then(() => this.evolutionCompositionFactory(context))
+        .then((value) => {
+          const composition = captureAgentEvolutionRuntimeComposition(value);
+          if (composition.runId !== entry.runId) {
+            throw new TypeError(
+              "Agent evolution composition belongs to another Graph run",
+            );
+          }
+          if (
+            typeof composition.evolutionIngress?.start !== "function" ||
+            typeof composition.evolutionIngress?.complete !== "function"
+          ) {
+            throw new TypeError(
+              "Agent evolution composition has no usable ingress",
+            );
+          }
+          return composition;
+        });
+    }
+    if (!entry.evolutionStartPromise) {
+      entry.evolutionStartPromise = entry.evolutionCompositionPromise.then(
+        async (composition) => {
+          await composition.evolutionIngress.start();
+          return composition;
+        },
+      );
+    }
+    try {
+      return await entry.evolutionStartPromise;
+    } catch (cause) {
+      entry.evolutionIngressFailed = true;
+      if (cause?.code === "CC_AGENT_EVOLUTION_INGRESS_FAILED") throw cause;
+      const error = runtimeError(
+        "CC_AGENT_EVOLUTION_INGRESS_FAILED",
+        `Graph evolution ingress failed: ${cause?.message || String(cause)}`,
+        { cause },
+      );
+      throw error;
+    }
+  }
+
+  async _completeEvolution(entry) {
+    if (!this.evolutionCompositionFactory || entry.evolutionIngressFailed) {
+      return;
+    }
+    if (entry.evolutionCompletionPromise) {
+      return entry.evolutionCompletionPromise;
+    }
+    try {
+      entry.evolutionCompletionPromise = this._prepareEvolution(entry).then(
+        (composition) => composition.evolutionIngress.complete(),
+      );
+      await entry.evolutionCompletionPromise;
+    } catch (cause) {
+      entry.evolutionIngressFailed = true;
+      if (cause?.code === "CC_AGENT_EVOLUTION_INGRESS_FAILED") throw cause;
+      throw runtimeError(
+        "CC_AGENT_EVOLUTION_INGRESS_FAILED",
+        `Graph evolution completion failed: ${cause?.message || String(cause)}`,
+        { cause },
+      );
+    }
+  }
+
   _requestThread(runId) {
     return `graph-request:${graphDigest(
       runId,
@@ -329,6 +413,8 @@ export class AppServerGraphRuntime {
       runId: id,
       compiled,
       inputs: { ...inputs },
+      originSurface,
+      authorityMode,
     });
     this._emit(id, "graph/run-started", { projection });
     return this.status(id);
@@ -339,9 +425,16 @@ export class AppServerGraphRuntime {
     if (projection.authorityMode === "shadow") {
       return Promise.resolve(this.status(projection.id));
     }
-    const settled = this._drive(projection.id);
-    if (options.waitForCompletion === true) return settled;
-    return Promise.resolve(projection);
+    const entry = this.runs.get(projection.id);
+    const launch = () => {
+      const settled = this._drive(projection.id);
+      if (options.waitForCompletion === true) return settled;
+      return projection;
+    };
+    if (this.evolutionCompositionFactory) {
+      return this._prepareEvolution(entry).then(launch);
+    }
+    return Promise.resolve(launch());
   }
 
   resume(runId, { waitForCompletion = false } = {}) {
@@ -375,12 +468,15 @@ export class AppServerGraphRuntime {
     if (!entry)
       throw runtimeError("CC_GRAPH_RUN_NOT_FOUND", "Graph run missing");
     const { kernel } = entry;
+    await this._prepareEvolution(entry);
     for (let steps = 0; steps < 10_000; steps += 1) {
       const status = kernel.getRun(runId);
-      if (
-        TERMINAL.has(status.status) ||
-        status.status === "reconciliation_required"
-      ) {
+      if (TERMINAL.has(status.status)) {
+        await this._completeEvolution(entry);
+        this._emit(runId, "graph/run-settled", { projection: status });
+        return status;
+      }
+      if (status.status === "reconciliation_required") {
         this._emit(runId, "graph/run-settled", { projection: status });
         return status;
       }
@@ -562,6 +658,7 @@ export class AppServerGraphRuntime {
   async _executeAttempt(entry, nodeId) {
     const { kernel } = entry;
     const runId = entry.runId;
+    const evolutionComposition = await this._prepareEvolution(entry);
     const attempt = kernel.assignNode(runId, nodeId, "app-server-agent", {
       ttlMs: this.writerLeaseTtlMs,
       leaseId: `app-server-attempt:${this.createId()}`,
@@ -595,6 +692,7 @@ export class AppServerGraphRuntime {
         attempt,
         input: nodeInput(entry.inputs, nodeId),
         signal: controller.signal,
+        evolutionIngress: evolutionComposition?.evolutionIngress || null,
       });
       if (!result || !["succeeded", "completed"].includes(result.status)) {
         const error = runtimeError(
@@ -631,6 +729,9 @@ export class AppServerGraphRuntime {
       });
       return settled;
     } catch (error) {
+      if (error?.code === "CC_AGENT_EVOLUTION_INGRESS_FAILED") {
+        entry.evolutionIngressFailed = true;
+      }
       if (controller.signal.aborted) return kernel.getRun(runId);
       if (effect) {
         const known = error?.outcomeKnown === true;
@@ -826,6 +927,8 @@ export class AppServerGraphRuntime {
       runId,
       compiled: compileGraphDefinition(request.definition),
       inputs: { ...request.inputs },
+      originSurface: request.originSurface,
+      authorityMode: request.authorityMode,
     };
     this.runs.set(runId, entry);
     this._recoverReceiptedAttempts(entry);
@@ -1003,7 +1106,7 @@ export class AppServerGraphRuntime {
   async cancel(runId, reason = "cancelled by App Server client") {
     const id = String(runId);
     const entry = this.runs.get(id) || this._recover(id);
-    return entry.kernel.cancelRun(id, {
+    const projection = await entry.kernel.cancelRun(id, {
       reason,
       interrupt: async (attempt) => {
         const active = this.active.get(attempt.id);
@@ -1012,6 +1115,10 @@ export class AppServerGraphRuntime {
         await active.done;
       },
     });
+    if (TERMINAL.has(projection.status)) {
+      await this._completeEvolution(entry);
+    }
+    return projection;
   }
 
   async reconcile(runId, input = {}) {

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

@@ -144,6 +144,7 @@ export class CcAppServer {
     interruptSettlementMs = 30_000,
     transport = "stdio",
     graphRuntime = null,
+    evolutionCompositionFactory = null,
     contextMemoryRuntimeFactory = createCliContextMemoryRuntime,
   } = {}) {
     if (typeof send !== "function") {
@@ -165,12 +166,18 @@ export class CcAppServer {
       throw new TypeError("contextMemoryRuntimeFactory must be a function");
     }
     this.contextMemoryRuntimeFactory = contextMemoryRuntimeFactory;
+    if (graphRuntime && evolutionCompositionFactory) {
+      throw new TypeError(
+        "graphRuntime and evolutionCompositionFactory cannot both be provided",
+      );
+    }
     this.graphRuntime =
       graphRuntime ||
       new AppServerGraphRuntime({
         rolloutStore: resolvedStore,
         now,
         createId,
+        evolutionCompositionFactory,
         executeNode: (context) => this._executeGraphNode(context),
         requestHumanTask: (context) => this._requestHumanTask(context),
         onEvent: (event) => {
@@ -598,7 +605,14 @@ export class CcAppServer {
     );
   }
 
-  async _executeGraphNode({ runId, nodeId, attempt, input, signal }) {
+  async _executeGraphNode({
+    runId,
+    nodeId,
+    attempt,
+    input,
+    signal,
+    evolutionIngress,
+  }) {
     const threadId = `graph-agent:${runId}:${nodeId}`;
     const turn = { id: attempt.id, threadId };
     const onAbort = () => {
@@ -606,11 +620,16 @@ export class CcAppServer {
     };
     signal?.addEventListener?.("abort", onAbort, { once: true });
     try {
+      const turnOptions = { ...(input?.options || {}) };
+      delete turnOptions.evolutionIngress;
+      if (evolutionIngress !== null && evolutionIngress !== undefined) {
+        turnOptions.evolutionIngress = evolutionIngress;
+      }
       const result = await this.kernel.startTurn({
         threadId,
         turnId: attempt.id,
         input: requiredString(input?.prompt, `inputs.${nodeId}.prompt`),
-        options: input?.options || {},
+        options: turnOptions,
         emit: (event) =>
           this._notify("graph/event", {
             type: "graph/agent-event",

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

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

package/src/lib/evolution/agent-evolution-ingress.js

@@ -0,0 +1,300 @@
+import crypto from "node:crypto";
+import evolutionRun from "@chainlesschain/session-core/evolution-run";
+
+import { EvolutionEvidenceArtifactAdapter } from "./evolution-evidence-artifact-adapter.js";
+import { EvolutionRunLedgerAdapter } from "./evolution-run-ledger-adapter.js";
+import { captureEvolutionRunWikiMaintenanceProducer } from "./evolution-run-wiki-maintenance-source.js";
+import { WIKI_MAINTENANCE_TRIGGER_KIND } from "./wiki-maintenance-trigger-ledger-adapter.js";
+
+const { EVOLUTION_RUN_EVENT_SCHEMA, EVENT_TYPES } = evolutionRun;
+
+export const AGENT_EVOLUTION_INGRESS_SCHEMA =
+  "chainlesschain.agent-evolution-ingress/v1";
+export const AGENT_EVOLUTION_INGRESS_FAILED_CODE =
+  "CC_AGENT_EVOLUTION_INGRESS_FAILED";
+
+const INGRESSES = new WeakSet();
+const CORE_EVENT_KINDS = new Map([
+  ["tool-executing", "tool-requested"],
+  ["tool-result", "tool-completed"],
+  ["tool-error", "tool-failed"],
+  ["response-complete", "response-completed"],
+  ["run-ended", "goal-ended"],
+]);
+
+function requiredString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${label} is required`);
+  }
+  return value;
+}
+
+function canonical(value) {
+  if (value === null || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("Agent evolution evidence must be finite JSON");
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") return JSON.stringify(value);
+  if (!value || typeof value !== "object") {
+    throw new TypeError("Agent evolution evidence must be JSON-compatible");
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonical).join(",")}]`;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError("Agent evolution evidence must use plain objects");
+  }
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+    .join(",")}}`;
+}
+
+function clone(value) {
+  return JSON.parse(canonical(value));
+}
+
+function digest(value) {
+  return `sha256:${crypto.createHash("sha256").update(canonical(value)).digest("hex")}`;
+}
+
+function timestamp(value, label) {
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime()) || date.toISOString() !== value) {
+    throw new TypeError(`${label} must be a canonical timestamp`);
+  }
+  return value;
+}
+
+function normalizeId(value, label) {
+  const result = requiredString(value, label);
+  if (Buffer.byteLength(result, "utf8") > 256) {
+    throw new TypeError(`${label} is too long`);
+  }
+  return result;
+}
+
+function guardIngress(operation) {
+  return Promise.resolve(operation).catch((cause) => {
+    if (cause?.code === AGENT_EVOLUTION_INGRESS_FAILED_CODE) throw cause;
+    const error = new Error(
+      `Agent evolution ingress failed: ${cause?.message || String(cause)}`,
+      { cause },
+    );
+    error.code = AGENT_EVOLUTION_INGRESS_FAILED_CODE;
+    throw error;
+  });
+}
+
+export function createAgentEvolutionIngress({
+  evidenceAdapter,
+  runAdapter,
+  sourceEnvelopeAuthority,
+  wikiMaintenanceProducer = null,
+  completionTriggerKind = WIKI_MAINTENANCE_TRIGGER_KIND.SESSION_END,
+  now = () => new Date(),
+  idGenerator = () => crypto.randomUUID(),
+} = {}) {
+  if (!(evidenceAdapter instanceof EvolutionEvidenceArtifactAdapter)) {
+    throw new TypeError("an EvolutionEvidenceArtifactAdapter is required");
+  }
+  if (!(runAdapter instanceof EvolutionRunLedgerAdapter)) {
+    throw new TypeError("an EvolutionRunLedgerAdapter is required");
+  }
+  if (typeof sourceEnvelopeAuthority?.issue !== "function") {
+    throw new TypeError("sourceEnvelopeAuthority.issue is required");
+  }
+  if (typeof now !== "function" || typeof idGenerator !== "function") {
+    throw new TypeError("ingress clock and idGenerator must be functions");
+  }
+  const maintenanceProducer =
+    wikiMaintenanceProducer === null
+      ? null
+      : captureEvolutionRunWikiMaintenanceProducer(wikiMaintenanceProducer);
+  if (
+    ![
+      WIKI_MAINTENANCE_TRIGGER_KIND.SESSION_END,
+      WIKI_MAINTENANCE_TRIGGER_KIND.GOAL_END,
+    ].includes(completionTriggerKind)
+  ) {
+    throw new TypeError(
+      "Agent completion trigger kind must be session-end or goal-end",
+    );
+  }
+  const issueSourceEnvelope = sourceEnvelopeAuthority.issue.bind(
+    sourceEnvelopeAuthority,
+  );
+  const descriptor = runAdapter.descriptor;
+  let tail = Promise.resolve();
+
+  const serialize = (operation) => {
+    const pending = tail.then(operation, operation);
+    tail = pending.catch(() => undefined);
+    return pending;
+  };
+
+  const currentTimestamp = () => {
+    const value = now();
+    const iso = value instanceof Date ? value.toISOString() : value;
+    return timestamp(iso, "ingress timestamp");
+  };
+
+  const appendStarted = () => {
+    const loaded = runAdapter.load();
+    if (loaded.events.length > 0) return loaded.projection;
+    const occurredAt = currentTimestamp();
+    return runAdapter.appendEvent({
+      schema: EVOLUTION_RUN_EVENT_SCHEMA,
+      tenantId: descriptor.tenantId,
+      runId: descriptor.runId,
+      eventId: `${descriptor.runId}:started`,
+      sequence: 1,
+      type: EVENT_TYPES.RUN_STARTED,
+      subjectId: descriptor.runId,
+      payloadDigest: digest({ occurredAt, runtime: "agent" }),
+      artifactRef: null,
+      keyRef: null,
+      data: { occurredAt, runtime: "agent" },
+    }).projection;
+  };
+
+  const ingest = (kind, evidence, options = {}) =>
+    guardIngress(
+      serialize(async () => {
+        const projection = appendStarted();
+        if (projection.status === "completed") {
+          throw new Error(
+            "completed EvolutionRun cannot accept Agent evidence",
+          );
+        }
+        const eventId = normalizeId(
+          options.eventId ?? `agent:${idGenerator()}`,
+          "Agent evidence eventId",
+        );
+        const occurredAt = timestamp(
+          options.occurredAt ?? currentTimestamp(),
+          "Agent evidence occurredAt",
+        );
+        const payload = clone(evidence);
+        const sourceEnvelope = await issueSourceEnvelope(
+          Object.freeze({
+            schema: AGENT_EVOLUTION_INGRESS_SCHEMA,
+            tenantId: descriptor.tenantId,
+            runId: descriptor.runId,
+            eventId,
+            kind,
+            occurredAt,
+            evidence: payload,
+          }),
+        );
+        const persisted = await evidenceAdapter.projectAndPersist({
+          sourceEnvelope,
+          payload,
+        });
+        if (
+          persisted?.tenantId !== descriptor.tenantId ||
+          persisted.evidenceId == null ||
+          persisted.manifest?.type !== "evidence" ||
+          typeof persisted.manifest.ref?.ref !== "string"
+        ) {
+          throw new Error(
+            "Agent evidence persistence returned an unbound result",
+          );
+        }
+        const current = runAdapter.load();
+        return runAdapter.appendEvent({
+          schema: EVOLUTION_RUN_EVENT_SCHEMA,
+          tenantId: descriptor.tenantId,
+          runId: descriptor.runId,
+          eventId,
+          sequence: current.events.length + 1,
+          type: EVENT_TYPES.RAW_EVENT_REFERENCED,
+          subjectId: persisted.evidenceId,
+          payloadDigest: persisted.manifest.digest,
+          artifactRef: persisted.manifest.ref.ref,
+          keyRef: null,
+          data: {
+            evidenceKind: kind,
+            occurredAt,
+            derivationManifestDigest: persisted.manifest.digest,
+          },
+        });
+      }),
+    );
+
+  const ingress = Object.freeze({
+    schema: AGENT_EVOLUTION_INGRESS_SCHEMA,
+    tenantId: descriptor.tenantId,
+    runId: descriptor.runId,
+    start: () => guardIngress(serialize(() => appendStarted())),
+    ingestUserPrompt: (input, options) =>
+      ingest("user-prompt", { input: clone(input) }, options),
+    ingestAgentEvent: (event, options) => {
+      const baseKind = CORE_EVENT_KINDS.get(event?.type);
+      if (!baseKind) {
+        return Promise.resolve(Object.freeze({ ignored: true }));
+      }
+      const kind =
+        event.type === "tool-result" &&
+        Boolean(event.error || event.result?.error || event.result?.isError)
+          ? "tool-failed"
+          : baseKind;
+      return ingest(kind, { event: clone(event) }, options);
+    },
+    complete: (options = {}) =>
+      guardIngress(
+        serialize(async () => {
+          const loaded = runAdapter.load();
+          let projection;
+          if (loaded.projection?.status === "completed") {
+            projection = loaded.projection;
+          } else {
+            if (loaded.events.length === 0) appendStarted();
+            const current = runAdapter.load();
+            const occurredAt = timestamp(
+              options.occurredAt ?? currentTimestamp(),
+              "Agent completion occurredAt",
+            );
+            projection = runAdapter.appendEvent({
+              schema: EVOLUTION_RUN_EVENT_SCHEMA,
+              tenantId: descriptor.tenantId,
+              runId: descriptor.runId,
+              eventId: `${descriptor.runId}:completed`,
+              sequence: current.events.length + 1,
+              type: EVENT_TYPES.RUN_COMPLETED,
+              subjectId: descriptor.runId,
+              payloadDigest: digest({ occurredAt, status: "completed" }),
+              artifactRef: null,
+              keyRef: null,
+              data: { occurredAt, status: "completed" },
+            }).projection;
+          }
+          if (maintenanceProducer !== null) {
+            await maintenanceProducer.enqueueCompletedRun({
+              kind: completionTriggerKind,
+              runId: descriptor.runId,
+            });
+          }
+          return projection;
+        }),
+      ),
+  });
+  INGRESSES.add(ingress);
+  return ingress;
+}
+
+export function captureAgentEvolutionIngress(value, options = {}) {
+  if (!INGRESSES.has(value)) {
+    throw new TypeError("a branded Agent evolution ingress is required");
+  }
+  if (options.tenantId != null && value.tenantId !== options.tenantId) {
+    throw new TypeError("Agent evolution ingress belongs to another tenant");
+  }
+  return value;
+}

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

@@ -0,0 +1,22 @@
+export const AGENT_EVOLUTION_RUNTIME_COMPOSITION_SCHEMA =
+  "chainlesschain.agent-evolution-runtime-composition/v1";
+
+const COMPOSITIONS = new WeakSet();
+
+export function sealAgentEvolutionRuntimeComposition(fields) {
+  const composition = Object.freeze({
+    schema: AGENT_EVOLUTION_RUNTIME_COMPOSITION_SCHEMA,
+    ...fields,
+  });
+  COMPOSITIONS.add(composition);
+  return composition;
+}
+
+export function captureAgentEvolutionRuntimeComposition(value) {
+  if (!COMPOSITIONS.has(value)) {
+    throw new TypeError(
+      "a branded Agent evolution runtime composition is required",
+    );
+  }
+  return value;
+}