@personaxis/core 0.11.0

package/dist/context.js

@@ -0,0 +1,178 @@
+/**
+ * Context-window management (the bottom-bar meter + auto-compaction).
+ *
+ * Every serious agent tracks how full the model's context window is and compacts
+ * before it overflows (Claude Code auto-compacts ~80%; Hermes shows `model │
+ * 14.4K/256K │ %`). Two hard parts handled here, model-agnostically:
+ *   1. The window VARIES per model and we won't hardcode thousands — so we resolve
+ *      it dynamically from the endpoint's `/models` (OpenRouter/Ollama expose
+ *      `context_length`), cache it, and fall back to a small pattern table.
+ *   2. Compaction must fire with HEADROOM (default 0.8): summarizing is itself a
+ *      model call that needs room for the conversation + the summary; waiting for
+ *      100% leaves no space and most providers hard-error at the limit.
+ */
+// Pattern table fallback (used when /models doesn't report a window). Conservative.
+const WINDOW_TABLE = [
+    [/command-a|command-r-plus/i, 256_000],
+    [/command-r|command/i, 128_000],
+    [/gpt-5|gpt-4\.1|o3|o4|gpt-4o-2/i, 1_000_000],
+    [/gpt-4o|gpt-4-turbo|gpt-4\b/i, 128_000],
+    [/claude/i, 200_000],
+    [/gemini/i, 1_000_000],
+    [/deepseek/i, 128_000],
+    [/qwen|llama|mistral|phi|gemma/i, 32_768],
+];
+const DEFAULT_WINDOW = 32_768;
+const cache = new Map();
+export function tableContextWindow(model) {
+    for (const [re, n] of WINDOW_TABLE)
+        if (re.test(model))
+            return n;
+    return DEFAULT_WINDOW;
+}
+/** Synchronous best-known window (cache → table). Safe for render paths. */
+export function cachedContextWindow(model) {
+    return cache.get(model) ?? tableContextWindow(model);
+}
+/**
+ * Resolve the model's context window, best-effort: query `{endpoint}/models`,
+ * read context_length/context_window, cache it; else fall back to the table.
+ * Never throws; never blocks startup beyond a short timeout.
+ */
+export async function resolveContextWindow(cfg, timeoutMs = 2500) {
+    if (cache.has(cfg.model))
+        return cache.get(cfg.model);
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), timeoutMs);
+        const res = await fetchImpl(`${cfg.endpoint.replace(/\/$/, "")}/models`, {
+            headers: cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {},
+            signal: ctrl.signal,
+        });
+        clearTimeout(t);
+        if (res.ok) {
+            const json = (await res.json());
+            const list = json.data ?? json.models ?? [];
+            const entry = list.find((m) => String(m.id ?? m.name ?? "").toLowerCase() === cfg.model.toLowerCase())
+                ?? list.find((m) => String(m.id ?? m.name ?? "").toLowerCase().includes(cfg.model.toLowerCase()));
+            const w = entry && pickWindow(entry);
+            if (typeof w === "number" && w > 0) {
+                cache.set(cfg.model, w);
+                return w;
+            }
+        }
+    }
+    catch {
+        /* network/timeout — fall through to table */
+    }
+    const t = tableContextWindow(cfg.model);
+    cache.set(cfg.model, t);
+    return t;
+}
+function pickWindow(entry) {
+    const candidates = [
+        entry.context_length,
+        entry.context_window,
+        entry.max_context_length,
+        entry.max_model_len,
+        entry.top_provider?.context_length,
+    ];
+    for (const c of candidates)
+        if (typeof c === "number" && c > 0)
+            return c;
+    return undefined;
+}
+/** Rough token estimate when the provider doesn't report usage (~4 chars/token). */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export function estimateMessagesTokens(messages) {
+    return messages.reduce((n, m) => n + estimateTokens(m.content ?? "") + 4, 0);
+}
+/**
+ * Tracks how full the context window is across a session. `used` is the size of
+ * the last prompt sent (the live context), preferring provider-reported tokens.
+ */
+export class ContextMeter {
+    limit;
+    used = 0;
+    startedAt = Date.now();
+    constructor(limit) {
+        this.limit = limit;
+    }
+    /** Record the provider's reported usage for the last call. */
+    observe(usage) {
+        if (usage?.prompt_tokens)
+            this.used = usage.prompt_tokens;
+    }
+    /** Fallback: estimate from the current message array. */
+    estimate(messages) {
+        this.used = Math.max(this.used, estimateMessagesTokens(messages));
+    }
+    get pct() {
+        return this.limit > 0 ? Math.min(1, this.used / this.limit) : 0;
+    }
+    get elapsedSeconds() {
+        return (Date.now() - this.startedAt) / 1000;
+    }
+}
+/**
+ * Compact the conversation when the meter crosses the threshold: summarize the
+ * older messages into one, keep the system message + the last N turns. The
+ * summary is produced by the model itself (Claude-Code style). Best-effort: if the
+ * summarizer call fails, returns the messages unchanged (never breaks the session).
+ */
+export async function compactMessages(messages, meter, opts) {
+    const threshold = Math.min(0.95, opts.threshold ?? 0.8);
+    const keepLastN = opts.keepLastN ?? 10;
+    if (meter.pct < threshold)
+        return { messages, compacted: false };
+    const system = messages.find((m) => m.role === "system");
+    const rest = messages.filter((m) => m !== system);
+    if (rest.length <= keepLastN + 1)
+        return { messages, compacted: false };
+    const older = rest.slice(0, rest.length - keepLastN);
+    const recent = rest.slice(rest.length - keepLastN);
+    const transcript = older
+        .map((m) => `${m.role.toUpperCase()}: ${m.content}`)
+        .join("\n")
+        .slice(0, 12000);
+    let summary;
+    try {
+        summary = await summarize(opts.llm, transcript);
+    }
+    catch {
+        return { messages, compacted: false };
+    }
+    const summaryMsg = {
+        role: "user",
+        content: `<summary>\nEarlier conversation, condensed (decisions, facts, open tasks preserved):\n${summary}\n</summary>`,
+    };
+    const next = [...(system ? [system] : []), summaryMsg, ...recent];
+    meter.used = estimateMessagesTokens(next);
+    return { messages: next, compacted: true, summary, removed: older.length };
+}
+async function summarize(cfg, transcript) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${cfg.endpoint.replace(/\/$/, "")}/chat/completions`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...(cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {}) },
+        body: JSON.stringify({
+            model: cfg.model,
+            messages: [
+                { role: "system", content: "You compress conversations. Preserve all decisions, facts, names, numbers, and open tasks. Drop pleasantries. Output ONLY the summary prose." },
+                { role: "user", content: `Summarize:\n${transcript}` },
+            ],
+            temperature: 0,
+            max_tokens: 700,
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`summarizer HTTP ${res.status}`);
+    const json = (await res.json());
+    const out = (json.choices?.[0]?.message?.content ?? "").trim();
+    if (!out)
+        throw new Error("empty summary");
+    return out;
+}

package/dist/envelopes.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Envelope discovery — the spec's bounded-mutability primitive.
+ *
+ * Every mutable runtime field (personality traits, core affect, mood — and, in
+ * v1.0, envelope-declaring drives) declares a `{ mean, range: [min, max] }`
+ * envelope in the persona frontmatter. Current values live in state.json and are
+ * clamped to these ranges on every mutation.
+ *
+ * Keys are dot-notation, identical to state.json `values` keys. Their form is
+ * version-dependent:
+ *   spec ≤ 0.10:  traits.<name> | affect.<dim> | mood.<dim>            (short, legacy)
+ *   spec 1.0:     personality.traits.<name> | affect.baseline.core_affect.<dim> |
+ *                 affect.baseline.mood.<dim> | values_and_drives.drives.<name>  (full dot-paths)
+ * `resolveField` maps either form a caller supplies onto the persona's canonical
+ * form, so `--field mood.tone` keeps working against a v1.0 persona.
+ */
+import type { PersonaFrontmatter } from "./persona.js";
+export interface Envelope {
+    mean: number;
+    min: number;
+    max: number;
+}
+export interface EnvelopeLookup {
+    envelopes: Record<string, Envelope>;
+    /** Virtues whose enforcement is "hard" — never mutable at runtime. */
+    hardEnforcedVirtues: string[];
+    /**
+     * Exact envelope KEYS that are immutable at runtime. Legacy: traits sharing a
+     * hard virtue's name. v1.0: additionally every trait a hard virtue declares in
+     * its `refs:` — the composition rule that finally makes `honesty` (virtue) protect
+     * `honesty_humility` (trait). Optional for hand-built lookups (tests): when absent
+     * the governance gate falls back to the legacy name-match rule.
+     */
+    protectedFields?: string[];
+}
+/** True when the frontmatter is a v1.0 document (spec_version 1.x / renamed layer 9). */
+export declare function isV1Frontmatter(data: PersonaFrontmatter): boolean;
+/** Short (≤0.10) prefix → full (1.0) prefix for state/envelope keys. */
+export declare const SHORT_TO_FULL: ReadonlyArray<[string, string]>;
+/**
+ * Resolve a caller-supplied field name (short or full form) onto the key the
+ * persona's envelope set actually uses. Returns the input unchanged when no
+ * mapping matches — the gate then rejects it with the exact-field message.
+ */
+export declare function resolveField(field: string, envelopes: Record<string, Envelope>): string;
+/** Position (0..width-1) of a value within its envelope — shared bar math. */
+export declare function barIndex(value: number, e: Envelope, width: number): number;
+export declare function extractEnvelopes(data: PersonaFrontmatter): EnvelopeLookup;

package/dist/envelopes.js

@@ -0,0 +1,131 @@
+/**
+ * Envelope discovery — the spec's bounded-mutability primitive.
+ *
+ * Every mutable runtime field (personality traits, core affect, mood — and, in
+ * v1.0, envelope-declaring drives) declares a `{ mean, range: [min, max] }`
+ * envelope in the persona frontmatter. Current values live in state.json and are
+ * clamped to these ranges on every mutation.
+ *
+ * Keys are dot-notation, identical to state.json `values` keys. Their form is
+ * version-dependent:
+ *   spec ≤ 0.10:  traits.<name> | affect.<dim> | mood.<dim>            (short, legacy)
+ *   spec 1.0:     personality.traits.<name> | affect.baseline.core_affect.<dim> |
+ *                 affect.baseline.mood.<dim> | values_and_drives.drives.<name>  (full dot-paths)
+ * `resolveField` maps either form a caller supplies onto the persona's canonical
+ * form, so `--field mood.tone` keeps working against a v1.0 persona.
+ */
+/** True when the frontmatter is a v1.0 document (spec_version 1.x / renamed layer 9). */
+export function isV1Frontmatter(data) {
+    const sv = data.spec_version;
+    if (typeof sv === "string" && sv.startsWith("1."))
+        return true;
+    return data.self_regulation !== undefined;
+}
+/** Short (≤0.10) prefix → full (1.0) prefix for state/envelope keys. */
+export const SHORT_TO_FULL = [
+    ["traits.", "personality.traits."],
+    ["affect.", "affect.baseline.core_affect."],
+    ["mood.", "affect.baseline.mood."],
+    ["drives.", "values_and_drives.drives."],
+];
+/**
+ * Resolve a caller-supplied field name (short or full form) onto the key the
+ * persona's envelope set actually uses. Returns the input unchanged when no
+ * mapping matches — the gate then rejects it with the exact-field message.
+ */
+export function resolveField(field, envelopes) {
+    if (field in envelopes)
+        return field;
+    for (const [short, full] of SHORT_TO_FULL) {
+        if (field.startsWith(short)) {
+            const candidate = full + field.slice(short.length);
+            if (candidate in envelopes)
+                return candidate;
+        }
+        if (field.startsWith(full)) {
+            const candidate = short + field.slice(full.length);
+            if (candidate in envelopes)
+                return candidate;
+        }
+    }
+    return field;
+}
+function readEnv(v) {
+    if (typeof v === "object" &&
+        v !== null &&
+        typeof v.mean === "number" &&
+        Array.isArray(v.range) &&
+        v.range.length === 2) {
+        const e = v;
+        return { mean: e.mean, range: e.range };
+    }
+    return null;
+}
+/** Position (0..width-1) of a value within its envelope — shared bar math. */
+export function barIndex(value, e, width) {
+    const frac = e.max === e.min ? 0.5 : (value - e.min) / (e.max - e.min);
+    return Math.max(0, Math.min(width - 1, Math.round(frac * (width - 1))));
+}
+export function extractEnvelopes(data) {
+    const envelopes = {};
+    const hardEnforcedVirtues = [];
+    const protectedFields = [];
+    const v1 = isV1Frontmatter(data);
+    const traitKey = (name) => (v1 ? `personality.traits.${name}` : `traits.${name}`);
+    const personality = data.personality;
+    for (const [name, t] of Object.entries(personality?.traits ?? {})) {
+        const e = readEnv(t);
+        if (e)
+            envelopes[traitKey(name)] = { mean: e.mean, min: e.range[0], max: e.range[1] };
+    }
+    const affect = data.affect;
+    for (const [dim, env] of Object.entries(affect?.baseline?.core_affect ?? {})) {
+        const e = readEnv(env);
+        if (e)
+            envelopes[v1 ? `affect.baseline.core_affect.${dim}` : `affect.${dim}`] = {
+                mean: e.mean,
+                min: e.range[0],
+                max: e.range[1],
+            };
+    }
+    for (const [dim, env] of Object.entries(affect?.baseline?.mood ?? {})) {
+        const e = readEnv(env);
+        if (e)
+            envelopes[v1 ? `affect.baseline.mood.${dim}` : `mood.${dim}`] = {
+                mean: e.mean,
+                min: e.range[0],
+                max: e.range[1],
+            };
+    }
+    // v1.0: a drive that declares an envelope joins the mutable surface.
+    if (v1) {
+        const vad = data.values_and_drives;
+        for (const [name, d] of Object.entries(vad?.drives ?? {})) {
+            const e = readEnv(d);
+            if (e)
+                envelopes[`values_and_drives.drives.${name}`] = { mean: e.mean, min: e.range[0], max: e.range[1] };
+        }
+    }
+    const character = data.character;
+    for (const [name, v] of Object.entries(character?.virtues ?? {})) {
+        if (v?.enforcement !== "hard")
+            continue;
+        hardEnforcedVirtues.push(name);
+        // Legacy rule: a trait sharing the hard virtue's NAME is protected.
+        const sameName = traitKey(name);
+        if (sameName in envelopes)
+            protectedFields.push(sameName);
+        // v1.0 rule: every trait the hard virtue references is protected.
+        if (v1 && Array.isArray(v.refs)) {
+            for (const ref of v.refs) {
+                if (typeof ref !== "string")
+                    continue;
+                const key = resolveField(ref, envelopes);
+                if (key in envelopes && key.includes("traits.") && !protectedFields.includes(key)) {
+                    protectedFields.push(key);
+                }
+            }
+        }
+    }
+    return { envelopes, hardEnforcedVirtues, protectedFields };
+}

package/dist/events.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Submit/event bus — engine ⟂ UI separation (the Codex pattern).
+ *
+ * The engine never prints. It emits typed events; consumers (REPL, TUI, MCP,
+ * HTTP) render them. This keeps one core reusable across every entry point.
+ */
+import type { MutationResult } from "./state-engine.js";
+import type { AppraisalSignal } from "./appraisal.js";
+import type { Verdict } from "./governance.js";
+import type { MemoryEntry } from "./memory.js";
+export type LoopEvent = {
+    type: "observe";
+    observation: string;
+    source: string;
+} | {
+    type: "appraise";
+    signal: AppraisalSignal;
+} | {
+    type: "govern";
+    verdicts: Verdict[];
+} | {
+    type: "mutate";
+    result: MutationResult;
+} | {
+    type: "memory";
+    entry: MemoryEntry;
+} | {
+    type: "memory-kind";
+    kind: "procedural" | "autobiographical" | "user_preferences" | "evaluations";
+    detail: string;
+} | {
+    type: "memory-recall";
+    kind: "episodic" | "semantic" | "procedural" | "autobiographical" | "user_preferences";
+    count: number;
+    detail?: string;
+} | {
+    type: "evaluation";
+    target: string;
+    dimension: string;
+    score: number;
+    rationale: string;
+} | {
+    type: "self-edit";
+    op: "queued" | "applied" | "rejected";
+    targetPath: string;
+    id?: string;
+    reason?: string;
+} | {
+    type: "anomaly";
+    kind: string;
+    detail: string;
+} | {
+    type: "recompile";
+    reason: string;
+} | {
+    type: "abstain";
+    reason: string;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "tick-complete";
+    mutationsApplied: number;
+    memoriesWritten: number;
+} | {
+    type: "agent-step";
+    step: number;
+} | {
+    type: "agent-think";
+    text: string;
+} | {
+    type: "tool-propose";
+    tool: string;
+    args: Record<string, unknown>;
+} | {
+    type: "tool-verdict";
+    tool: string;
+    decision: "allow" | "ask" | "deny";
+    reason: string;
+} | {
+    type: "tool-result";
+    tool: string;
+    ok: boolean;
+    output: string;
+} | {
+    type: "agent-finish";
+    summary: string;
+    steps: number;
+} | {
+    type: "agent-error";
+    message: string;
+} | {
+    type: "agent-budget";
+    step: number;
+    tokens: number;
+    costUsd: number;
+    wallSeconds: number;
+} | {
+    type: "agent-stop-condition";
+    reason: string;
+    step: number;
+} | {
+    type: "verify-start";
+    gates: number;
+} | {
+    type: "verify-result";
+    verifier: string;
+    pass: boolean;
+    reason: string;
+} | {
+    type: "verify-complete";
+    passed: boolean;
+    passes: number;
+    quorum: number;
+} | {
+    type: "trace-exported";
+    format: string;
+    path: string;
+    spanCount: number;
+} | {
+    type: "context-meter";
+    used: number;
+    limit: number;
+    pct: number;
+} | {
+    type: "context-compacted";
+    removed: number;
+    usedAfter: number;
+};
+export type LoopListener = (e: LoopEvent) => void;
+export declare class EventBus {
+    private listeners;
+    on(listener: LoopListener): () => void;
+    emit(e: LoopEvent): void;
+}

package/dist/events.js

@@ -0,0 +1,19 @@
+/**
+ * Submit/event bus — engine ⟂ UI separation (the Codex pattern).
+ *
+ * The engine never prints. It emits typed events; consumers (REPL, TUI, MCP,
+ * HTTP) render them. This keeps one core reusable across every entry point.
+ */
+export class EventBus {
+    listeners = [];
+    on(listener) {
+        this.listeners.push(listener);
+        return () => {
+            this.listeners = this.listeners.filter((l) => l !== listener);
+        };
+    }
+    emit(e) {
+        for (const l of this.listeners)
+            l(e);
+    }
+}

package/dist/evolution-view.d.ts

@@ -0,0 +1,43 @@
+/**
+ * F3.8 — the appraiser's EVOLUTION VIEW.
+ *
+ * Before this, the appraiser proposed changes blind: it saw the mutable field
+ * NAMES and the editable section names, but not the CURRENT value of each field,
+ * its envelope, or the improvement mode. So it could propose "nudge mood.tone up"
+ * without knowing mood.tone is already at the top of its range.
+ *
+ * The evolution view is the grounded projection of the editable surface: for
+ * each mutable field, its current value, envelope [min,max], and a band telling
+ * the model where the value sits and how much headroom remains; plus the
+ * improvement mode and the sections open to qualitative self-edits. The model
+ * proposes deltas against reality, and the runtime still clamps/governs/audits.
+ */
+import type { Envelope } from "./envelopes.js";
+export interface EvolutionField {
+    path: string;
+    current: number;
+    mean: number;
+    min: number;
+    max: number;
+    /** Where `current` sits in [min,max]. */
+    band: "at-min" | "low" | "mid" | "high" | "at-max";
+    /** Room to move down / up before hitting the envelope, rounded. */
+    headroomDown: number;
+    headroomUp: number;
+}
+export interface EvolutionView {
+    /** improvement_policy.mode — locked disables self-edits entirely. */
+    mode: string;
+    fields: EvolutionField[];
+    /** Top-level sections open to qualitative self-edits (editGate != block). */
+    editableSections: string[];
+}
+/** Build the grounded evolution view from current state + envelopes + mode. */
+export declare function buildEvolutionView(args: {
+    values: Record<string, number>;
+    envelopes: Record<string, Envelope>;
+    editableSections: string[];
+    mode: string;
+}): EvolutionView;
+/** Render the evolution view as compact prompt text for the appraiser. */
+export declare function renderEvolutionView(view: EvolutionView): string;

package/dist/evolution-view.js

@@ -0,0 +1,67 @@
+/**
+ * F3.8 — the appraiser's EVOLUTION VIEW.
+ *
+ * Before this, the appraiser proposed changes blind: it saw the mutable field
+ * NAMES and the editable section names, but not the CURRENT value of each field,
+ * its envelope, or the improvement mode. So it could propose "nudge mood.tone up"
+ * without knowing mood.tone is already at the top of its range.
+ *
+ * The evolution view is the grounded projection of the editable surface: for
+ * each mutable field, its current value, envelope [min,max], and a band telling
+ * the model where the value sits and how much headroom remains; plus the
+ * improvement mode and the sections open to qualitative self-edits. The model
+ * proposes deltas against reality, and the runtime still clamps/governs/audits.
+ */
+function bandOf(current, e) {
+    const span = e.max - e.min || 1;
+    const pct = (current - e.min) / span;
+    if (current <= e.min + 1e-9)
+        return "at-min";
+    if (current >= e.max - 1e-9)
+        return "at-max";
+    if (pct < 0.34)
+        return "low";
+    if (pct > 0.66)
+        return "high";
+    return "mid";
+}
+const r2 = (n) => Math.round(n * 100) / 100;
+/** Build the grounded evolution view from current state + envelopes + mode. */
+export function buildEvolutionView(args) {
+    const fields = [];
+    for (const [path, e] of Object.entries(args.envelopes)) {
+        const current = args.values[path] ?? e.mean;
+        fields.push({
+            path,
+            current: r2(current),
+            mean: r2(e.mean),
+            min: r2(e.min),
+            max: r2(e.max),
+            band: bandOf(current, e),
+            headroomDown: r2(current - e.min),
+            headroomUp: r2(e.max - current),
+        });
+    }
+    return { mode: args.mode, fields, editableSections: args.editableSections };
+}
+/** Render the evolution view as compact prompt text for the appraiser. */
+export function renderEvolutionView(view) {
+    const lines = [];
+    lines.push(`# Evolution view (improvement mode: ${view.mode})`);
+    if (view.mode === "locked") {
+        lines.push("Self-improvement is LOCKED — do not propose selfEdits; envelope nudges still allowed.");
+    }
+    lines.push("## Mutable envelope fields — current value, range, and headroom:");
+    if (view.fields.length === 0) {
+        lines.push("(none)");
+    }
+    else {
+        for (const f of view.fields) {
+            lines.push(`- ${f.path}: current ${f.current} in [${f.min}, ${f.max}] (${f.band}); ` +
+                `headroom ↓${f.headroomDown} ↑${f.headroomUp}`);
+        }
+    }
+    lines.push("## Sections open to qualitative self-edits:");
+    lines.push(view.editableSections.length ? view.editableSections.join(", ") : "(none — do not propose selfEdits)");
+    return lines.join("\n");
+}

package/dist/generated/version.d.ts

@@ -0,0 +1 @@
+export declare const CORE_VERSION = "0.11.0";

package/dist/generated/version.js

@@ -0,0 +1,2 @@
+// AUTO-GENERATED by scripts/gen-version.mjs — do not edit, do not commit.
+export const CORE_VERSION = "0.11.0";