@one-agent-ctx/native-runtime 0.0.0-stage → 0.1.4

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# Agent Context OS
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local Rust infrastructure for coding/general agents. It provides four bounded
+capabilities and does nothing until the host explicitly calls it or registers a
+directory:
+
+- recall confirmed preferences, evidence-backed mistakes and source-bound general memories;
+- search and version-bind executable Skill packages;
+- search knowledge inside explicitly registered Resource directory subtrees;
+- turn verified repeated workflows into replayable Skill drafts, then install
+  them only after the host records a successful clean replay.
+
+It does not crawl the working directory, auto-install Skills, execute generated
+scripts, or treat Resource text as agent instructions.
+
+## Build and verify
+
+```bash
+cargo build --workspace --all-features
+cargo test --workspace --all-features
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+## Run
+
+Native JSON Lines transport:
+
+```bash
+cargo run -p ctxos -- serve --stdio --data-dir /absolute/path/to/ctxos-data
+```
+
+MCP stdio transport:
+
+```bash
+cargo run -p ctxos --features mcp -- serve --mcp --data-dir /absolute/path/to/ctxos-data
+```
+
+Host-only control channel (same process, same Store writer):
+
+```bash
+cargo run -p ctxos --features mcp -- serve --mcp --control --data-dir /absolute/path/to/ctxos-data
+```
+
+The control endpoint is published as owner-only `<data-dir>/control.json`
+(`version`, `pid`, loopback `port`, `started_at_unix_ms`). It is for host
+operations such as durable-context assembly, inbox listing, confirmation and
+forget; it is not a model-facing tool. MCP remains the model transport.
+
+`stdout` is reserved for the selected protocol. The SQLite store, immutable
+installed Skill versions, and generated drafts live below `data-dir`.
+
+## Explicit directory registration
+
+A host may call `register_root` through the native protocol, or pass an absolute
+config file:
+
+```toml
+data_dir = { encoding = "utf8", value = "/absolute/ctxos-data" }
+
+[[roots]]
+kind = "resource"
+scope = "global"
+path = { encoding = "utf8", value = "/root/product" }
+
+[[roots]]
+kind = "skill"
+scope = "global"
+path = { encoding = "utf8", value = "/root/skills" }
+```
+
+```bash
+cargo run -p ctxos -- serve --stdio --config /absolute/config.toml
+```
+
+Registration starts a recursive native watcher and performs an authoritative
+initial reconcile. Queries must still pass a non-empty `within` list. Searching
+`/root/product/taobao` cannot return `/root/product/pdd`; searching
+`/root/product` can return both. Multiple authorized subtrees form a union.
+
+Paths use the tagged `NativePath` wire representation so Unix non-UTF-8 bytes
+and Windows UTF-16 paths are not silently corrupted. Skill package members use
+portable `/`-separated relative paths and reject traversal, symlinks, reserved
+Windows names, case collisions, and Unicode-normalization collisions.
+
+## Agent lifecycle
+
+The intended stable hooks are:
+
+1. task start: `recall_memories`;
+2. planning: `search_skills`, then `load_skill` with the returned version/hash;
+3. knowledge gap: `search_resources` with explicit directories;
+4. task completion/correction: `record_episode`;
+5. repeated verified workflow: `draft_skill`, execute its replay plan in the
+   host, `record_draft_replay`, then user-confirmed `install_skill`.
+
+The MCP tool surface covers the agent loop, explicit model extraction, resource
+understanding and context assembly. Host management operations such as directory
+authorization, replay evidence and installation remain on native `ctxos.v1`;
+they are not implicitly granted to agents. The current protocol contract is in
+`docs/refactor/42-ctxos-api.md`. (A pure-Go JSON Lines client formerly lived in
+`sdk/go/ctxos`; it was removed 2026-09-30 — zero consumers. The historical
+HTTP/FFI SDK of the retired generation was a different protocol.)
+
+Context assembly is read-only. Hosts supply the actual turn and confirm only
+the rendered entries after flushing and reading back their durable context
+snapshot. `confirm_context_injection` atomically records the cooldown projection
+and idempotent receipt; it is a host management operation, not an MCP tool.
+Saved-memory deletion, provenance and the context-recall wipe behind the
+schema-v34 stamp are in [memory integrity](docs/refactor/58-memory-integrity.md).
+Schema 33 collided with the parallel epoch-2 identity/TTL cutover; the merged
+build defines 34, and any database stamped by either 33 lineage is archived by
+the epoch gate rather than opened.
+
+## Upstream reuse and current backend decision
+
+Production retrieval uses Qdrant Edge and upstream BM25/RRF code; exact-dense
+remains a correctness oracle. OpenViking algorithms, prompts and schemas are
+ported into resource, memory, session, assembly and Skill learning paths with
+explicit source and approval safeguards. Remote models require explicit host
+configuration. Every reuse decision and its limits are recorded in
+`provenance/reuse-ledger.toml`; integration is not proof of overall superiority.
+Current tests and remaining migration gaps are recorded in
+`docs/refactor/54-implementation-evidence.md` and `docs/refactor/56-long-run-delivery.md`.
+Cross-compilation must not be described as native Windows execution.
+
+For the Node package, the [npm native qualification and release runbook](docs/refactor/06-platform-and-path-portability.md#npm-原生包资格)
+defines the six macOS/Linux/Windows targets, NAPI and CLI native qualification,
+runtime receipts, and explicit release prerequisites.
+
+See `docs/refactor/README.md` for the design source of truth and
+`provenance/qdrant-edge-qualification.md` for the qualification evidence.

package/cli.d.ts

@@ -0,0 +1,2 @@
+/** Absolute path to the verified CLI in the installed platform package. */
+export function cliPath(): string;

package/cli.js

@@ -0,0 +1,26 @@
+'use strict';
+const { resolvePlatform } = require('./platform.js');
+const { createHash } = require('node:crypto');
+const { readFileSync } = require('node:fs');
+
+/** Resolve the CLI distributed with the exact native platform package. */
+function cliPath() {
+  const platform = resolvePlatform(process.platform, process.arch,
+    process.platform === 'linux' ? process.report.getReport().header.glibcVersionRuntime : undefined);
+  const packageName = `@one-agent-ctx/runtime-${platform.id}`;
+  try {
+    const binary = require.resolve(`${packageName}/${platform.cli}`);
+    const receipt = require(`${packageName}/artifact.json`);
+    const version = require('./package.json').version;
+    const digest = createHash('sha256').update(readFileSync(binary)).digest('hex');
+    if (receipt.version !== version || receipt.platform !== platform.id || receipt.cliSha256 !== digest) {
+      throw new Error(`${packageName} CLI bytes differ from its published artifact identity`);
+    }
+    return binary;
+  } catch (cause) {
+    if (cause.code !== 'MODULE_NOT_FOUND') throw cause;
+    throw new Error(`${packageName} CLI is not installed. Install @one-agent-ctx/native-runtime with optional dependencies enabled.`, { cause });
+  }
+}
+
+module.exports = { cliPath };

package/index.d.ts

@@ -0,0 +1,24 @@
+/** Agent Context OS native runtime (napi-rs binding). */
+export interface CtxosCapabilities {
+  readonly version: string;
+  readonly methods: readonly string[];
+  readonly generationConfigured: boolean;
+}
+export interface EmbedderConfig {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  readonly model: string;
+  readonly dimension: number;
+}
+export interface GeneratorConfig {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  readonly model: string;
+  readonly maxCalls: number;
+}
+export class CtxosRuntime {
+  constructor(dataDir: string);
+  static withModels(dataDir: string, embedder?: EmbedderConfig | null, generator?: GeneratorConfig | null): CtxosRuntime;
+  handle(requestJson: string): Promise<string>;
+  capabilities(): CtxosCapabilities;
+}

package/index.js

@@ -0,0 +1,15 @@
+'use strict';
+const { resolvePlatform } = require('./platform.js');
+const platform = resolvePlatform(process.platform, process.arch,
+  process.platform === 'linux' ? process.report.getReport().header.glibcVersionRuntime : undefined);
+const packageName = `@one-agent-ctx/runtime-${platform.id}`;
+let binaryPath;
+try {
+  binaryPath = require.resolve(`${packageName}/ctxos_napi.node`);
+} catch (cause) {
+  if (cause.code !== 'MODULE_NOT_FOUND') throw cause;
+  throw new Error(`${packageName} is not installed. Install @one-agent-ctx/native-runtime with optional dependencies enabled.`, { cause });
+}
+// Preserve native loader errors: a corrupt or incompatible binary cannot be
+// treated as an absent optional dependency or silently replaced.
+module.exports = require(binaryPath);

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@one-agent-ctx/native-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "description": "Agent Context OS - native Node.js binding (napi-rs). Memories, skills, resources, self-evolution.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "platform.js",
+    "cli.js",
+    "cli.d.ts"
+  ],
+  "optionalDependencies": {
+    "@one-agent-ctx/runtime-darwin-arm64": "0.1.4",
+    "@one-agent-ctx/runtime-darwin-x64": "0.1.4",
+    "@one-agent-ctx/runtime-linux-arm64": "0.1.4",
+    "@one-agent-ctx/runtime-linux-x64": "0.1.4",
+    "@one-agent-ctx/runtime-win32-x64-msvc": "0.1.4",
+    "@one-agent-ctx/runtime-win32-arm64-msvc": "0.1.4"
+  },
+  "scripts": {
+    "test:npm": "node --test tests/harness/npm-release.test.mjs",
+    "release:matrix": "node scripts/npm-release.mjs matrix",
+    "release:stage": "node scripts/npm-release.mjs stage",
+    "release:verify": "node scripts/npm-release.mjs verify",
+    "release:publish": "node scripts/npm-release.mjs publish",
+    "release:stage-cross": "node scripts/npm-release.mjs stage-cross",
+    "release:publish-local": "node scripts/npm-release.mjs publish-local"
+  },
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wocrab/one-ctx.git"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/platform.js

@@ -0,0 +1,19 @@
+'use strict';
+
+// One distribution roster drives package resolution and release qualification.
+const platforms = Object.freeze([
+  { id: 'darwin-arm64', os: 'darwin', cpu: 'arm64', target: 'aarch64-apple-darwin', runner: 'macos-15', library: 'libctxos_napi.dylib', cli: 'ctxos' },
+  { id: 'darwin-x64', os: 'darwin', cpu: 'x64', target: 'x86_64-apple-darwin', runner: 'macos-15-intel', library: 'libctxos_napi.dylib', cli: 'ctxos' },
+  { id: 'linux-arm64', os: 'linux', cpu: 'arm64', target: 'aarch64-unknown-linux-gnu', runner: 'ubuntu-24.04-arm', library: 'libctxos_napi.so', cli: 'ctxos' },
+  { id: 'linux-x64', os: 'linux', cpu: 'x64', target: 'x86_64-unknown-linux-gnu', runner: 'ubuntu-24.04', library: 'libctxos_napi.so', cli: 'ctxos' },
+  { id: 'win32-arm64-msvc', os: 'win32', cpu: 'arm64', target: 'aarch64-pc-windows-msvc', runner: 'windows-11-arm', library: 'ctxos_napi.dll', cli: 'ctxos.exe' },
+  { id: 'win32-x64-msvc', os: 'win32', cpu: 'x64', target: 'x86_64-pc-windows-msvc', runner: 'windows-2025', library: 'ctxos_napi.dll', cli: 'ctxos.exe' },
+].map(Object.freeze));
+
+function resolvePlatform(os, cpu, glibcVersion) {
+  const platform = platforms.find(entry => entry.os === os && entry.cpu === cpu);
+  if (!platform) throw new Error(`@one-agent-ctx/native-runtime does not support ${os}-${cpu}`);
+  return platform;
+}
+
+module.exports = { platforms, resolvePlatform };