@personaxis/core 0.11.0

package/dist/appraisal.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Appraisal signals — what the model proposes, NOT what gets applied.
+ *
+ * Feasibility-in-small-models design (see plan/04-small-models): the model never
+ * emits a valid state mutation by hand. It emits a *structured appraisal signal*
+ * under a JSON Schema (enforceable with GBNF / json-schema constrained decoding),
+ * and the spec engine performs the clamp + governance. The model proposes
+ * signals; the code + the spec impose safety.
+ */
+import type { EvolutionView } from "./evolution-view.js";
+export type ProvenanceSource = "user" | "tool" | "internal" | "synthesis";
+export interface ProposedMutation {
+    /** Dot-notation envelope field, e.g. "mood.tone". */
+    field: string;
+    /** Signed delta; the engine clamps it to the envelope. */
+    delta: number;
+    /** One-line rationale (required for audit). */
+    reason: string;
+}
+export interface ProposedMemory {
+    /** Short, self-contained note to remember. */
+    content: string;
+    /** Where the content came from (drives trust + sensitive-action gates). */
+    source: ProvenanceSource;
+    tags?: string[];
+}
+/**
+ * A proposed QUALITATIVE self-edit to the spec's prose material (governed downstream by
+ * improvement_policy.mode + consensus verifiers + the protected-path list). The engine —
+ * not the model — decides whether it is queued, applied, or rejected.
+ */
+export interface ProposedSelfEdit {
+    /** Dot-path into the spec; only qualitative prefixes (persona_prompting.*) are honored. */
+    targetPath: string;
+    /** The proposed new value (string/array/object of prose). */
+    toValue: unknown;
+    /** One-line justification (required for audit + the rationale verifier). */
+    rationale: string;
+}
+/** A proposed stable user preference (memory.types.user_preferences). */
+export interface ProposedPreference {
+    key: string;
+    value: string;
+    rationale?: string;
+}
+export interface AppraisalSignal {
+    /** Free-text appraisal of the current situation (kept short). */
+    appraisal: string;
+    /** Proposed envelope nudges (clamped + governed downstream). */
+    mutations: ProposedMutation[];
+    /** Proposed memory writes (verified + lineage-tagged downstream). */
+    memories: ProposedMemory[];
+    /** Proposed qualitative self-edits to persona_prompting (governed by mode + consensus). */
+    selfEdits?: ProposedSelfEdit[];
+    /** Proposed stable user preferences (written only when user_preferences is enabled). */
+    preferences?: ProposedPreference[];
+    /** Model's self-reported confidence in [0,1] (drives abstain/disclose). */
+    confidence: number;
+}
+/**
+ * JSON Schema for the appraisal signal. Feed this to the local provider's
+ * constrained-decoding backend (llama.cpp json-schema / GBNF, Outlines, XGrammar)
+ * so even a <=4B model can only emit a well-formed signal.
+ */
+export declare const APPRAISAL_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["appraisal", "mutations", "memories", "confidence"];
+    readonly properties: {
+        readonly appraisal: {
+            readonly type: "string";
+            readonly maxLength: 600;
+        };
+        readonly mutations: {
+            readonly type: "array";
+            readonly maxItems: 8;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["field", "delta", "reason"];
+                readonly properties: {
+                    readonly field: {
+                        readonly type: "string";
+                    };
+                    readonly delta: {
+                        readonly type: "number";
+                        readonly minimum: -1;
+                        readonly maximum: 1;
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                        readonly maxLength: 200;
+                    };
+                };
+            };
+        };
+        readonly memories: {
+            readonly type: "array";
+            readonly maxItems: 8;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["content", "source"];
+                readonly properties: {
+                    readonly content: {
+                        readonly type: "string";
+                        readonly maxLength: 500;
+                    };
+                    readonly source: {
+                        readonly type: "string";
+                        readonly enum: readonly ["user", "tool", "internal", "synthesis"];
+                    };
+                    readonly tags: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly maxItems: 6;
+                    };
+                };
+            };
+        };
+        readonly selfEdits: {
+            readonly type: "array";
+            readonly maxItems: 4;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["targetPath", "toValue", "rationale"];
+                readonly properties: {
+                    readonly targetPath: {
+                        readonly type: "string";
+                    };
+                    readonly toValue: {};
+                    readonly rationale: {
+                        readonly type: "string";
+                        readonly maxLength: 240;
+                    };
+                };
+            };
+        };
+        readonly preferences: {
+            readonly type: "array";
+            readonly maxItems: 4;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["key", "value"];
+                readonly properties: {
+                    readonly key: {
+                        readonly type: "string";
+                    };
+                    readonly value: {
+                        readonly type: "string";
+                        readonly maxLength: 200;
+                    };
+                    readonly rationale: {
+                        readonly type: "string";
+                        readonly maxLength: 200;
+                    };
+                };
+            };
+        };
+        readonly confidence: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+        };
+    };
+};
+/**
+ * Project a JSON Schema down to the portable subset accepted by strict
+ * structured-output endpoints: keep structural keywords (`type`, `properties`,
+ * `required`, `items`, `enum`, `additionalProperties`), drop value constraints.
+ */
+export declare function portableJsonSchema(schema: unknown): unknown;
+/** Anything that can turn an observation into an appraisal signal. */
+export interface Appraiser {
+    appraise(input: AppraiseInput): Promise<AppraisalSignal>;
+}
+export interface AppraiseInput {
+    /** What just happened (provenance-tagged). */
+    observation: string;
+    source: ProvenanceSource;
+    /** The compiled persona document (identity, slot #1). */
+    personaBody: string;
+    /** Current envelope fields the model may nudge. */
+    mutableFields: string[];
+    /** Top-level spec sections the persona MAY propose qualitative self-edits to (editGate != block). */
+    editableSections?: string[];
+    /** F3.8: grounded projection of the editable surface (current values + envelopes + mode).
+     * When present, an appraiser SHOULD prefer it over the bare `mutableFields` names. */
+    evolutionView?: EvolutionView;
+}
+/** Defensive parser: coerce arbitrary JSON into a valid AppraisalSignal. */
+export declare function parseAppraisalSignal(raw: unknown): AppraisalSignal;

