lingxios 1.0.0

package/README.md

@@ -0,0 +1,54 @@
+# LingxiOS
+
+AgentOS and Harness in one npm package: durable PostgreSQL work queues, fenced workers, versioned requests, Python execution, action receipts, goal outcomes and committed messages/files.
+
+The first release targets the core runtime. The optional LingxiLoop integration contains the implemented bindings; it does not claim complete product capability coverage. There is one initial schema and no legacy migration or dual-write path.
+
+## Run a request
+
+Requires Node.js 22.13+, Python 3 and a PostgreSQL pool. Apply `packageResources().schema` to a new application database before starting. The application checks the installed schema and does not fall back to in-memory storage.
+
+```ts
+import { createLingxiOS } from 'lingxios'
+import { pool } from './database.js'
+
+const app = await createLingxiOS({
+  database: pool,
+  model: { apiKey: process.env.AGENT_OS_MODEL_API_KEY! },
+  kernel: { homesRoot: '/persistent/agent-homes' },
+})
+
+try {
+  // Authenticate and authorize this identity in the calling server.
+  const identity = {
+    runId: 'request-1', tenantId: 'tenant', agentId: 'assistant', sessionId: 'conversation',
+  }
+  await app.enqueue({
+    ...identity, id: identity.runId, principalId: 'authenticated-user',
+    text: 'Calculate six times seven using Python.',
+  })
+  await app.runNext()
+  console.log(await app.readMessage(identity))
+  console.log(await app.readOutcome(identity))
+} finally {
+  await app.stop()
+}
+```
+
+The default model is `deepseek-ai/DeepSeek-V4-Flash` at SiliconFlow, with `reasoning_effort=high`. The calling application owns the database pool. Use `start()` for continuous local workers, or `/worker` and the authenticated HTTP control plane for separate worker processes.
+
+## Public entries
+
+| Entry | Purpose |
+| --- | --- |
+| `lingxios` | Application, diagnostics and packaged schema/runner locations |
+| `lingxios/worker` | Worker process and startup configuration |
+| `lingxios/ui` | Browser-safe committed message and event consumers |
+| `lingxios/eval` | Recorded resource checks and model review |
+| `lingxios/lingxiloop` | Optional native product bindings |
+
+Goal status is separate from worker lifecycle. `satisfied` records the model's requirement assessment; it is not independent proof of correctness. Unknown actions, missing receipts and known resource failures prevent a satisfied result. Input/approval waits retain the same request and version. Committed files are hashed snapshots; recovering an interrupted worker does not blindly repeat unknown effects.
+
+Python execution needs deployment isolation suitable for your trust model; Python-level guards are not an OS security boundary. Committed artifacts currently require shared persistent filesystem storage and are limited to 16 MiB each.
+
+See [runtime API and deployment details](docs/packaged-runtime.md). `npm test` includes standalone tarball installation. `npm run check:release` also requires isolated PostgreSQL fixtures and the native LingxiLoop reference checkout; it does not deploy a product or contact real email recipients.

package/db/schema.sql

