@yos-ai/agent-engine

Node.js Agent Engine containing session/run orchestration, permission gates, persistence ports and the Pi Agent runtime adapter.

import { AgentEngine, AllowListPolicy } from "@yos-ai/agent-engine";
import { PiAgentRuntime } from "@yos-ai/agent-engine/pi";
import {
  InMemoryEventStore,
  InMemoryModelCredentialStore,
  InMemorySessionStore,
} from "@yos-ai/agent-engine/testing";

const engine = new AgentEngine({
  runtime: new PiAgentRuntime(),
  sessions: new InMemorySessionStore(),
  events: new InMemoryEventStore(),
  credentials: new InMemoryModelCredentialStore(),
  permissions: new AllowListPolicy([]),
});

SQLite session persistence

Node/Electron hosts can persist sessions with the built-in Node SQLite adapter. It enables foreign keys, WAL mode, schema versioning, optimistic session revisions, ordered event replay, and cascading deletion. Pi's complete transcript, including tool calls and tool results, is stored in the session runtime snapshot.

import { AgentClient } from "@yos-ai/agent-sdk";
import { createLocalAgentTransport } from "@yos-ai/agent-engine/local";
import { getDefaultYosDatabasePath } from "@yos-ai/agent-engine/sqlite";

const client = new AgentClient(createLocalAgentTransport({
  ownerId: "local-user",
  databasePath: getDefaultYosDatabasePath(), // %APPDATA%/YOS/agent.db
}));

const sessions = await client.listSessions();
const history = await client.listEvents(sessions[0]!.id, { after: 0, limit: 1000 });

Model API keys are encrypted before being written to SQLite and are never included in session views or Engine events. The default portable codec has the same limitations as the model config codec; production Electron applications should provide OS-backed encryption.

Local model configuration

Node and Electron main-process consumers can import EncryptedModelConfigFileStore from @yos-ai/agent-engine/config-file. It persists the complete model configuration, including the API key, as an AES-256-GCM encrypted payload at %APPDATA%\YOS\config.json by default.

The built-in codec uses an application key and prevents plaintext credentials on disk, but it is not an OS credential vault. Electron applications can provide a custom ModelConfigFileCodec backed by safeStorage.

Loop tools

@yos-ai/agent-engine/tools exports the safe current_time and calculator tools, plus adapters for Pi's built-in read, write, edit, and bash harness tools. Coding tools require an explicit Node execution environment and are disabled by default in the local Engine factory:

const transport = createLocalAgentTransport({
  ownerId: "local-user",
  codingTools: { cwd: process.cwd() },
});

The cwd is the base directory for relative paths and commands, not an operating-system sandbox. Host applications should combine coding tools with an appropriate permission policy and OS/container isolation before exposing them to untrusted users.

Model baseUrl values are canonical service roots without /v1. The Engine resolves OpenAI requests to {baseUrl}/v1/chat/completions and Anthropic requests to {baseUrl}/v1/messages. Legacy values ending in /v1 or a complete operation path are migrated automatically.

YOS system prompt

Every Pi run receives an Engine-built system prompt containing the YOS智能助手 identity, execution and truthfulness rules, permission-aware tool-calling guidance, a catalog generated from the tools actually registered for that run, and a non-sensitive runtime summary. SessionConfig.systemPrompt is appended as additional session instructions; credentials and Base URLs are never included.