talon-agent 4.6.1 → 5.0.1

package/src/core/soul/retrieve.ts

@@ -1,146 +0,0 @@
-/**
- * Soul Kernel — context-conditioned retrieval.
- *
- * Grounded in Park et al., "Generative Agents: Interactive Simulacra of Human
- * Behavior" (2023), whose memory retrieval scores each record by a normalized
- * sum of three signals: recency, importance, and relevance to the current
- * moment. We adapt it to value retrieval so the projected soul is the part of
- * identity that is *relevant right now*, not just globally salient:
- *
- *   recency     — decayed salience (already the kernel's "weather").
- *   importance  — how core the value is: confidence magnitude + how connected it
- *                 is in the Hebbian lattice (degree centrality). Central,
- *                 well-evidenced values matter regardless of the moment.
- *   relevance   — cosine similarity between the value's medoid and the current
- *                 context embedding (0 when no context is supplied).
- *
- * Each component is min-max normalized to [0,1] across the candidate set (as in
- * the paper) before the weighted sum, so no single signal's scale dominates.
- * Still model-free: scores are arithmetic over embeddings and counts.
- */
-
-import type { SoulDag } from "./dag.js";
-import { isSuperseded } from "./consolidate.js";
-import { cosineSimilarity, type Embedder } from "./embedder.js";
-import { confidence, effectiveSalience } from "./salience.js";
-import type { Hash, SoulConfig, ValuePayload } from "./types.js";
-import { halfLifeForKind } from "./types.js";
-
-export interface RetrievalWeights {
-  readonly recency: number;
-  readonly importance: number;
-  readonly relevance: number;
-}
-
-const DEFAULT_RETRIEVAL_WEIGHTS: RetrievalWeights = {
-  recency: 1,
-  importance: 1,
-  relevance: 1,
-};
-
-export interface RetrievedValue {
-  readonly hash: Hash;
-  readonly score: number;
-  readonly recency: number;
-  readonly importance: number;
-  readonly relevance: number;
-}
-
-export interface RetrieveOptions {
-  readonly now: number;
-  readonly config: SoulConfig;
-  /** Current-moment text; its embedding drives the relevance term. */
-  readonly context?: string;
-  readonly weights?: RetrievalWeights;
-  /**
-   * Optional precomputed centrality (e.g. PageRank) used for the importance
-   * term. When absent, importance falls back to log-degree centrality.
-   */
-  readonly centrality?: ReadonlyMap<Hash, number>;
-}
-
-function medoidText(dag: SoulDag, valueHash: Hash): string | undefined {
-  const node = dag.getNode(valueHash);
-  if (node?.payload.kind !== "value") return undefined;
-  const medoid = dag.getNode((node.payload as ValuePayload).medoid);
-  return medoid?.payload.kind === "evidence" ? medoid.payload.text : undefined;
-}
-
-/** Degree centrality: total coactivation edge weight incident to a node. */
-function centrality(dag: SoulDag, hash: Hash): number {
-  let sum = 0;
-  for (const e of dag.edgesFrom(hash, "coactivation")) sum += e.weight;
-  return sum;
-}
-
-function minMax(values: number[]): (x: number) => number {
-  const lo = Math.min(...values);
-  const hi = Math.max(...values);
-  const span = hi - lo;
-  return (x) => (span <= 0 ? 0 : (x - lo) / span);
-}
-
-/**
- * Rank live values by the Generative-Agents composite score. Async because the
- * relevance term embeds the medoids and the context together.
- */
-export async function retrieveValues(
-  dag: SoulDag,
-  embedder: Embedder,
-  opts: RetrieveOptions,
-): Promise<RetrievedValue[]> {
-  const weights = opts.weights ?? DEFAULT_RETRIEVAL_WEIGHTS;
-  const values = dag
-    .nodesOfKind("value")
-    .filter((n) => !isSuperseded(dag, n.hash));
-
-  const rows = values
-    .map((n) => ({ hash: n.hash, text: medoidText(dag, n.hash) }))
-    .filter((r): r is { hash: Hash; text: string } => !!r.text);
-  if (rows.length === 0) return [];
-
-  const rawRecency = rows.map((r) =>
-    effectiveSalience(
-      dag.stateOf(r.hash),
-      opts.now,
-      halfLifeForKind(opts.config, "value"),
-    ),
-  );
-  const rawImportance = rows.map((r) => {
-    const conf = Math.abs(confidence(dag.stateOf(r.hash)));
-    const struct = opts.centrality
-      ? (opts.centrality.get(r.hash) ?? 0)
-      : Math.log1p(centrality(dag, r.hash));
-    return conf + struct;
-  });
-
-  // Relevance via one embed call over [context, ...medoids].
-  let rawRelevance = rows.map(() => 0);
-  if (opts.context) {
-    const vecs = await embedder.embed([
-      opts.context,
-      ...rows.map((r) => r.text),
-    ]);
-    const ctx = vecs[0]!;
-    rawRelevance = rows.map((_, i) =>
-      Math.max(0, cosineSimilarity(ctx, vecs[i + 1]!)),
-    );
-  }
-
-  const nR = minMax(rawRecency);
-  const nI = minMax(rawImportance);
-  const nV = minMax(rawRelevance);
-
-  return rows
-    .map((r, i) => {
-      const recency = nR(rawRecency[i]!);
-      const importance = nI(rawImportance[i]!);
-      const relevance = nV(rawRelevance[i]!);
-      const score =
-        weights.recency * recency +
-        weights.importance * importance +
-        weights.relevance * relevance;
-      return { hash: r.hash, score, recency, importance, relevance };
-    })
-    .sort((a, b) => b.score - a.score || a.hash.localeCompare(b.hash));
-}