package/dist/appraisal.js

@@ -0,0 +1,159 @@
+/**
+ * Appraisal signals — what the model proposes, NOT what gets applied.
+ *
+ * Feasibility-in-small-models design (see plan/04-small-models): the model never
+ * emits a valid state mutation by hand. It emits a *structured appraisal signal*
+ * under a JSON Schema (enforceable with GBNF / json-schema constrained decoding),
+ * and the spec engine performs the clamp + governance. The model proposes
+ * signals; the code + the spec impose safety.
+ */
+/**
+ * JSON Schema for the appraisal signal. Feed this to the local provider's
+ * constrained-decoding backend (llama.cpp json-schema / GBNF, Outlines, XGrammar)
+ * so even a <=4B model can only emit a well-formed signal.
+ */
+export const APPRAISAL_JSON_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["appraisal", "mutations", "memories", "confidence"],
+    properties: {
+        appraisal: { type: "string", maxLength: 600 },
+        mutations: {
+            type: "array",
+            maxItems: 8,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["field", "delta", "reason"],
+                properties: {
+                    field: { type: "string" },
+                    delta: { type: "number", minimum: -1, maximum: 1 },
+                    reason: { type: "string", maxLength: 200 },
+                },
+            },
+        },
+        memories: {
+            type: "array",
+            maxItems: 8,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["content", "source"],
+                properties: {
+                    content: { type: "string", maxLength: 500 },
+                    source: { type: "string", enum: ["user", "tool", "internal", "synthesis"] },
+                    tags: { type: "array", items: { type: "string" }, maxItems: 6 },
+                },
+            },
+        },
+        selfEdits: {
+            type: "array",
+            maxItems: 4,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["targetPath", "toValue", "rationale"],
+                properties: {
+                    targetPath: { type: "string" },
+                    toValue: {},
+                    rationale: { type: "string", maxLength: 240 },
+                },
+            },
+        },
+        preferences: {
+            type: "array",
+            maxItems: 4,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["key", "value"],
+                properties: {
+                    key: { type: "string" },
+                    value: { type: "string", maxLength: 200 },
+                    rationale: { type: "string", maxLength: 200 },
+                },
+            },
+        },
+        confidence: { type: "number", minimum: 0, maximum: 1 },
+    },
+};
+/**
+ * Value-constraint keywords that hosted structured-output backends (Cohere, Groq,
+ * some Azure deployments) reject — they accept only a structural subset of JSON
+ * Schema. The spec engine re-imposes every one of these downstream (delta clamping
+ * + `parseAppraisalSignal` coercion), so dropping them from the *wire* schema costs
+ * no safety: the model still proposes, the code + spec still impose.
+ */
+const UNSUPPORTED_SCHEMA_KEYWORDS = new Set([
+    "maxLength",
+    "minLength",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "maxItems",
+    "minItems",
+    "pattern",
+    "multipleOf",
+    "format",
+]);
+/**
+ * Project a JSON Schema down to the portable subset accepted by strict
+ * structured-output endpoints: keep structural keywords (`type`, `properties`,
+ * `required`, `items`, `enum`, `additionalProperties`), drop value constraints.
+ */
+export function portableJsonSchema(schema) {
+    if (Array.isArray(schema))
+        return schema.map(portableJsonSchema);
+    if (schema && typeof schema === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(schema)) {
+            if (UNSUPPORTED_SCHEMA_KEYWORDS.has(k))
+                continue;
+            out[k] = portableJsonSchema(v);
+        }
+        return out;
+    }
+    return schema;
+}
+/** Defensive parser: coerce arbitrary JSON into a valid AppraisalSignal. */
+export function parseAppraisalSignal(raw) {
+    const o = (raw ?? {});
+    const mutations = Array.isArray(o.mutations) ? o.mutations : [];
+    const memories = Array.isArray(o.memories) ? o.memories : [];
+    const selfEdits = Array.isArray(o.selfEdits) ? o.selfEdits : [];
+    const preferences = Array.isArray(o.preferences) ? o.preferences : [];
+    return {
+        appraisal: typeof o.appraisal === "string" ? o.appraisal : "",
+        confidence: typeof o.confidence === "number" && o.confidence >= 0 && o.confidence <= 1
+            ? o.confidence
+            : 0.5,
+        mutations: mutations
+            .map((m) => m)
+            .filter((m) => typeof m.field === "string" && typeof m.delta === "number")
+            .map((m) => ({
+            field: m.field,
+            delta: m.delta,
+            reason: typeof m.reason === "string" ? m.reason : "appraisal nudge",
+        })),
+        memories: memories
+            .map((m) => m)
+            .filter((m) => typeof m.content === "string")
+            .map((m) => ({
+            content: m.content,
+            source: isSource(m.source) ? m.source : "internal",
+            tags: Array.isArray(m.tags) ? m.tags.filter((t) => typeof t === "string") : [],
+        })),
+        selfEdits: selfEdits
+            .map((s) => s)
+            .filter((s) => typeof s.targetPath === "string" && "toValue" in s && typeof s.rationale === "string")
+            .map((s) => ({ targetPath: s.targetPath, toValue: s.toValue, rationale: s.rationale })),
+        preferences: preferences
+            .map((p) => p)
+            .filter((p) => typeof p.key === "string" && typeof p.value === "string")
+            .map((p) => ({ key: p.key, value: p.value, ...(typeof p.rationale === "string" ? { rationale: p.rationale } : {}) })),
+    };
+}
+function isSource(v) {
+    return v === "user" || v === "tool" || v === "internal" || v === "synthesis";
+}

