@personaxis/sdk 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Personaxis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @personaxis/sdk
+
+Embed a living, governed persona in a Node/TypeScript backend.
+
+This is the **embed SDK**: it runs the personaxis engine **in your process** (Modo 2 self-host), so
+your app owns the model, the state, and the data. It is a thin, typed wrapper over
+[`@personaxis/core`](../core) — the engine already does the governance (clamp + audit + injection
+scan + hash-chained memory + the governance gate); this package gives your app a small, obvious API.
+
+## Where this fits (the SDK strategy)
+
+Like Anthropic/OpenAI, personaxis has **two kinds of SDK**, one per deployment mode:
+
+| SDK kind | What it does | Package | Status |
+|---|---|---|---|
+| **Embed SDK** | Runs the engine **in-process** (your backend, your model) | `@personaxis/sdk` (this) — TS, in the monorepo | **Shipping** |
+| **API-client SDK** | Calls the **managed SaaS** HTTP API (like `anthropic`/`openai` clients) | separate repos, one per language (`personaxis-python`, …) | With the SaaS (future) |
+
+The TS embed SDK lives in this monorepo because the whole toolchain is TS and it depends directly on
+`@personaxis/core`. Per-language **API-client** SDKs are separate repos (the professional pattern:
+`anthropic-sdk-typescript`, `anthropic-sdk-python`, … are each their own repo) and wrap the SaaS
+HTTP surface — they arrive with the managed SaaS.
+
+## Install
+
+```bash
+npm add @personaxis/sdk   # (or pnpm/yarn) — depends on @personaxis/core
+```
+
+## Use
+
+```ts
+import { Persona } from "@personaxis/sdk";
+
+const persona = new Persona("./.personaxis/personas/support/personaxis.md");
+
+// 1) Load the identity as system-prompt slot #1 for YOUR LLM call.
+const systemPrompt = persona.compiledIdentity();
+
+// 2) Learn from an interaction on your configured model (env > project > global config).
+await persona.observe("the customer is frustrated about a double charge", "user");
+
+// 3) Read / nudge the runtime dials (clamped + audited).
+const { values } = persona.state();
+persona.adjust("mood.tone", -0.1, "customer frustrated");
+
+// 4) Verify integrity (hash-chained memory, anomaly detection).
+const audit = persona.audit();
+```
+
+## API
+
+- `new Persona(personaPath)` — bind to a `personaxis.md` (its `state.json` + memory live alongside).
+- `compiledIdentity(): string` — the compiled `PERSONA.md` (falls back to the spec body).
+- `state(): { values, recentMutations }` — current envelope dials + recent audited mutations.
+- `observe(observation, source?): Promise<{ report, events, recompilePending }>` — one governed
+  Living-Loop tick on the resolved model (heuristic fallback offline).
+- `adjust(field, delta, reason)` — a single clamped, audited mutation.
+- `audit(): { mutationCount, memoryEntries, memoryChainIntact, anomalies }`.
+- `reload()` — re-read the spec after an external recompile/decompile.
+
+## Config & secrets
+
+The model/key resolve through the same layered config the CLI uses (`resolveModel`: env > project >
+global; the key from the env var named by `apiKeyEnv`). In production the key comes from your deploy's
+secret manager — never a file. See the CLI's [configuration guide](../../docs/configuration.md) and
+[deployment modes](../../docs/architecture/deployment.md).

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @personaxis/sdk — the SINGLE engine façade (F3.5).
+ *
+ * Embed a living, governed persona in a Node/TS backend (Modo 2 self-host). The
+ * engine (@personaxis/core) does the governance — clamp + audit + injection scan
+ * + hash-chained memory + the agent loop; this SDK is the ONE ergonomic surface
+ * that drives it, with full parity across state, evolution, memory, agent, and
+ * safety operations. The MCP server, `serve`, and the REPL consume this façade
+ * rather than re-wrapping core (end of the wrapper triplication): host-specific
+ * concerns (MCP path-confinement, HTTP shaping, REPL rendering) wrap the SDK,
+ * they do not re-implement the engine.
+ *
+ * Example:
+ *   import { Persona } from "@personaxis/sdk";
+ *   const persona = new Persona("./.personaxis/personas/support/personaxis.md");
+ *   const systemPrompt = persona.compiledIdentity();          // system-prompt slot #1
+ *   await persona.observe("the customer is frustrated about billing", "user");
+ *   const { values } = persona.state();
+ */
+import { applyMutation, reviewSkill, scanForInjection, scanAgentConfig, evaluateCommand, type LoopEvent, type ProvenanceSource } from "@personaxis/core";
+export interface ObserveResult {
+    report: {
+        mutationsApplied: number;
+        memoriesWritten: number;
+        abstained: boolean;
+    };
+    events: LoopEvent[];
+    /** True if a governed self-edit left the compiled PERSONA.md stale (call `personaxis compile`). */
+    recompilePending: boolean;
+}
+export interface PersonaStateView {
+    values: Record<string, number>;
+    recentMutations: unknown[];
+}
+export interface PersonaAuditView {
+    mutationCount: number;
+    memoryEntries: number;
+    memoryChainIntact: boolean;
+    memoryChainBrokenAt: number | null;
+    anomalies: unknown[];
+}
+export interface AgentRunResult {
+    result: unknown;
+    events: LoopEvent[];
+    trace: unknown[];
+}
+/** A live persona bound to its `personaxis.md` spec (its state.json + memory live alongside it). */
+export declare class Persona {
+    readonly personaPath: string;
+    private handle;
+    constructor(personaPath: string);
+    private fm;
+    /** The compiled, LLM-facing identity document (system-prompt slot #1). Falls back to the spec
+     * body if PERSONA.md hasn't been compiled yet. */
+    compiledIdentity(): string;
+    /** The raw qualitative spec body (the compiled document as stored on the spec). */
+    compiledBody(): string;
+    /** Current runtime state: envelope values + the last few audited mutations. */
+    state(): PersonaStateView;
+    /** The mutable surface: envelope fields + the hard-enforced virtues that are immutable. */
+    envelopes(): {
+        mutableFields: Record<string, unknown>;
+        hardEnforcedVirtues: unknown;
+    };
+    /**
+     * Run ONE governed Living-Loop cycle on an observation, on the persona's resolved model
+     * (falls back to the deterministic heuristic appraiser if no model is configured). Every mutation
+     * is clamped + audited; a malicious observation is injection-scanned and cannot steer evolution.
+     */
+    observe(observation: string, source?: ProvenanceSource): Promise<ObserveResult>;
+    /** Apply a single clamped, audited mutation to an envelope field (the spec's adjust_persona_state). */
+    adjust(field: string, delta: number, reason: string): ReturnType<typeof applyMutation>;
+    /**
+     * Run the governed Agent Loop on a task. Non-interactive: any tool whose verdict is `ask` is
+     * denied unless the persona's permissions allow-list pre-authorizes it. Requires a configured model.
+     */
+    agentRun(task: string, opts?: {
+        maxSteps?: number;
+        onApproval?: () => Promise<"deny" | "approve">;
+    }): Promise<AgentRunResult | {
+        error: string;
+    }>;
+    /** Integrity view: mutation count, memory size, hash-chain validity, detected anomalies. */
+    audit(): PersonaAuditView;
+    /** Honor deletion_policy.user_request_supported: tombstone a memory entry (retrieval removal). */
+    forget(targetHash: string, reason: string): {
+        tombstoned: string;
+        by: string;
+        liveEntries: number;
+    };
+    /** Propose a governed self-edit (queued or applied per improvement_policy.mode). */
+    proposeEdit(targetPath: string, toValue: unknown, rationale: string, sources?: ProvenanceSource[]): Record<string, unknown>;
+    /** Pending self-edit proposals + the active applied overlay. */
+    listProposals(): {
+        proposals: unknown;
+        activeOverlay: unknown;
+    };
+    /**
+     * Decide a pending proposal. `approver` MUST differ from the proposer (proposer≠approver);
+     * hosts pass their own identity so the audit trail is meaningful.
+     */
+    decideEdit(id: string, decision: "approve" | "reject", approver: string): Record<string, unknown>;
+    /** Whether the compiled PERSONA.md is stale (a governed self-edit was applied since the last compile). */
+    recompileStatus(): {
+        recompilePending: boolean;
+        reason: string | null;
+        since: string | null;
+    };
+    /** Reload the spec from disk (e.g. after an external recompile/decompile). */
+    reload(): void;
+}
+/** Scan untrusted text for prompt-injection before it reaches a persona. */
+export declare function scanText(text: string): ReturnType<typeof scanForInjection>;
+/** Scan an agent config file's content for injection/poisoning (kind inferred from the filename). */
+export declare function scanConfig(content: string, filename?: string): ReturnType<typeof scanAgentConfig>;
+/** Security-review a skill before use (supply-chain defense). */
+export declare function skillReview(skillPath: string): ReturnType<typeof reviewSkill>;
+/**
+ * Evaluate a shell command against a two-axis (approval × sandbox) policy. With a persona path, the
+ * persona's OWN declared `permissions` posture is used (v0.8); otherwise the explicit args apply.
+ */
+export declare function evaluateCmd(command: string, sandbox: "read-only" | "workspace-write" | "danger-full-access", approval: "untrusted" | "on-failure" | "on-request" | "never", personaPath?: string): ReturnType<typeof evaluateCommand>;
+export { resolveModel } from "@personaxis/core";