package/src/core/soul/salience.ts

@@ -1,146 +0,0 @@
-/**
- * Soul Kernel — salience dynamics. "The soul has weather."
- *
- * This is the entire learning mechanism, and it is pure arithmetic — no model,
- * no embedder, just counters, exponential decay, and a delta rule. Four forces:
- *
- *   - decay        salience halves over a half-life of disuse, so stale
- *                  fixations fade from projection without being deleted.
- *   - reinforce    activation under a positive signal raises salience and
- *                  accumulates signed evidence.
- *   - coactivate   Hebbian: nodes that fire together in a successful interaction
- *                  strengthen their mutual edge ("fire together, wire together").
- *   - prediction   the soul predicts how loud a node should be; a correction is
- *     error        a large prediction error and updates proportionally.
- *
- * Decay is applied LAZILY: stored salience is always "salience as of
- * lastActivatedAt", and the effective value at any later instant is computed on
- * read. This means no global sweep is ever required — reading the soul is O(1)
- * per node, and writing only touches the nodes actually involved.
- */
-
-import type { SoulDag } from "./dag.js";
-import { retrievability } from "./forgetting.js";
-import type { ActivationState, Hash } from "./types.js";
-
-/** Exponential decay multiplier for an elapsed interval given a half-life. */
-export function decayFactor(elapsedMs: number, halfLifeMs: number): number {
-  if (elapsedMs <= 0 || halfLifeMs <= 0) return elapsedMs <= 0 ? 1 : 0;
-  return Math.pow(0.5, elapsedMs / halfLifeMs);
-}
-
-/**
- * Salience as it stands *now*, after lazy time-decay from its last activation.
- * When the node carries an FSRS stability, decay follows the power-law
- * retrievability curve; otherwise it is the fixed-half-life exponential. An
- * infinite half-life (a no-decay node kind, e.g. reflexes) short-circuits both
- * paths: the stored salience is returned untouched.
- */
-export function effectiveSalience(
-  state: ActivationState,
-  now: number,
-  halfLifeMs: number,
-): number {
-  if (!Number.isFinite(halfLifeMs)) return state.salience;
-  if (state.stability !== undefined) {
-    return (
-      state.salience *
-      retrievability(now - state.lastActivatedAt, state.stability)
-    );
-  }
-  return state.salience * decayFactor(now - state.lastActivatedAt, halfLifeMs);
-}
-
-/**
- * Confidence in a node, squashed from its net evidence into (-1, 1). Positive
- * means behavior expressing it has been rewarded; negative means corrected.
- * tanh keeps a runaway counter from ever dominating.
- */
-export function confidence(state: ActivationState): number {
-  return Math.tanh(state.evidence / 4);
-}
-
-export interface ReinforceOptions {
-  readonly now: number;
-  readonly halfLifeMs: number;
-  /** Salience increment for this activation (>= 0). */
-  readonly amount: number;
-  /** Signed evidence delta: positive for reward, negative for a correction. */
-  readonly valence: number;
-}
-
-/**
- * Activation under a behavioral signal. Decays the stored salience to `now`
- * first (so the additive bump composes correctly with time), then adds the
- * increment and accumulates signed evidence.
- */
-export function reinforce(
-  dag: SoulDag,
-  hash: Hash,
-  opts: ReinforceOptions,
-): void {
-  const s = dag.stateOf(hash);
-  s.salience = effectiveSalience(s, opts.now, opts.halfLifeMs) + opts.amount;
-  s.evidence += opts.valence;
-  s.activations += 1;
-  s.lastActivatedAt = opts.now;
-  dag.touch(hash);
-}
-
-/**
- * Hebbian co-activation over the set of nodes active in one interaction.
- * Strengthens a symmetric coactivation edge for every unordered pair. The
- * Lattice's affinity/tension structure self-organizes from these counts — no
- * model decides which values relate, the statistics do.
- */
-export function coactivate(
-  dag: SoulDag,
-  hashes: readonly Hash[],
-  opts: { now: number; increment: number },
-): void {
-  const list = [...new Set(hashes)];
-  for (let i = 0; i < list.length; i++) {
-    for (let j = i + 1; j < list.length; j++) {
-      const a = list[i]!;
-      const b = list[j]!;
-      for (const [from, to] of [
-        [a, b],
-        [b, a],
-      ] as const) {
-        const e = dag.edge(from, "coactivation", to, opts.now);
-        e.weight += opts.increment;
-        e.updatedAt = opts.now;
-      }
-    }
-  }
-}
-
-export interface PredictionErrorOptions {
-  readonly now: number;
-  readonly halfLifeMs: number;
-  /** How strongly the observed signal corrects the prediction, in (0, 1]. */
-  readonly learningRate: number;
-}
-
-/**
- * Predictive-coding update. The soul holds a prediction of how salient a node
- * should be (its decayed salience); the realized `observed` signal yields an
- * error, and salience moves a learningRate-fraction of the way toward it.
- * Returns the error so callers can route large surprises into the Spine as
- * developmental events. Salience is floored at 0.
- */
-export function applyPredictionError(
-  dag: SoulDag,
-  hash: Hash,
-  observed: number,
-  opts: PredictionErrorOptions,
-): number {
-  const s = dag.stateOf(hash);
-  const predicted = effectiveSalience(s, opts.now, opts.halfLifeMs);
-  const error = observed - predicted;
-  s.salience = Math.max(0, predicted + opts.learningRate * error);
-  s.activations += 1;
-  s.lastActivatedAt = opts.now;
-  dag.touch(hash);
-  return error;
-}