package/dist/approval.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Approval broker (FR.10 — the minimal slice of Codex's approval state
+ * machine): request → deliver → await → gate.
+ *
+ * Why a broker instead of an inline prompt: an approval must OUTLIVE a single
+ * prompt/render cycle — the agent keeps waiting while the question travels to
+ * whichever front-end answers it (TUI, dashboard, another protocol client).
+ * States are explicit and auditable; an undecided request can time out to a
+ * DENY (never to an allow).
+ */
+export type ApprovalState = "requested" | "delivered" | "decided" | "expired";
+export type BrokerDecision = "allow" | "deny";
+export interface ApprovalRequest {
+    requestId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    reason: string;
+    state: ApprovalState;
+    createdAt: string;
+    decidedAt?: string;
+    decision?: BrokerDecision;
+}
+export declare class ApprovalBroker {
+    private readonly entries;
+    /**
+     * Open a request and await its decision. `onRequest` is the delivery
+     * callback (broadcast to front-ends); when nobody decides within
+     * `timeoutMs` the request EXPIRES to a deny — fail-closed, always.
+     */
+    request(tool: string, args: Record<string, unknown>, reason: string, opts?: {
+        onRequest?: (r: ApprovalRequest) => void;
+        timeoutMs?: number;
+    }): {
+        requestId: string;
+        decision: Promise<BrokerDecision>;
+    };
+    /** Gate: resolve a pending request. False when unknown/already decided. */
+    decide(requestId: string, decision: BrokerDecision): boolean;
+    /** Requests still awaiting a decision (for a front-end's review queue). */
+    pending(): ApprovalRequest[];
+    private expire;
+}