@@ -0,0 +1,306 @@
+-- LingxiOS Agent OS — control-plane schema (protocol v2)
+--
+-- Apply with: psql -f db/schema.sql
+-- All tables are owned by the control plane; workers never touch the database.
+
+CREATE SCHEMA IF NOT EXISTS lingxios;
+
+CREATE TABLE IF NOT EXISTS lingxios.schema_version (
+  singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),
+  version INT NOT NULL
+);
+INSERT INTO lingxios.schema_version(singleton, version) VALUES(TRUE, 1) ON CONFLICT DO NOTHING;
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_work_items (
+  id                   TEXT PRIMARY KEY,
+  fence                BIGINT NOT NULL DEFAULT 0,
+  tenant_id            TEXT NOT NULL,
+  agent_id             TEXT NOT NULL,
+  session_id           TEXT NOT NULL,
+  thread_id            TEXT,
+  kind                 TEXT NOT NULL,
+  lane                 TEXT NOT NULL CHECK (lane IN ('interactive','approval','collaboration','background')),
+  trigger_ref          TEXT NOT NULL,
+  principal_id         TEXT,
+  priority             INT NOT NULL DEFAULT 0,
+  status               TEXT NOT NULL DEFAULT 'queued'
+                       CHECK (status IN ('queued','leased','completed','failed','cancelled')),
+  created_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  available_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  attempts             INT NOT NULL DEFAULT 0,
+  preemptions          INT NOT NULL DEFAULT 0,
+  lease_token_hash     TEXT,
+  leased_by            TEXT,
+  lease_expires_at     TIMESTAMPTZ,
+  cancel_requested_at  TIMESTAMPTZ,
+  preempt_requested_at TIMESTAMPTZ,
+  steer_inputs         JSONB NOT NULL DEFAULT '[]'::jsonb,
+  result_text          TEXT,
+  goal_outcome         JSONB,
+  error                TEXT,
+  meta                 JSONB,
+  finished_at          TIMESTAMPTZ,
+  updated_at           TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS agent_work_items_claim_idx
+  ON lingxios.agent_work_items (status, available_at)
+  WHERE status IN ('queued','leased');
+
+-- Package-owned schedules; no dependency on the retired product agent runtime.
+CREATE TABLE IF NOT EXISTS lingxios.agent_routines (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  principal_id TEXT NOT NULL,
+  project_id TEXT,
+  course_id TEXT,
+  thread_id TEXT,
+  kind TEXT NOT NULL,
+  title TEXT,
+  instructions TEXT,
+  schedule JSONB NOT NULL,
+  timezone TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('active','paused')),
+  version INT NOT NULL DEFAULT 1 CHECK (version>0),
+  next_run_at TIMESTAMPTZ,
+  pause_reason TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CHECK (kind<>'teacher_digest' OR (project_id IS NOT NULL AND course_id IS NOT NULL AND thread_id IS NULL)),
+  CHECK (kind='teacher_digest' OR (title IS NOT NULL AND instructions IS NOT NULL AND course_id IS NULL)),
+  CHECK ((status='active' AND next_run_at IS NOT NULL) OR (status='paused' AND next_run_at IS NULL))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS agent_teacher_digest_scope_idx ON lingxios.agent_routines(tenant_id,agent_id,session_id,kind) WHERE kind='teacher_digest';
+CREATE INDEX IF NOT EXISTS agent_routines_due_idx ON lingxios.agent_routines(next_run_at) WHERE status='active';
+CREATE TABLE IF NOT EXISTS lingxios.agent_routine_runs (
+  routine_id TEXT NOT NULL REFERENCES lingxios.agent_routines(id) ON DELETE CASCADE,
+  routine_version INT NOT NULL,
+  scheduled_at TIMESTAMPTZ NOT NULL,
+  work_id TEXT NOT NULL UNIQUE REFERENCES lingxios.agent_work_items(id) ON DELETE CASCADE,
+  PRIMARY KEY(routine_id,routine_version,scheduled_at)
+);
+
+-- One live lease per session key.
+CREATE TABLE IF NOT EXISTS lingxios.agent_os_session_leases (
+  session_key TEXT PRIMARY KEY,
+  work_id     TEXT NOT NULL,
+  fence       BIGINT NOT NULL,
+  expires_at  TIMESTAMPTZ NOT NULL,
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Session -> worker routing with home epochs.
+CREATE TABLE IF NOT EXISTS lingxios.agent_os_session_routes (
+  session_key TEXT PRIMARY KEY,
+  worker_id   TEXT NOT NULL,
+  home_epoch  BIGINT NOT NULL DEFAULT 1,
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Worker liveness.
+CREATE TABLE IF NOT EXISTS lingxios.agent_os_workers (
+  worker_id    TEXT PRIMARY KEY,
+  last_seen_at TIMESTAMPTZ NOT NULL,
+  updated_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Durable conversational sessions (optimistic concurrency via revision).
+CREATE TABLE IF NOT EXISTS lingxios.agent_os_sessions (
+  session_key      TEXT PRIMARY KEY,
+  tenant_id        TEXT NOT NULL,
+  agent_id         TEXT NOT NULL,
+  session_id       TEXT NOT NULL,
+  thread_id        TEXT,
+  summary          TEXT,
+  history          JSONB NOT NULL DEFAULT '[]'::jsonb,
+  applied_work_ids JSONB NOT NULL DEFAULT '[]'::jsonb,
+  revision         BIGINT NOT NULL DEFAULT 0,
+  compaction_epoch INT NOT NULL DEFAULT 0,
+  prompt_context   JSONB,
+  request_snapshot JSONB,
+  updated_at       TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Run event ledger: dedupe on (run_id, seq); the attempt range is enforced by
+-- the control plane before insert.
+CREATE TABLE IF NOT EXISTS lingxios.agent_run_events (
+  run_id      TEXT NOT NULL,
+  seq         BIGINT NOT NULL,
+  tenant_id   TEXT NOT NULL,
+  agent_id    TEXT NOT NULL,
+  kind        TEXT NOT NULL,
+  stage       TEXT NOT NULL,
+  visibility  TEXT NOT NULL CHECK (visibility IN ('user','internal')),
+  data        JSONB NOT NULL DEFAULT '{}'::jsonb,
+  recorded_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (run_id, seq)
+);
+
+-- An intent without a receipt is uncertain, never automatically re-executed.
+CREATE TABLE IF NOT EXISTS lingxios.agent_action_intents (
+  idempotency_key TEXT PRIMARY KEY,
+  fingerprint TEXT NOT NULL,
+  intent JSONB NOT NULL CHECK (jsonb_typeof(intent) = 'object'),
+  recorded_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Receipts complement pre-execution intents; missing receipts require reconciliation.
+CREATE TABLE IF NOT EXISTS lingxios.agent_action_ledger (
+  idempotency_key TEXT PRIMARY KEY REFERENCES lingxios.agent_action_intents(idempotency_key),
+  result          JSONB NOT NULL,
+  recorded_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_messages (
+  run_id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  message JSONB NOT NULL,
+  home_epoch BIGINT NOT NULL DEFAULT 1 CHECK (home_epoch > 0),
+  committed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_delivery_outbox (
+  run_id TEXT PRIMARY KEY REFERENCES lingxios.agent_messages(run_id),
+  work JSONB NOT NULL,
+  delivered_at TIMESTAMPTZ,
+  available_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  claim_token TEXT,
+  attempts INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_calendar_outbox (
+  id TEXT PRIMARY KEY REFERENCES lingxios.agent_action_intents(idempotency_key),
+  work_id TEXT NOT NULL REFERENCES lingxios.agent_work_items(id),
+  event JSONB NOT NULL CHECK (jsonb_typeof(event)='object' AND event->>'type'='calendar.changed'),
+  delivered_at TIMESTAMPTZ,
+  available_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  claim_token TEXT,
+  attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts BETWEEN 0 AND 30)
+);
+CREATE INDEX IF NOT EXISTS agent_calendar_outbox_pending
+  ON lingxios.agent_calendar_outbox(available_at,id) WHERE delivered_at IS NULL;
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_canvas_outbox (
+  id TEXT PRIMARY KEY,
+  event JSONB NOT NULL CHECK (jsonb_typeof(event)='object' AND event->>'type'='canvas.changed'),
+  delivered_at TIMESTAMPTZ,
+  available_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  claim_token TEXT,
+  attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts BETWEEN 0 AND 30)
+);
+CREATE INDEX IF NOT EXISTS agent_canvas_outbox_pending
+  ON lingxios.agent_canvas_outbox(available_at,id) WHERE delivered_at IS NULL;
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_document_outbox (
+  id TEXT PRIMARY KEY,
+  event JSONB NOT NULL CHECK (jsonb_typeof(event)='object' AND event->>'type' IN ('doc.changed','doc.update')),
+  delivered_at TIMESTAMPTZ,
+  available_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  claim_token TEXT,
+  attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts BETWEEN 0 AND 30)
+);
+CREATE INDEX IF NOT EXISTS agent_document_outbox_pending
+  ON lingxios.agent_document_outbox(available_at,id) WHERE delivered_at IS NULL;
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_memories (
+  tenant_id TEXT NOT NULL,
+  id TEXT NOT NULL,
+  scope_type TEXT NOT NULL CHECK (scope_type IN ('learner','course','agent_role')),
+  scope_id TEXT NOT NULL,
+  body TEXT NOT NULL CHECK (length(body) BETWEEN 1 AND 2000),
+  kind TEXT NOT NULL,
+  origin TEXT NOT NULL CHECK (origin IN ('explicit','synthesized')),
+  pinned BOOLEAN NOT NULL DEFAULT FALSE,
+  version INTEGER NOT NULL DEFAULT 1 CHECK (version > 0),
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','expired')),
+  source_refs JSONB NOT NULL CHECK (jsonb_typeof(source_refs)='array' AND jsonb_array_length(source_refs) BETWEEN 1 AND 64),
+  valid_until TIMESTAMPTZ,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (tenant_id,id)
+);
+CREATE INDEX IF NOT EXISTS agent_memories_scope ON lingxios.agent_memories(tenant_id,scope_type,scope_id,updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_memory_embeddings (
+  tenant_id TEXT NOT NULL,
+  memory_id TEXT NOT NULL,
+  version INTEGER NOT NULL CHECK (version > 0),
+  model_key TEXT NOT NULL,
+  model TEXT NOT NULL,
+  embedding DOUBLE PRECISION[] NOT NULL CHECK (cardinality(embedding) BETWEEN 1 AND 4096),
+  PRIMARY KEY (tenant_id,memory_id,model_key),
+  FOREIGN KEY (tenant_id,memory_id) REFERENCES lingxios.agent_memories(tenant_id,id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_memory_versions (
+  tenant_id TEXT NOT NULL,
+  memory_id TEXT NOT NULL,
+  version INTEGER NOT NULL CHECK (version > 0),
+  snapshot JSONB NOT NULL CHECK (jsonb_typeof(snapshot)='object'),
+  replaced_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (tenant_id,memory_id,version),
+  FOREIGN KEY (tenant_id,memory_id) REFERENCES lingxios.agent_memories(tenant_id,id) ON DELETE CASCADE
+);
+
+-- Archive the replaced version in the mutation transaction. Explicit forgetting
+-- deletes its history through the foreign key instead of retaining forgotten text.
+CREATE OR REPLACE FUNCTION lingxios.archive_memory_version() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF NEW.version <= OLD.version THEN
+    RAISE EXCEPTION 'memory versions must increase';
+  END IF;
+  INSERT INTO lingxios.agent_memory_versions(tenant_id,memory_id,version,snapshot)
+    VALUES(OLD.tenant_id,OLD.id,OLD.version,to_jsonb(OLD));
+  RETURN NEW;
+END;
+$$;
+CREATE OR REPLACE TRIGGER agent_memory_version_history
+  BEFORE UPDATE OF version ON lingxios.agent_memories
+  FOR EACH ROW WHEN (OLD.version IS DISTINCT FROM NEW.version)
+  EXECUTE FUNCTION lingxios.archive_memory_version();
+
+CREATE TABLE IF NOT EXISTS lingxios.agent_memory_evidence (
+  source_run_id TEXT PRIMARY KEY REFERENCES lingxios.agent_messages(run_id),
+  tenant_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  principal_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  request_version INTEGER NOT NULL CHECK (request_version > 0),
+  source_ref TEXT NOT NULL,
+  input_sha256 TEXT NOT NULL CHECK (input_sha256 ~ '^[a-f0-9]{64}$'),
+  input_text TEXT NOT NULL CHECK (length(input_text) <= 16000),
+  assistant_text TEXT NOT NULL CHECK (length(assistant_text) <= 16000),
+  input_truncated BOOLEAN NOT NULL,
+  assistant_truncated BOOLEAN NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','processed','rejected','superseded')),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Invalidate sources atomically on every cancellation/continuation path, including
+-- server-side ingress that does not call the worker's control-plane methods.
+CREATE OR REPLACE FUNCTION lingxios.supersede_memory_evidence() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  WITH superseded AS (
+    UPDATE lingxios.agent_memory_evidence SET status='superseded'
+    WHERE source_run_id=NEW.id AND status IN ('pending','processed')
+      AND (NEW.cancel_requested_at IS NOT NULL OR NEW.status='cancelled'
+        OR request_version<>jsonb_array_length(NEW.steer_inputs)+1)
+    RETURNING source_run_id,tenant_id)
+  UPDATE lingxios.agent_memories memory SET status='expired',version=version+1,updated_at=NOW()
+    FROM superseded source WHERE memory.tenant_id=source.tenant_id AND memory.origin='synthesized'
+      AND NOT memory.pinned AND memory.status='active'
+      AND memory.source_refs @> jsonb_build_array(jsonb_build_object('workId',source.source_run_id));
+  RETURN NEW;
+END;
+$$;
+CREATE OR REPLACE TRIGGER agent_work_memory_evidence
+  AFTER UPDATE OF cancel_requested_at,status,steer_inputs ON lingxios.agent_work_items
+  FOR EACH ROW
+  WHEN (OLD.cancel_requested_at IS DISTINCT FROM NEW.cancel_requested_at
+    OR OLD.status IS DISTINCT FROM NEW.status OR OLD.steer_inputs IS DISTINCT FROM NEW.steer_inputs)
+  EXECUTE FUNCTION lingxios.supersede_memory_evidence();

package/dist/src/app/artifacts.d.ts

@@ -0,0 +1,8 @@
+import type { SqlPool } from '../control-plane/pg-store.js';
+import type { AssistantMessage, KernelArtifact, WorkItem } from '../protocol/types.js';
+import type { MessageIdentity, RequestInput } from './index.js';
+export declare function persistArtifacts(homesRoot: string, work: Omit<WorkItem, 'leaseToken'>, message: AssistantMessage): Promise<void>;
+export declare function readArtifact(database: SqlPool, homesRoot: string, identity: MessageIdentity & Pick<RequestInput, 'principalId' | 'threadId'>, path: string): Promise<{
+    artifact: KernelArtifact;
+    bytes: Buffer<ArrayBuffer>;
+} | null>;

package/dist/src/app/artifacts.js

@@ -0,0 +1,114 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { open, realpath, mkdir, link, unlink } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { kernelHome } from '../kernel/manager.js';
+import { snapshotArtifacts } from '../outcome/envelope.js';
+function artifactDirectory(root, identity) {
+    const hash = createHash('sha256').update(JSON.stringify([identity.tenantId, identity.agentId, identity.runId])).digest('hex');
+    return resolve(root, '.committed-artifacts', hash);
+}
+const inside = (parent, child) => {
+    const path = relative(parent, child);
+    return path !== '..' && !path.startsWith('../') && !path.startsWith('..\\') && !isAbsolute(path);
+};
+async function checkedFile(root, directory, filename, artifact) {
+    // ponytail: bounded buffers; add streaming storage for files above 16 MiB.
+    if (artifact.size > 16 * 1024 * 1024)
+        throw new Error('artifact exceeds the 16 MiB limit');
+    const home = await realpath(directory);
+    const file = await realpath(resolve(home, filename));
+    if (!inside(root, home) || !inside(home, file))
+        throw new Error('artifact is outside its committed home');
+    const handle = await open(file, 'r');
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.size !== artifact.size)
+            throw new Error('artifact changed since commitment');
+        const bytes = Buffer.alloc(artifact.size + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const read = await handle.read(bytes, length, bytes.length - length, null);
+            if (!read.bytesRead)
+                break;
+            length += read.bytesRead;
+        }
+        const after = await handle.stat();
+        const content = bytes.subarray(0, length);
+        if (length !== artifact.size || before.mtimeMs !== after.mtimeMs || after.size !== artifact.size
+            || createHash('sha256').update(content).digest('hex') !== artifact.sha256.toLowerCase())
+            throw new Error('artifact changed since commitment');
+        return { artifact, bytes: content };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function persistArtifacts(homesRoot, work, message) {
+    const artifacts = snapshotArtifacts(message.envelope.artifacts);
+    if (!artifacts.length)
+        return;
+    const root = await realpath(homesRoot);
+    const directory = artifactDirectory(root, { ...work, runId: work.id });
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if (await realpath(directory) !== directory)
+        throw new Error('artifact storage must not traverse directory links');
+    for (const artifact of artifacts) {
+        const destination = resolve(directory, artifact.sha256.toLowerCase());
+        try {
+            await checkedFile(root, directory, artifact.sha256.toLowerCase(), artifact);
+            continue;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const { bytes } = await checkedFile(root, kernelHome(root, work), artifact.path, artifact);
+        const temporary = resolve(directory, randomUUID());
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+            await handle.close();
+            try {
+                await link(temporary, destination);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            await checkedFile(root, directory, artifact.sha256.toLowerCase(), artifact);
+        }
+        finally {
+            await handle.close();
+            await unlink(temporary);
+        }
+    }
+}
+export async function readArtifact(database, homesRoot, identity, path) {
+    if (!identity.principalId?.trim())
+        throw new Error('authenticated principalId is required');
+    const { rows } = await database.query(`SELECT message.message,message.home_epoch FROM lingxios.agent_messages message
+    JOIN lingxios.agent_work_items work ON work.id=message.run_id AND work.tenant_id=message.tenant_id
+      AND work.agent_id=message.agent_id AND work.session_id=message.session_id
+    WHERE message.run_id=$1 AND message.tenant_id=$2 AND message.agent_id=$3 AND message.session_id=$4
+      AND work.principal_id=$5 AND work.thread_id IS NOT DISTINCT FROM $6`, [identity.runId, identity.tenantId, identity.agentId, identity.sessionId, identity.principalId, identity.threadId ?? null]);
+    if (!rows[0])
+        return null;
+    const message = rows[0]['message'];
+    const artifact = snapshotArtifacts(message.envelope.artifacts).find(item => item.path === path);
+    if (!artifact)
+        return null;
+    try {
+        const root = await realpath(homesRoot);
+        const directory = artifactDirectory(root, identity);
+        if (await realpath(directory) !== directory)
+            throw new Error('artifact storage must not traverse directory links');
+        return await checkedFile(root, directory, artifact.sha256.toLowerCase(), artifact);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/src/app/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../../src/app/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/src/app/doctor.d.ts

@@ -0,0 +1,22 @@
+import type { SqlQueryable } from '../control-plane/pg-store.js';
+export interface DoctorCheck {
+    name: string;
+    status: 'passed' | 'failed' | 'not_run';
+    detail: string;
+}
+export declare function doctor(options?: {
+    database?: SqlQueryable;
+    pythonCommand?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    ready: boolean;
+    versions: Readonly<{
+        readonly runtime: "1.0.0";
+        readonly controlPlane: 2;
+        readonly kernel: 2;
+        readonly schema: 1;
+        readonly lingxiLoop: 1;
+        readonly assistantMessage: 2;
+    }>;
+    checks: DoctorCheck[];
+}>;

package/dist/src/app/doctor.js

@@ -0,0 +1,44 @@
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { packageResources } from './resources.js';
+import { checkStorage } from './storage.js';
+import { releaseVersions } from '../versions.js';
+export async function doctor(options = {}) {
+    const env = options.env ?? process.env;
+    const checks = [];
+    const [nodeMajor = 0, nodeMinor = 0] = process.versions.node.split('.').map(Number);
+    checks.push({ name: 'node', status: (nodeMajor > 22 || nodeMajor === 22 && nodeMinor >= 13) ? 'passed' : 'failed', detail: process.versions.node });
+    const python = options.pythonCommand ?? env['AGENT_OS_PYTHON'] ?? (process.platform === 'win32' ? 'python' : 'python3');
+    try {
+        const { stdout } = await promisify(execFile)(python, ['-I', '-c', 'import sys; assert sys.version_info >= (3, 10); print(sys.version.split()[0])'], { timeout: 10_000 });
+        checks.push({ name: 'python', status: 'passed', detail: stdout.trim() });
+    }
+    catch {
+        checks.push({ name: 'python', status: 'failed', detail: 'Python >=3.10 must be executable; set AGENT_OS_PYTHON if needed' });
+    }
+    for (const [name, path] of Object.entries(packageResources())) {
+        try {
+            await access(path);
+            checks.push({ name, status: 'passed', detail: path });
+        }
+        catch {
+            checks.push({ name, status: 'failed', detail: 'required packaged resource is missing' });
+        }
+    }
+    checks.push({ name: 'model_configuration', status: env['AGENT_OS_MODEL_API_KEY']?.trim() ? 'passed' : 'failed', detail: 'Checks credential configuration presence only; model defaults to DeepSeek-V4-Flash with high reasoning. Provider access and quality are not tested.' });
+    if (options.database) {
+        try {
+            await checkStorage(options.database);
+            checks.push({ name: 'database', status: 'passed', detail: 'Initial schema version 1, required columns and memory triggers are readable; write permissions and all constraints are not verified' });
+        }
+        catch {
+            checks.push({ name: 'database', status: 'failed', detail: 'Database unavailable or explicit schema installation is required' });
+        }
+    }
+    else {
+        checks.push({ name: 'database', status: 'not_run', detail: 'Pass the existing database pool to doctor to verify storage' });
+    }
+    return { ready: checks.every((check) => check.status === 'passed'), versions: releaseVersions, checks };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/src/app/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/app/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErC,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAQhD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,UAAwF,EAAE;IACrH,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAA;IACtC,MAAM,MAAM,GAAkB,EAAE,CAAA;IAChC,MAAM,CAAC,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACnF,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,SAAS,GAAG,EAAE,IAAI,SAAS,KAAK,EAAE,IAAI,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;IACnJ,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,IAAI,GAAG,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IACvH,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,+EAA+E,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;QACxK,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,iEAAiE,EAAE,CAAC,CAAA;IAC9H,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAA;YAClB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,uCAAuC,EAAE,CAAC,CAAA;QAC1F,CAAC;IACH,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,MAAM,EAAE,GAAG,CAAC,wBAAwB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,qJAAqJ,EAAE,CAAC,CAAA;IAChR,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;YACpC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,qIAAqI,EAAE,CAAC,CAAA;QACpM,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,kEAAkE,EAAE,CAAC,CAAA;QACjI,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,6DAA6D,EAAE,CAAC,CAAA;IAC7H,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,CAAA;AACzG,CAAC"}