@guangnao/agent-os 1.0.0

package/dist/userland/agent.d.ts

@@ -0,0 +1,62 @@
+import type { ProcessImage, Segment } from '../abi/index';
+import type { ChatMessage, ToolSchema } from '../drivers/llm';
+export interface AgentSpec {
+    readonly task?: string;
+    readonly system?: string;
+    readonly tools?: readonly ToolSchema[];
+    readonly maxSteps?: number;
+    readonly baseSteps?: number;
+    readonly stallLimit?: number;
+    readonly maxTokens?: number;
+    readonly history?: readonly ChatMessage[];
+    readonly delegate?: DelegatePolicy;
+    readonly reflect?: (messages: readonly ChatMessage[]) => Promise<ReflectVerdict> | ReflectVerdict;
+    readonly maxRevisions?: number;
+    readonly maxContinue?: number;
+}
+/** A reflect verdict, returned just before a turn would finish:
+ *   - null / '' / undefined         → let it finish.
+ *   - string  or  {kind:'revise'}   → a QUALITY correction (e.g. "verify failed, fix it"); sent back, COUNTED
+ *                                      against maxRevisions so it can't loop forever.
+ *   - {kind:'continue'}             → the plan still has work AND is progressing; sent back but NOT counted
+ *                                      against maxRevisions (only the generous maxContinue + the maxSteps
+ *                                      ceiling bound it). This is what lets a multi-step plan loop to completion
+ *                                      instead of being cut off at 2 revisions. Userland MUST stop emitting it
+ *                                      once there's no real progress (else it spins to the ceiling). */
+export type ReflectVerdict = string | {
+    readonly correction: string;
+    readonly kind?: 'revise' | 'continue';
+} | null | undefined;
+/** When the model keeps investigating file-by-file (which floods the transcript + its own context), steer
+ *  it to delegate to a sub-agent tool instead. Past `after` consecutive investigation calls we withhold
+ *  the (sub-agent-replaceable) read/search tools for a round and nudge it to call `via`. */
+export interface DelegatePolicy {
+    readonly investigate: readonly string[];
+    readonly withhold: readonly string[];
+    readonly via: string;
+    readonly after: number;
+}
+export interface AgentResult {
+    readonly $: 'result';
+    readonly answer: string;
+    readonly steps: number;
+    readonly error?: string;
+}
+/** Enforce the provider invariant "an assistant tool_calls turn is followed by a tool result for EACH
+ *  id" — the MMU can page out one half of a call/result pair, leaving a dangling tool_calls (→ 400) or
+ *  an orphan tool result. Keep only tool_calls whose result is still resident, drop orphan tool turns,
+ *  and demote an assistant turn whose calls are all gone to plain narration. Applied just before send. */
+/** Order the working set for maximal provider prompt-cache hits. Caches key on the longest IDENTICAL
+ *  message PREFIX, so we front-load the STABLE parts: pinned system prompt(s), then the slowly-changing
+ *  earlier-context summaries, then the live turns in recency order. Between compactions the live turns
+ *  only grow by append, so the whole prefix stays byte-identical and the provider recomputes just the
+ *  newest turn. (The pager appends each summary at the END of resident — newest slot — which is both the
+ *  wrong chronology and cache-hostile; this also restores "summary of old context comes first".) */
+export declare function orderForCache(segs: readonly Segment[]): Segment[];
+export declare function pairToolCalls(messages: readonly ChatMessage[]): ChatMessage[];
+/** One-shot: seed system + task, run a turn, report the answer, exit. */
+export declare function reactAgent(spec: AgentSpec): ProcessImage;
+/** Long-lived conversation: pinned system prompt, then a loop over user turns. Context carries
+ *  across turns (the MMU pages/compresses it under pressure), so the agent remembers the dialogue.
+ *  Each turn arrives as `{ task }`; the answer is sent back to the reply cap. */
+export declare function conversationAgent(spec?: AgentSpec): ProcessImage;

package/dist/userland/distill.d.ts

@@ -0,0 +1,9 @@
+import type { ChatFn, ChatMessage } from '../drivers/llm';
+import type { LongMemory } from './longmem';
+export type Distiller = (messages: readonly ChatMessage[]) => Promise<string[]>;
+/** Parse a model reply into clean one-line lessons. */
+export declare const parseLessons: (text: string) => string[];
+/** An LLM-backed distiller: a finished session's messages → reusable lessons. */
+export declare function llmDistiller(chat: ChatFn, maxTokens?: number): Distiller;
+/** Reflect on a finished session: distill lessons and fold them into long-term memory. Returns added count. */
+export declare function learn(mem: LongMemory, distill: Distiller, messages: readonly ChatMessage[], tags?: readonly string[]): Promise<number>;

package/dist/userland/evolve.d.ts