package/dist/approval.js

@@ -0,0 +1,71 @@
+/**
+ * Approval broker (FR.10 — the minimal slice of Codex's approval state
+ * machine): request → deliver → await → gate.
+ *
+ * Why a broker instead of an inline prompt: an approval must OUTLIVE a single
+ * prompt/render cycle — the agent keeps waiting while the question travels to
+ * whichever front-end answers it (TUI, dashboard, another protocol client).
+ * States are explicit and auditable; an undecided request can time out to a
+ * DENY (never to an allow).
+ */
+import { randomUUID } from "node:crypto";
+export class ApprovalBroker {
+    entries = new Map();
+    /**
+     * Open a request and await its decision. `onRequest` is the delivery
+     * callback (broadcast to front-ends); when nobody decides within
+     * `timeoutMs` the request EXPIRES to a deny — fail-closed, always.
+     */
+    request(tool, args, reason, opts = {}) {
+        const request = {
+            requestId: randomUUID(),
+            tool,
+            args,
+            reason,
+            state: "requested",
+            createdAt: new Date().toISOString(),
+        };
+        const decision = new Promise((resolve) => {
+            const entry = { request, resolve };
+            if (opts.timeoutMs && opts.timeoutMs > 0) {
+                entry.timer = setTimeout(() => this.expire(request.requestId), opts.timeoutMs);
+                entry.timer.unref?.();
+            }
+            this.entries.set(request.requestId, entry);
+        });
+        // Delivery is the broker's job so the state transition stays honest.
+        if (opts.onRequest) {
+            request.state = "delivered";
+            opts.onRequest(request);
+        }
+        return { requestId: request.requestId, decision };
+    }
+    /** Gate: resolve a pending request. False when unknown/already decided. */
+    decide(requestId, decision) {
+        const entry = this.entries.get(requestId);
+        if (!entry || entry.request.state === "decided" || entry.request.state === "expired")
+            return false;
+        entry.request.state = "decided";
+        entry.request.decision = decision;
+        entry.request.decidedAt = new Date().toISOString();
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.resolve(decision);
+        this.entries.delete(requestId);
+        return true;
+    }
+    /** Requests still awaiting a decision (for a front-end's review queue). */
+    pending() {
+        return [...this.entries.values()].map((e) => e.request);
+    }
+    expire(requestId) {
+        const entry = this.entries.get(requestId);
+        if (!entry)
+            return;
+        entry.request.state = "expired";
+        entry.request.decision = "deny";
+        entry.request.decidedAt = new Date().toISOString();
+        entry.resolve("deny"); // fail-closed
+        this.entries.delete(requestId);
+    }
+}

