ai-harness

AI Harness

Use This For

Use this skill for work involving @purista/harness, @purista/harness-openai, or addon packages named @purista/harness-*.

Core Model

@purista/harness is a standalone, ESM-only agent runtime. It composes typed model aliases, tools, skills, agents, workflows, state, memory, sandboxing, logging, telemetry, and streaming behind one session API.

Keep these layers separate:

• configuration: defineHarness() registers adapters, defaults, models, tools, skills, agents, and workflows
• execution: harness.getSession(id) returns typed session.agents.* and session.workflows.*
• adapter code: provider, state, memory, sandbox, MCP, durable runtime, logger, and telemetry ports
• application integration: HTTP/SSE, queues, persistence, auth, and business state stay outside the harness unless represented by a port or tool
• optional governance: policy-as-code for tool decisions, approvals, audit, and policy-pack adapters is configured only when needed; ordinary agents do not require policy setup

Hard Rules

• Use defineHarness() as the sole construction path. Do not invent standalone defineAgent, defineWorkflow, defineTool, defineSkill, or defineModel helpers.
• Use defineHarnessModule<Required>()('module.id', { register }) only for local static composition. Modules contribute normal definitions to the caller's builder; they are not remote plugins, manifests, loaders, or lifecycle owners. Module callbacks cannot build or recursively use a harness.
• Use @purista/harness-agent-plugins only for data-only Agent Plugins v1 packages. Require application-owned source/digest/trust approval, inspect diagnostics, then bind selected skills and MCP tools explicitly. A selected stdio server also needs an existing caller-owned data directory and an isolating sandbox implementing both spawn and mountReadOnly; the local host-directory sandbox does not qualify. Never load package code, auto-install dependencies, auto-expose tools, or accept plugin-provided credentials.
• MCP is a clean v2 integration pinned to 2026-07-28: use @modelcontextprotocol/client, modern stateless Streamable HTTP, and a spawn-capable sandbox for stdio. Do not add legacy MCP, HTTP+SSE, one-shot exec, or compatibility fallbacks.
• Module definition ids compose additively. Treat duplicate module/definition ids as configuration errors; inspect only harness.inspect().modules for content-free provenance.
• Preserve builder inference by declaring models before agents and agents before workflows.
• Use inline helper callbacks for agents and workflows: .agents(({ agent }) => ({ ... })) and .workflows(({ workflow }) => ({ ... })).
• Child-agent delegation is disabled by default. Any workflow that calls ctx.agents.<id>(input) must declare workflow.delegation; prefer delegation.agents allowlists and document budget/model overrides there.
• Use ctx.fanOut(...) for ordered, bounded workflow batches. Use ctx.childTasks.start(...) only for workflow-owned isolated background work; task turns queue under the delegation parallel ceiling and never inherit parent history or widen agent permissions.
• mode: 'continuable' keeps an isolated in-process task conversation open for explicit send(...) turns and close(). Do not use it for durable workflow execution or claim cross-process recovery; use an application queue/worker adapter when work must survive a restart.
• Configure defaults.historyRetention for durable conversations that need a storage bound. It retains complete newest turns only and requires an atomic StateStore.replaceMessages; maxBytes is serialized UTF-8 storage size, never a token estimate. Use the model's context window/token tooling separately when selecting request context.
• For at-least-once direct-agent delivery, pass the transport's stable message or delivery id as InvokeOptions.idempotencyKey. Replaying the same successful invocation returns its recorded output without a second provider call or transcript; never derive this key from prompt content.
• Use session.release() at the end of an idle request to close live sandbox/MCP resources while preserving StateStore-backed history and runs. session.close() is destructive: it deletes the session record, history, runs, and persisted events.
• Declare model capabilities truthfully. Capability arrays gate both TypeScript handles and runtime behavior.
• Prefer object / object_stream for structured generation. Do not use legacy json capability names.
• Keep RAG orchestration in application/workflow code. The harness provides embeddings and rerank operations, not vector storage.
• Keep HTTP/SSE protocol mapping outside the harness. Harness streams are typed RunEvent values.
• Do not import PURISTA framework packages from harness or harness addon packages.
• Do not leak prompts, documents, tool inputs, or secrets through logs or telemetry. telemetry({ contentCaptureMode: 'NO_CONTENT' }) is the production default.
• Skills are mounted files, not prompt text. Register directories with .skills(...), allowlist skill ids per agent, keep read available for skill-backed agents, and verify SKILL.md bodies are not inlined into prompts, logs, traces, or persisted events.
• Prefer ctx.metrics for application-owned counters, histograms, and operation durations inside workflow handlers, custom agent handlers, and TypeScript tool handlers. Do not call the low-level TelemetryShim directly for app metrics.
• Governance policy is optional and late-bound through .governance(...) after agents/workflows are declared. Keep simple use cases on per-agent permissions; use governance only for composable/audited policy, approval, or external policy-pack interoperability.