package/src/core/soul/service.ts

@@ -1,204 +0,0 @@
-/**
- * Soul Kernel — runtime service (the harness integration seam).
- *
- * A single gated entry point the rest of Talon talks to, so the kernel's
- * internals stay decoupled from the frontend/runtime. The service is OFF unless
- * the deployment opts in (`TALON_SOUL_ENABLED`); when off, every method is an
- * inert no-op and nothing about Talon's behavior changes.
- *
- * Construction is synchronous and race-free: the kernel loads from disk (or
- * genesis) with `readFileSync`, and the static projection used in the system
- * prompt is synchronous too. Only the maintenance `dream` (which embeds) is
- * async, so it runs off the hot path on a schedule.
- *
- * Responsibilities:
- *   - render the projected identity surface for the system prompt,
- *   - accept behavioral signals (reactions today; more taps to follow),
- *   - evaluate reflexes for the turn-end guard,
- *   - run the periodic `dream` and persist.
- */
-
-import { existsSync } from "node:fs";
-import { files } from "../../util/paths.js";
-import { log, logError } from "../../util/log.js";
-import { SoulKernel } from "./kernel.js";
-import { TalonEmbedder } from "./talon-embedder.js";
-import { resolveSoulSettings, type SoulSettings } from "./settings.js";
-import {
-  evaluateReflexes,
-  isBlocked,
-  type ReflexContext,
-  type ReflexVerdict,
-} from "./reflex.js";
-import { explainDelta } from "./delta.js";
-import type { Embedder } from "./embedder.js";
-import type { Hash, ReflexPayload } from "./types.js";
-
-export class SoulService {
-  readonly enabled: boolean;
-  private readonly embedder: Embedder = new TalonEmbedder();
-  private lastActive: Hash[] = [];
-
-  private constructor(
-    private readonly kernel: SoulKernel | null,
-    private readonly path: string,
-  ) {
-    this.enabled = kernel !== null;
-  }
-
-  /**
-   * Build the service from settings. Disabled deployments get an inert instance;
-   * enabled ones load the persisted kernel (or genesis a fresh one). A corrupt
-   * store degrades to genesis rather than crashing the bot.
-   */
-  static create(override?: Partial<SoulSettings>): SoulService {
-    const settings = resolveSoulSettings(override);
-    const path = settings.path ?? files.soul;
-    if (!settings.enabled) return new SoulService(null, path);
-
-    let kernel: SoulKernel;
-    try {
-      kernel = existsSync(path) ? SoulKernel.load(path) : SoulKernel.genesis();
-      log("soul", `loaded kernel (${existsSync(path) ? "disk" : "genesis"})`);
-    } catch (err) {
-      logError("soul", `kernel load failed, starting fresh: ${String(err)}`);
-      kernel = SoulKernel.genesis();
-    }
-    return new SoulService(kernel, path);
-  }
-
-  // ── Prompt surface ───────────────────────────────────────────────────────────
-
-  /**
-   * The projected identity surface to inject into the system prompt, or "" when
-   * disabled. Records the surfaced values as "active" so a later reaction can be
-   * credited to exactly what was on stage.
-   */
-  renderPromptSection(): string {
-    if (!this.kernel) return "";
-    const projection = this.kernel.project();
-    this.lastActive = [...projection.includedValues];
-    return projection.text;
-  }
-
-  // ── Signal taps ──────────────────────────────────────────────────────────────
-
-  /** A reaction to Talon's message → reinforce/penalize the values on stage. */
-  recordReaction(emoji: string, at = Date.now()): void {
-    if (!this.kernel) return;
-    this.kernel.ingest({
-      kind: "reaction",
-      at,
-      emoji,
-      activeNodes: this.lastActive,
-    });
-    this.persist();
-  }
-
-  /** An explicit instruction about how to be → stored as verbatim evidence. */
-  recordDirective(text: string, actor?: string, at = Date.now()): void {
-    if (!this.kernel) return;
-    this.kernel.ingest({
-      kind: "directive",
-      at,
-      text,
-      ...(actor ? { actor } : {}),
-    });
-    this.persist();
-  }
-
-  /** A correction → verbatim evidence + Spine event + penalize active values. */
-  recordCorrection(text: string, actor?: string, at = Date.now()): void {
-    if (!this.kernel) return;
-    this.kernel.ingest({
-      kind: "correction",
-      at,
-      text,
-      activeNodes: this.lastActive,
-      ...(actor ? { actor } : {}),
-    });
-    this.persist();
-  }
-
-  // ── Reflex guard ─────────────────────────────────────────────────────────────
-
-  /** Evaluate the kernel's reflexes for a decision point. Empty when disabled. */
-  reflexCheck(ctx: ReflexContext): ReflexVerdict[] {
-    if (!this.kernel) return [];
-    const reflexes = this.kernel
-      .graph()
-      .nodesOfKind("reflex")
-      .map((n) => n.payload as ReflexPayload);
-    return evaluateReflexes(reflexes, ctx);
-  }
-
-  /** Convenience: does any reflex block this decision point? */
-  isBlocked(ctx: ReflexContext): boolean {
-    return isBlocked(this.reflexCheck(ctx));
-  }
-
-  // ── Maintenance ──────────────────────────────────────────────────────────────
-
-  /** The periodic organic pass: crystallize → consolidate → reflect, then persist. */
-  async dream(): Promise<void> {
-    if (!this.kernel) return;
-    try {
-      const summary = await this.kernel.dream(this.embedder);
-      this.kernel.commit("dream");
-      this.persist();
-      log(
-        "soul",
-        `dream: +${summary.crystallized} values, ${summary.consolidated.created.length} merged, ${summary.themes} themes`,
-      );
-    } catch (err) {
-      logError("soul", `dream failed: ${String(err)}`);
-    }
-  }
-
-  // ── Introspection (/soul) ────────────────────────────────────────────────────
-
-  /** Human-readable current identity + last delta, for the `/soul` command. */
-  introspect(): string {
-    if (!this.kernel) return "Soul is disabled.";
-    const head = this.kernel.head();
-    const projection = this.kernel.project();
-    const lines = [
-      projection.text,
-      "",
-      `_version ${this.kernel.history().length}, ${this.kernel.graph().size} nodes_`,
-    ];
-    if (head) lines.push(`_last change: ${head.summary}_`);
-    const delta = explainDelta(this.kernel.delta());
-    if (delta !== "no structural change")
-      lines.push("", "Recent changes:", delta);
-    return lines.join("\n");
-  }
-
-  private persist(): void {
-    if (!this.kernel) return;
-    try {
-      this.kernel.save(this.path);
-    } catch (err) {
-      logError("soul", `persist failed: ${String(err)}`);
-    }
-  }
-}
-
-// ── Module singleton ─────────────────────────────────────────────────────────
-
-let instance: SoulService | null = null;
-
-/** The process-wide soul service (lazily created from env settings). */
-export function getSoul(): SoulService {
-  return (instance ??= SoulService.create());
-}
-
-/** Replace the singleton (tests / explicit settings). */
-export function setSoul(service: SoulService): void {
-  instance = service;
-}
-
-/** Drop the singleton so the next getSoul() rebuilds it. */
-export function resetSoul(): void {
-  instance = null;
-}