package/dist/blackboard.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Blackboard multi-persona orchestration (F7 — plan/07-orchestration).
+ *
+ * The overseer doesn't hard-wire which persona does what. It posts a task to a
+ * shared blackboard; personas *volunteer* ranked by how well their declared
+ * capabilities match the task (Salemi et al., 2025 blackboard; the puppeteer
+ * orchestrator of Dang et al., 2025 picks among volunteers). This scales to a
+ * heterogeneous pool without a central registry of who-can-do-what.
+ *
+ * Everything is auditable: post → solicit (ranked) → assign → contribute → resolve,
+ * each an event on the board. The actual "work" is a pluggable worker (an LLM-backed
+ * loop in production; a stub in tests), so the orchestration is verifiable on its own.
+ */
+import type { PersonaFrontmatter } from "./persona.js";
+/**
+ * Capability tokens for a persona. Prefers the explicit, machine-readable
+ * `identity.capabilities` (v0.8); falls back to deriving them from the identity
+ * layer (purpose / allowed_domains / role) when absent.
+ */
+export declare function extractCapabilities(fm: PersonaFrontmatter): string[];
+export interface Agent {
+    id: string;
+    capabilities: string[];
+}
+export interface Volunteer {
+    id: string;
+    score: number;
+    matched: string[];
+}
+export type TaskStatus = "open" | "assigned" | "resolved";
+export interface Contribution {
+    agentId: string;
+    content: string;
+    ts: string;
+}
+export interface Task {
+    id: string;
+    description: string;
+    tokens: string[];
+    status: TaskStatus;
+    assignedTo?: string;
+    contributions: Contribution[];
+    result?: string;
+}
+export interface BoardEvent {
+    ts: string;
+    kind: "post" | "assign" | "contribute" | "resolve";
+    taskId: string;
+    detail: string;
+}
+/** Score how well an agent matches a task (Jaccard-like, recall-weighted). */
+export declare function matchScore(taskTokens: string[], capabilities: string[]): {
+    score: number;
+    matched: string[];
+};
+export declare class Blackboard {
+    private tasks;
+    readonly log: BoardEvent[];
+    private seq;
+    post(description: string): Task;
+    /** Rank the agents who could take this task (highest score first, score>0). */
+    solicit(taskId: string, agents: Agent[]): Volunteer[];
+    /** Assign to a specific agent, or auto-assign the top volunteer. */
+    assign(taskId: string, agents: Agent[], agentId?: string): Volunteer | null;
+    contribute(taskId: string, agentId: string, content: string): void;
+    resolve(taskId: string, result: string): void;
+    get(taskId: string): Task | undefined;
+    all(): Task[];
+    private require;
+    private event;
+}
+export interface OrchestrateOptions {
+    /** Pluggable worker: in production an LLM-backed loop; default a stub. */
+    worker?: (agent: Agent, task: Task) => Promise<string> | string;
+}
+export interface OrchestrateResult {
+    task: Task;
+    volunteers: Volunteer[];
+    assigned: Volunteer | null;
+    contribution?: string;
+}
+/**
+ * Run one full blackboard cycle for a task over a pool of agents (puppeteer-style:
+ * solicit volunteers, assign the best, have it contribute, resolve).
+ */
+export declare function orchestrate(board: Blackboard, description: string, agents: Agent[], opts?: OrchestrateOptions): Promise<OrchestrateResult>;