@@ -0,0 +1,29 @@
+export interface Candidate {
+    prompt: string;
+    label?: string;
+}
+export interface Scored extends Candidate {
+    fitness: number;
+    detail?: unknown;
+}
+export type Scorer = (prompt: string) => Promise<{
+    fitness: number;
+    detail?: unknown;
+}>;
+/** Score candidates concurrently and rank best-first (higher fitness = better). */
+export declare function tournament(candidates: readonly Candidate[], score: Scorer): Promise<Scored[]>;
+/** Evolve a base prompt: score it against the variants; adopt the winner ONLY if it beats the base
+ *  by `margin` (else keep the baseline — no regression). Returns the chosen prompt + the ranking. */
+export declare function evolve(base: string, variants: readonly string[], score: Scorer, margin?: number): Promise<{
+    winner: string;
+    improved: boolean;
+    ranked: Scored[];
+}>;
+/** A fitness from a run's outcome: correctness [0..1] dominates; cost (steps/tokens/usd) breaks ties.
+ *  Tune the weights per domain; this is a sensible default the Scorer can build on. */
+export declare function meteredFitness(r: {
+    correct: number;
+    steps?: number;
+    tokens?: number;
+    usd?: number;
+}): number;

package/dist/userland/expert.d.ts

@@ -0,0 +1,28 @@
+import type { ChatFn, ChatMessage } from '../drivers/llm';
+import { LongMemory, type MemoryPersist } from './longmem';
+import { type Distiller } from './distill';
+import { PersonaRegistry, type Persona, type PersonaPersist } from './persona';
+import type { AgentSpec } from './agent';
+export interface ExpertOptions {
+    readonly memory?: MemoryPersist;
+    readonly personas?: PersonaPersist;
+    readonly distiller?: Distiller;
+    readonly now?: () => number;
+}
+export declare class PromptExpert {
+    private readonly chat;
+    readonly memory: LongMemory;
+    readonly personas: PersonaRegistry;
+    private readonly distill;
+    constructor(chat: ChatFn, opts?: ExpertOptions);
+    /** Reflect on a finished session → fold reusable lessons into long-term memory. Returns added count. */
+    learn(messages: readonly ChatMessage[], tags?: readonly string[]): Promise<number>;
+    /** Forge (or refresh) a domain persona from accumulated lessons, then register it. */
+    specialize(domain: string, opts?: {
+        name?: string;
+        goal?: string;
+        tools?: Persona['tools'];
+    }): Promise<Persona>;
+    /** Instantiate a persona for a task (enriched with recalled lessons) → ready for reactAgent/conversationAgent. */
+    hire(name: string, task: string, recall?: number): AgentSpec | null;
+}

package/dist/userland/longmem.d.ts

@@ -0,0 +1,32 @@
+import type { Recaller } from '../kernel/memory';
+export interface Lesson {
+    readonly id: string;
+    readonly text: string;
+    readonly tags: readonly string[];
+    readonly ts: number;
+    uses: number;
+}
+/** Durable backing for lessons — wire it to a file/DB; omit for in-memory only. */
+export interface MemoryPersist {
+    load(): readonly Lesson[];
+    append(l: Lesson): void;
+}
+export declare class LongMemory {
+    private readonly recaller;
+    private readonly by;
+    private readonly seen;
+    private readonly persist?;
+    private readonly now;
+    constructor(opts?: {
+        recaller?: Recaller;
+        persist?: MemoryPersist;
+        now?: () => number;
+    });
+    private ingest;
+    /** Add a distilled lesson (deduped, lossy by design). Returns false if it was a duplicate/empty. */
+    remember(text: string, tags?: readonly string[]): boolean;
+    /** Recall the k most relevant lessons for a query (bumps their use count — popularity signal). */
+    recall(query: string, k?: number): Lesson[];
+    all(): readonly Lesson[];
+    get size(): number;
+}

package/dist/userland/nameservice.d.ts

@@ -0,0 +1,6 @@
+import type { ProcessImage, Sys, CapRef } from '../abi/index';
+export declare const nameService: ProcessImage;
+/** Publish yourself under `name` so others can find you. */
+export declare function register(sys: Sys, names: CapRef, name: string): Promise<void>;
+/** Resolve `name` → a send-cap (or null). Skips unrelated messages while waiting for the reply. */
+export declare function lookup(sys: Sys, names: CapRef, name: string): Promise<CapRef | null>;

package/dist/userland/nursery.d.ts

@@ -0,0 +1,9 @@
+import type { Sys, CapRef, ProcessImage, SpawnOptions } from '../abi/index';
+export interface Scope {
+    /** Spawn a child INTO the scope; returns its cap (send/monitor/kill). Throws after join(). */
+    spawn<A>(image: ProcessImage<A>, opts?: SpawnOptions<A>): Promise<CapRef>;
+    /** Wait for ALL children. If any exits abnormally, cancel the rest and throw; else return normally.
+     *  Either way, on settle every child has terminated. Idempotent. */
+    join(): Promise<void>;
+}
+export declare function nursery(sys: Sys): Scope;

package/dist/userland/persona.d.ts