package/src/core/soul/settings.ts

@@ -1,47 +0,0 @@
-/**
- * Soul Kernel — runtime gate.
- *
- * The soul is OFF by default. It is an experimental identity substrate; no
- * deployment should grow one unless it explicitly opts in. Our own Talon flips
- * `enabled` on (so the kernel accumulates from day one, ready for when the
- * harness wiring lands); every other deployment stays inert.
- *
- * Resolution order: explicit settings argument → env (`TALON_SOUL_ENABLED`) →
- * default false. When the harness config system grows a `soul` block, it should
- * feed it through `resolveSoulSettings`, keeping this the single gate.
- */
-
-export interface SoulSettings {
-  /** Master switch. Default false everywhere except our Talon. */
-  readonly enabled: boolean;
-  /** Path to the persisted kernel; defaults under the workspace when wired. */
-  readonly path?: string;
-}
-
-export const DEFAULT_SOUL_SETTINGS: SoulSettings = { enabled: false };
-
-function envFlag(name: string): boolean | undefined {
-  const v = process.env[name];
-  if (v === undefined) return undefined;
-  return /^(1|true|yes|on)$/i.test(v.trim());
-}
-
-/**
- * Resolve effective settings. An explicit `enabled` always wins; otherwise the
- * env flag; otherwise disabled. Keeping this pure makes it trivially testable and
- * keeps the "default off" guarantee in one place.
- */
-export function resolveSoulSettings(
-  override?: Partial<SoulSettings>,
-): SoulSettings {
-  const enabled = override?.enabled ?? envFlag("TALON_SOUL_ENABLED") ?? false;
-  return {
-    enabled,
-    ...(override?.path ? { path: override.path } : {}),
-  };
-}
-
-/** True when the soul should run in this deployment. */
-export function soulEnabled(override?: Partial<SoulSettings>): boolean {
-  return resolveSoulSettings(override).enabled;
-}