package/dist/index.js

@@ -0,0 +1,196 @@
+/**
+ * @personaxis/sdk — the SINGLE engine façade (F3.5).
+ *
+ * Embed a living, governed persona in a Node/TS backend (Modo 2 self-host). The
+ * engine (@personaxis/core) does the governance — clamp + audit + injection scan
+ * + hash-chained memory + the agent loop; this SDK is the ONE ergonomic surface
+ * that drives it, with full parity across state, evolution, memory, agent, and
+ * safety operations. The MCP server, `serve`, and the REPL consume this façade
+ * rather than re-wrapping core (end of the wrapper triplication): host-specific
+ * concerns (MCP path-confinement, HTTP shaping, REPL rendering) wrap the SDK,
+ * they do not re-implement the engine.
+ *
+ * Example:
+ *   import { Persona } from "@personaxis/sdk";
+ *   const persona = new Persona("./.personaxis/personas/support/personaxis.md");
+ *   const systemPrompt = persona.compiledIdentity();          // system-prompt slot #1
+ *   await persona.observe("the customer is frustrated about billing", "user");
+ *   const { values } = persona.state();
+ */
+import { LivingLoop, HeuristicAppraiser, LlmAppraiser, resolveModel, PersonaAgent, EventBus, Tracer, readObservability, loadPersona, readState, writeState, withStateLock, ensureState, extractEnvelopes, resolveField, applyMutation, readMemory, readLiveMemory, tombstoneMemory, verifyMemoryChain, detectMemoryAnomalies, readMode, proposeSelfEdit, applySelfEdit, rejectSelfEdit, proposals, activeOverlay, readRecompilePending, reviewSkill, scanForInjection, scanAgentConfig, detectKind, evaluateCommand, policyFromFrontmatter, readAgentBudget, readVerification, DEFAULT_POLICY, } from "@personaxis/core";
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** A live persona bound to its `personaxis.md` spec (its state.json + memory live alongside it). */
+export class Persona {
+    personaPath;
+    handle;
+    constructor(personaPath) {
+        this.personaPath = resolve(personaPath);
+        this.handle = loadPersona(this.personaPath);
+        ensureState(this.handle);
+    }
+    fm() {
+        return this.handle.frontmatter;
+    }
+    /** The compiled, LLM-facing identity document (system-prompt slot #1). Falls back to the spec
+     * body if PERSONA.md hasn't been compiled yet. */
+    compiledIdentity() {
+        const compiled = join(dirname(this.personaPath), "PERSONA.md");
+        return existsSync(compiled) ? readFileSync(compiled, "utf-8") : this.handle.body;
+    }
+    /** The raw qualitative spec body (the compiled document as stored on the spec). */
+    compiledBody() {
+        return this.handle.body;
+    }
+    /** Current runtime state: envelope values + the last few audited mutations. */
+    state() {
+        const st = readState(this.handle.statePath);
+        return { values: st.values, recentMutations: st.mutation_log.slice(-5) };
+    }
+    /** The mutable surface: envelope fields + the hard-enforced virtues that are immutable. */
+    envelopes() {
+        const { envelopes, hardEnforcedVirtues } = extractEnvelopes(this.handle.frontmatter);
+        return { mutableFields: envelopes, hardEnforcedVirtues };
+    }
+    /**
+     * Run ONE governed Living-Loop cycle on an observation, on the persona's resolved model
+     * (falls back to the deterministic heuristic appraiser if no model is configured). Every mutation
+     * is clamped + audited; a malicious observation is injection-scanned and cannot steer evolution.
+     */
+    async observe(observation, source = "user") {
+        const m = resolveModel({ personaPath: this.personaPath, frontmatter: this.fm() });
+        const events = [];
+        const loop = new LivingLoop(this.personaPath, {
+            appraiser: m ? new LlmAppraiser({ ...m, timeoutMs: 30_000 }) : new HeuristicAppraiser(),
+        });
+        loop.bus.on((e) => events.push(e));
+        try {
+            const report = await loop.tick({ observation, source });
+            return { report, events, recompilePending: readRecompilePending(this.personaPath).pending };
+        }
+        catch (e) {
+            return {
+                report: { mutationsApplied: 0, memoriesWritten: 0, abstained: true },
+                events: [...events, { type: "error", message: e.message }],
+                recompilePending: readRecompilePending(this.personaPath).pending,
+            };
+        }
+    }
+    /** Apply a single clamped, audited mutation to an envelope field (the spec's adjust_persona_state). */
+    adjust(field, delta, reason) {
+        const env = extractEnvelopes(this.handle.frontmatter);
+        const resolved = resolveField(field, env.envelopes);
+        // Locked read→apply→write: an embedding app may run ticks/adjusts concurrently (F1.4).
+        return withStateLock(this.handle.statePath, () => {
+            const st = readState(this.handle.statePath);
+            const result = applyMutation(st, env.envelopes, { field: resolved, delta, reason, actor: "actor-llm" });
+            writeState(this.handle.statePath, st);
+            return result;
+        });
+    }
+    /**
+     * Run the governed Agent Loop on a task. Non-interactive: any tool whose verdict is `ask` is
+     * denied unless the persona's permissions allow-list pre-authorizes it. Requires a configured model.
+     */
+    async agentRun(task, opts = {}) {
+        const fm = this.fm();
+        const llm = resolveModel({ personaPath: this.personaPath, frontmatter: fm });
+        if (!llm) {
+            return { error: "agent requires a configured model (config.json local.endpoint/model or PERSONAXIS_ENDPOINT + PERSONAXIS_MODEL)" };
+        }
+        const events = [];
+        const bus = new EventBus();
+        bus.on((e) => events.push(e));
+        const agent = new PersonaAgent({
+            llm,
+            policy: policyFromFrontmatter(fm, process.cwd()),
+            personaBody: this.handle.body,
+            onApproval: opts.onApproval ?? (async () => "deny"),
+            maxSteps: opts.maxSteps ?? 12,
+            budget: readAgentBudget(fm),
+            verification: readVerification(fm),
+            judge: llm,
+            personaPath: this.personaPath,
+            bus,
+        });
+        const obs = readObservability(fm);
+        const tracer = obs.trace !== "off" ? new Tracer(bus, obs) : null;
+        const result = await agent.run(task);
+        const trace = tracer ? tracer.write(this.personaPath).paths : [];
+        tracer?.stop();
+        return { result, events, trace };
+    }
+    /** Integrity view: mutation count, memory size, hash-chain validity, detected anomalies. */
+    audit() {
+        const st = readState(this.handle.statePath);
+        const mem = readMemory(this.personaPath);
+        const chain = verifyMemoryChain(this.personaPath);
+        return {
+            mutationCount: st.mutation_log.length,
+            memoryEntries: mem.length,
+            memoryChainIntact: chain.ok,
+            memoryChainBrokenAt: chain.brokenAt ?? null,
+            anomalies: detectMemoryAnomalies(mem),
+        };
+    }
+    /** Honor deletion_policy.user_request_supported: tombstone a memory entry (retrieval removal). */
+    forget(targetHash, reason) {
+        const entry = tombstoneMemory(this.personaPath, targetHash, reason);
+        return { tombstoned: targetHash, by: entry.hash, liveEntries: readLiveMemory(this.personaPath).length };
+    }
+    /** Propose a governed self-edit (queued or applied per improvement_policy.mode). */
+    proposeEdit(targetPath, toValue, rationale, sources = ["user"]) {
+        const mode = readMode(this.fm(), this.personaPath);
+        const result = proposeSelfEdit(this.personaPath, { targetPath, toValue, rationale, sources }, mode);
+        return { ...result, recompilePending: readRecompilePending(this.personaPath).pending };
+    }
+    /** Pending self-edit proposals + the active applied overlay. */
+    listProposals() {
+        return { proposals: proposals(this.personaPath), activeOverlay: activeOverlay(this.personaPath) };
+    }
+    /**
+     * Decide a pending proposal. `approver` MUST differ from the proposer (proposer≠approver);
+     * hosts pass their own identity so the audit trail is meaningful.
+     */
+    decideEdit(id, decision, approver) {
+        if (decision === "approve") {
+            const applied = applySelfEdit(this.personaPath, id, approver);
+            return { ...applied, recompilePending: readRecompilePending(this.personaPath).pending };
+        }
+        rejectSelfEdit(this.personaPath, id, approver);
+        return { id, status: "rejected" };
+    }
+    /** Whether the compiled PERSONA.md is stale (a governed self-edit was applied since the last compile). */
+    recompileStatus() {
+        const s = readRecompilePending(this.personaPath);
+        return { recompilePending: s.pending, reason: s.reason ?? null, since: s.ts ?? null };
+    }
+    /** Reload the spec from disk (e.g. after an external recompile/decompile). */
+    reload() {
+        this.handle = loadPersona(this.personaPath);
+    }
+}
+// ── Persona-independent safety helpers (the same façade; no persona instance needed) ──────────────
+/** Scan untrusted text for prompt-injection before it reaches a persona. */
+export function scanText(text) {
+    return scanForInjection(text);
+}
+/** Scan an agent config file's content for injection/poisoning (kind inferred from the filename). */
+export function scanConfig(content, filename) {
+    return scanAgentConfig(content, filename ? detectKind(filename) : undefined);
+}
+/** Security-review a skill before use (supply-chain defense). */
+export function skillReview(skillPath) {
+    return reviewSkill(skillPath);
+}
+/**
+ * Evaluate a shell command against a two-axis (approval × sandbox) policy. With a persona path, the
+ * persona's OWN declared `permissions` posture is used (v0.8); otherwise the explicit args apply.
+ */
+export function evaluateCmd(command, sandbox, approval, personaPath) {
+    const policy = personaPath
+        ? policyFromFrontmatter(loadPersona(resolve(personaPath)).frontmatter, process.cwd())
+        : { ...DEFAULT_POLICY, sandbox, approval, workspaceRoot: process.cwd() };
+    return evaluateCommand(command, policy);
+}
+export { resolveModel } from "@personaxis/core";

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@personaxis/sdk",
+  "version": "0.11.0",
+  "description": "Ergonomic SDK for embedding a living, governed persona in a Node/TypeScript backend (Modo 2 self-host). A thin wrapper over @personaxis/core.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@personaxis/core": "0.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/personaxis/cli.git",
+    "directory": "packages/sdk"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}