@@ -0,0 +1,34 @@
+import type { AgentSpec } from './agent';
+import type { ToolSchema } from '../drivers/llm';
+import type { LongMemory } from './longmem';
+export interface Persona {
+    readonly name: string;
+    readonly domain: string;
+    readonly system: string;
+    readonly tools?: readonly ToolSchema[];
+    readonly notes?: string;
+    readonly ts: number;
+}
+/** Durable backing for personas — wire to a file/DB; omit for in-memory only. */
+export interface PersonaPersist {
+    load(): readonly Persona[];
+    save(p: Persona): void;
+}
+export declare class PersonaRegistry {
+    private readonly persist?;
+    private readonly now;
+    private readonly by;
+    constructor(persist?: PersonaPersist | undefined, now?: () => number);
+    /** Save (or replace) a persona by name. */
+    save(p: Omit<Persona, 'ts'> & {
+        ts?: number;
+    }): Persona;
+    get(name: string): Persona | undefined;
+    list(): readonly Persona[];
+    forDomain(domain: string): Persona[];
+}
+/** Build an AgentSpec from a persona — folding in the lessons memory recalls for `task`. */
+export declare function instantiate(p: Persona, task: string, opts?: {
+    memory?: LongMemory;
+    recall?: number;
+}): AgentSpec;

package/dist/userland/promptsmith.d.ts

@@ -0,0 +1,18 @@
+import type { ChatFn } from '../drivers/llm';
+import type { LongMemory } from './longmem';
+export interface ForgeBrief {
+    domain: string;
+    goal?: string;
+    lessons?: readonly string[];
+    tools?: readonly string[];
+}
+/** Forge a fresh specialized system prompt for a domain. */
+export declare function forgePrompt(chat: ChatFn, b: ForgeBrief, maxTokens?: number): Promise<string>;
+/** Improve an existing prompt given concrete feedback — fix the problem, keep what worked. */
+export declare function refinePrompt(chat: ChatFn, base: string, feedback: string, maxTokens?: number): Promise<string>;
+/** Forge a domain prompt using the top lessons long-term memory recalls — the learn→specialize loop. */
+export declare function forgeFromMemory(chat: ChatFn, domain: string, mem: LongMemory, opts?: {
+    goal?: string;
+    k?: number;
+    tools?: readonly string[];
+}): Promise<string>;

package/dist/userland/sandbox.d.ts

@@ -0,0 +1,14 @@
+import { type ResourceLimits } from 'node:worker_threads';
+import type { ProcessImage } from '../abi/index';
+/** Syscalls a sandbox may invoke by default — a least-privilege subset (no spawn/open/signal). */
+export declare const DEFAULT_ALLOW: readonly ["self", "recv", "send", "remember", "recall", "workingSet", "log", "exit"];
+/** Default heap bound for the worker. The kernel's `mem` quota bounds CONTEXT segments, not the worker's V8
+ *  heap — so without this an untrusted sandbox could allocate freely and OOM the HOST. Generous for real agent
+ *  logic; a breach aborts the worker (→ the process faults and is reaped). Raise via opts.resourceLimits. */
+export declare const DEFAULT_RESOURCE_LIMITS: ResourceLimits;
+/** Run `code` (a function body with `sys`, `args`, `threadId` in scope) isolated in a worker thread. */
+export declare function sandbox(code: string, opts?: {
+    allow?: readonly string[];
+    name?: string;
+    resourceLimits?: ResourceLimits;
+}): ProcessImage;

package/dist/userland/supervisor.d.ts

@@ -0,0 +1,21 @@
+import type { ProcessImage, Pid, Quota } from '../abi/index';
+export type RestartStrategy = 'one_for_one' | 'one_for_all' | 'rest_for_one';
+export type RestartKind = 'permanent' | 'transient' | 'temporary';
+export interface ChildSpec {
+    readonly id: string;
+    readonly image: ProcessImage;
+    readonly args?: unknown;
+    readonly quota?: Quota;
+    readonly restart?: RestartKind;
+}
+export interface SupervisorSpec {
+    readonly strategy: RestartStrategy;
+    readonly children: readonly ChildSpec[];
+    readonly maxRestarts?: number;
+    readonly periodMs?: number;
+    readonly backoffMs?: number;
+    readonly maxBackoffMs?: number;
+    /** Called after each (re)start — handy for tests/observability. */
+    readonly onStart?: (id: string, pid: Pid) => void;
+}
+export declare function supervisor(spec: SupervisorSpec): ProcessImage;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@guangnao/agent-os",
+  "version": "1.0.0",
+  "description": "AgentOS Kernel — a lightweight, type-safe agent operating system in TypeScript",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "agent", "agents", "llm", "microkernel", "operating-system", "scheduler",
+    "capabilities", "object-capability", "sandbox", "wasm", "react-agent", "typescript"
+  ],
+  "author": "guangnao",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "build:watch": "tsc -p tsconfig.build.json -w",
+    "typecheck": "tsc --noEmit",
+    "typecheck:watch": "tsc --noEmit -w",
+    "test": "tsc --noEmit && node --import tsx --test ./test/**/*.test.ts",
+    "test:run": "node --import tsx --test ./test/**/*.test.ts",
+    "test:watch": "node --import tsx --test --watch ./test/**/*.test.ts",
+    "bench": "tsx examples/bench.ts",
+    "pack": "node scripts/bundle.mjs",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.6.0",
+    "esbuild": "^0.28.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT"
+}