package/src/core/soul/signals.ts

@@ -1,117 +0,0 @@
-/**
- * Soul Kernel — behavioral signals: the fuel.
- *
- * The compiler never reads a transcript and forms an opinion. It consumes
- * *structured* events the harness already emits — reactions, whether a
- * conversation continued or died, corrections, reflex fires. Interpretation has
- * already happened by the time a signal exists, so turning experience into
- * identity stays mechanical.
- *
- * Each outcome signal carries the `activeNodes` that were surfaced in the
- * projection for that turn. That is what closes the loop: project → which values
- * were live → what happened → reinforce or penalize exactly those values.
- */
-
-import type { Hash } from "./types.js";
-
-interface ReactionSignal {
-  readonly kind: "reaction";
-  readonly at: number;
-  readonly emoji: string;
-  /** Value nodes that were live in the projection for the reacted-to turn. */
-  readonly activeNodes: readonly Hash[];
-}
-
-interface EngagementSignal {
-  readonly kind: "engagement";
-  readonly at: number;
-  /** Did the conversation continue after Talon's message, or die? */
-  readonly continued: boolean;
-  readonly activeNodes: readonly Hash[];
-  /**
-   * Categorical cues observed in the interaction (e.g. emojis used). When
-   * present, the outcome teaches each cue's learned valence — meaning comes from
-   * data, not a hardcoded table.
-   */
-  readonly cues?: readonly string[];
-}
-
-export interface CorrectionSignal {
-  readonly kind: "correction";
-  readonly at: number;
-  /** The verbatim correction — stored as ground-truth evidence. */
-  readonly text: string;
-  readonly actor?: string;
-  readonly ref?: string;
-  /** Values that were live when the correction landed (penalized). */
-  readonly activeNodes?: readonly Hash[];
-}
-
-export interface DirectiveSignal {
-  readonly kind: "directive";
-  readonly at: number;
-  /** Verbatim instruction about how to be — stored as evidence. */
-  readonly text: string;
-  readonly actor?: string;
-  readonly ref?: string;
-}
-
-interface ReflexFireSignal {
-  readonly kind: "reflex-fire";
-  readonly at: number;
-  readonly name: string;
-  readonly severity: "block" | "warn" | "advise";
-}
-
-interface ActivationSignal {
-  readonly kind: "activation";
-  readonly at: number;
-  readonly activeNodes: readonly Hash[];
-}
-
-export type Signal =
-  | ReactionSignal
-  | EngagementSignal
-  | CorrectionSignal
-  | DirectiveSignal
-  | ReflexFireSignal
-  | ActivationSignal;
-
-const POSITIVE = new Set([
-  "👍",
-  "❤",
-  "❤️",
-  "🔥",
-  "🎉",
-  "💯",
-  "🥰",
-  "👏",
-  "😁",
-  "🤩",
-  "🙏",
-  "👌",
-  "🤝",
-  "🫡",
-  "😍",
-  "🆒",
-  "💘",
-]);
-const NEGATIVE = new Set([
-  "👎",
-  "😡",
-  "🤬",
-  "💩",
-  "🤮",
-  "😢",
-  "🖕",
-  "🥱",
-  "🥴",
-  "😴",
-]);
-
-/** Map an emoji reaction to a signed valence in {-1, 0, +1}. */
-export function emojiValence(emoji: string): number {
-  if (POSITIVE.has(emoji)) return 1;
-  if (NEGATIVE.has(emoji)) return -1;
-  return 0;
-}