@vraxis/agent-v 0.4.0

package/dist/node/skills.js

@@ -0,0 +1,96 @@
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseDocument } from "yaml";
+import { AgentVError } from "../core/index.js";
+function invalid(message) {
+    throw new AgentVError("configuration-invalid", `Invalid Agent Skill: ${message}`);
+}
+function optionalString(value, field, max) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !value.trim() || value.length > max)
+        invalid(`${field} must be a non-empty string no longer than ${max} characters.`);
+    return value;
+}
+function metadata(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        invalid("metadata must be a string-to-string mapping.");
+    const entries = Object.entries(value);
+    if (entries.some(([, item]) => typeof item !== "string"))
+        invalid("metadata values must be strings.");
+    return Object.fromEntries(entries);
+}
+async function files(directory) {
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        return entries.filter((entry) => entry.isFile()).map((entry) => join(directory, entry.name)).sort();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+export async function loadSkillPackage(directory) {
+    const rootPath = await realpath(directory).catch((error) => {
+        if (error.code === "ENOENT")
+            invalid(`directory does not exist: ${directory}`);
+        throw error;
+    });
+    const manifestPath = join(rootPath, "SKILL.md");
+    const source = await readFile(manifestPath, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            invalid(`SKILL.md is missing from ${rootPath}`);
+        throw error;
+    });
+    const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/);
+    if (!match)
+        invalid("SKILL.md must contain YAML frontmatter followed by Markdown instructions.");
+    const document = parseDocument(match[1], { prettyErrors: true, uniqueKeys: true });
+    if (document.errors.length)
+        invalid(document.errors.map((error) => error.message).join("; "));
+    const frontmatter = document.toJS();
+    const name = optionalString(frontmatter.name, "name", 64) ?? invalid("name is required.");
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
+        invalid("name must contain lowercase letters, numbers, and single hyphens only.");
+    if (name !== basename(rootPath))
+        invalid(`name ${name} must match its parent directory name ${basename(rootPath)}.`);
+    const description = optionalString(frontmatter.description, "description", 1024) ?? invalid("description is required.");
+    const compatibility = optionalString(frontmatter.compatibility, "compatibility", 500);
+    const license = optionalString(frontmatter.license, "license", 500);
+    const parsedMetadata = metadata(frontmatter.metadata);
+    const allowedToolsRaw = optionalString(frontmatter["allowed-tools"], "allowed-tools", 2048);
+    const preapprovedTools = allowedToolsRaw?.match(/\S+/g) ?? [];
+    const instructions = match[2].trim();
+    if (!instructions)
+        invalid("the Markdown instruction body must not be empty.");
+    return {
+        rootPath,
+        manifestPath,
+        skill: {
+            id: name,
+            name,
+            version: typeof parsedMetadata?.version === "string" ? parsedMetadata.version : "0.0.0",
+            description,
+            instructions,
+            tools: preapprovedTools,
+            preapprovedTools,
+            license,
+            compatibility,
+            metadata: parsedMetadata,
+            source: { format: "agent-skills", uri: pathToFileURL(manifestPath).href },
+        },
+        scripts: await files(join(rootPath, "scripts")),
+        references: await files(join(rootPath, "references")),
+        assets: await files(join(rootPath, "assets")),
+    };
+}
+export async function discoverSkillPackages(parentDirectory) {
+    const entries = await readdir(parentDirectory, { withFileTypes: true });
+    const directories = entries.filter((entry) => entry.isDirectory()).map((entry) => join(parentDirectory, entry.name)).sort();
+    return Promise.all(directories.map(loadSkillPackage));
+}
+//# sourceMappingURL=skills.js.map

package/dist/node/skills.js.map

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

package/dist/testing/index.d.ts

@@ -0,0 +1,25 @@
+import type { ApprovalPolicy, ApprovalRequest, StructuredGenerationRequest, StructuredGenerationResult, StructuredModelEngine, ToolAgentEngine, ToolAgentRequest, ToolAgentResult } from "../core/contracts.js";
+import { type EventSink } from "../core/events.js";
+import type { EngineDescriptor } from "../core/types.js";
+export declare class StaticApprovalPolicy implements ApprovalPolicy {
+    private readonly decision;
+    readonly requests: ApprovalRequest[];
+    constructor(decision: "approved" | "denied");
+    decide(request: ApprovalRequest): Promise<"approved" | "denied">;
+}
+export declare class FakeStructuredModelEngine implements StructuredModelEngine {
+    private readonly response;
+    readonly descriptor: EngineDescriptor;
+    constructor(response: unknown);
+    generate<T>(request: StructuredGenerationRequest<T>, _events?: EventSink): Promise<StructuredGenerationResult<T>>;
+}
+export declare class FakeToolAgentEngine implements ToolAgentEngine {
+    readonly descriptor: EngineDescriptor;
+    readonly requests: ToolAgentRequest<unknown>[];
+    run<T = string>(request: ToolAgentRequest<T>, events?: EventSink): Promise<ToolAgentResult<T>>;
+    stream<T = string>(request: ToolAgentRequest<T>, events?: EventSink): Promise<{
+        events: AsyncGenerator<never, void, unknown>;
+        result: Promise<ToolAgentResult<T>>;
+    }>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAChN,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,qBAAa,oBAAqB,YAAW,cAAc;IAE7C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IADrC,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAM;gBACb,QAAQ,EAAE,UAAU,GAAG,QAAQ;IACtD,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,GAAG,QAAQ,CAAC;CACvE;AAED,qBAAa,yBAA0B,YAAW,qBAAqB;IAEzD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IADrC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAA2G;gBACnH,QAAQ,EAAE,OAAO;IACxC,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC;CAGxH;AAED,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAwH;IAC7J,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAM;IAC9C,GAAG,CAAC,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,MAAM,GAAE,SAAyB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAQ7G,MAAM,CAAC,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,SAAS;;;;CAC1E"}

package/dist/testing/index.js

@@ -0,0 +1,33 @@
+import { eventTimestamp, noopEventSink } from "../core/events.js";
+export class StaticApprovalPolicy {
+    decision;
+    requests = [];
+    constructor(decision) {
+        this.decision = decision;
+    }
+    async decide(request) { this.requests.push(request); return this.decision; }
+}
+export class FakeStructuredModelEngine {
+    response;
+    descriptor = { id: "fake-model", name: "Fake model", kind: "structured-model", capabilities: ["structured-output"] };
+    constructor(response) {
+        this.response = response;
+    }
+    async generate(request, _events) {
+        return { runId: request.runId ?? "fake-run", output: request.output.parse(this.response), provenance: { engineId: this.descriptor.id, adapterStrategy: "fake-structured-v1" }, durationMs: 0 };
+    }
+}
+export class FakeToolAgentEngine {
+    descriptor = { id: "fake-agent", name: "Fake agent", kind: "tool-agent", capabilities: ["tools", "skills", "structured-output"] };
+    requests = [];
+    async run(request, events = noopEventSink) {
+        this.requests.push(request);
+        const runId = request.runId ?? "fake-run";
+        await events.emit({ type: "run.started", runId, timestamp: eventTimestamp(), scope: request.scope, provenance: { engineId: this.descriptor.id, adapterStrategy: "fake-tool-agent-v1" } });
+        const output = request.output ? request.output.parse({ ok: true }) : "ok";
+        await events.emit({ type: "run.completed", runId, timestamp: eventTimestamp(), scope: request.scope, durationMs: 0 });
+        return { runId, output, text: "ok", steps: 1, provenance: { engineId: this.descriptor.id, adapterStrategy: "fake-tool-agent-v1" }, durationMs: 0 };
+    }
+    async stream(request, events) { return { events: (async function* () { })(), result: this.run(request, events) }; }
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

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

package/examples/approved-tool.ts

@@ -0,0 +1,56 @@
+import {
+  defineOutput,
+  defineTool,
+  type ApprovalPolicy,
+} from "@vraxis/agent-v";
+
+export const explicitApproval: ApprovalPolicy = {
+  async decide(request) {
+    // Replace this example decision with the host application's reviewed UI state.
+    return request.metadata?.founderApproved === true ? "approved" : "denied";
+  },
+};
+
+export function createPublishContributionTool(publish: (body: string) => Promise<{ channelId: string }>) {
+  return defineTool({
+    name: "publish-contribution",
+    version: "1.0.0",
+    description: "Publish one reviewed contribution through the selected channel.",
+    input: defineOutput({
+      name: "publish-contribution-input",
+      jsonSchema: {
+        type: "object",
+        properties: { body: { type: "string" } },
+        required: ["body"],
+        additionalProperties: false,
+      },
+      parse(value) {
+        const body = (value as { body?: unknown }).body;
+        if (typeof body !== "string" || !body.trim()) throw new Error("body is required");
+        return { body };
+      },
+    }),
+    output: defineOutput({
+      name: "publish-contribution-output",
+      jsonSchema: {
+        type: "object",
+        properties: { channelId: { type: "string" } },
+        required: ["channelId"],
+        additionalProperties: false,
+      },
+      parse(value) {
+        const channelId = (value as { channelId?: unknown }).channelId;
+        if (typeof channelId !== "string" || !channelId) throw new Error("channelId is required");
+        return { channelId };
+      },
+    }),
+    risk: "external-side-effect",
+    sideEffect: "non-idempotent",
+    requiredPermissions: ["contributions:publish"],
+    requiresApproval: true,
+    timeoutMs: 15_000,
+    execute({ body }) {
+      return publish(body);
+    },
+  });
+}

package/examples/basic-ai-sdk.ts

@@ -0,0 +1,29 @@
+import type { LanguageModel } from "ai";
+import {
+  AgentV,
+  EngineRegistry,
+  defineAgent,
+  localExecutionScope,
+} from "@vraxis/agent-v";
+import { AiSdkToolAgentEngine } from "@vraxis/agent-v/ai-sdk";
+
+export function createBasicAiAgent(model: LanguageModel) {
+  const engine = new AiSdkToolAgentEngine({
+    id: "primary-agent",
+    name: "Primary AI agent",
+    model,
+    adapterStrategy: "example-ai-sdk-v7",
+  });
+  const runtime = new AgentV({ engines: new EngineRegistry().register(engine) });
+  const agent = defineAgent({
+    id: "assistant",
+    name: "Assistant",
+    engineId: engine.descriptor.id,
+    instructions: "Answer clearly using only the context supplied by the host.",
+    skills: [],
+    tools: [],
+    requiredCapabilities: ["streaming"],
+    maxSteps: 8,
+  });
+  return { runtime, agent, scope: localExecutionScope("example-app") };
+}

package/examples/custom-model-resolver.ts

@@ -0,0 +1,14 @@
+import { AiSdkToolAgentEngine, type AiSdkModelResolver } from "@vraxis/agent-v/ai-sdk";
+
+export function createResolvedModelEngine(resolveModel: AiSdkModelResolver) {
+  return new AiSdkToolAgentEngine({
+    id: "profiled-agent",
+    name: "Profile-resolved agent",
+    provider: "host-resolved",
+    adapterStrategy: "host-model-resolver-v1",
+    resolveModel,
+  });
+}
+
+// A resolver should use selection.credentialRef and selection.scope to obtain
+// a provider model without placing credential values in agent-v configuration.

package/examples/filesystem-skill.ts

@@ -0,0 +1,12 @@
+import { ExtensionRegistry, defineExtension } from "@vraxis/agent-v";
+import { loadSkillPackage } from "@vraxis/agent-v/node";
+
+export async function registerFilesystemSkill(directory: string, extensions = new ExtensionRegistry()) {
+  const loaded = await loadSkillPackage(directory);
+  extensions.use(defineExtension({
+    id: `${loaded.skill.id}-package`,
+    version: loaded.skill.version,
+    skills: [loaded.skill],
+  }));
+  return { extensions, loaded };
+}

package/examples/local-cli.ts

@@ -0,0 +1,28 @@
+import { defineOutput, localExecutionScope } from "@vraxis/agent-v";
+import { LocalCliRuntimeEngine } from "@vraxis/agent-v/local-cli";
+
+export function createRepositorySummaryRequest(workspacePath: string) {
+  const engine = new LocalCliRuntimeEngine();
+  const request = {
+    runtimeId: "codex",
+    workspacePath,
+    workspaceAccess: "read-only" as const,
+    scope: localExecutionScope("repository-summary"),
+    input: { prompt: "Summarize the repository architecture using only evidence in the workspace." },
+    output: defineOutput({
+      name: "repository-summary",
+      jsonSchema: {
+        type: "object",
+        properties: { summary: { type: "string" } },
+        required: ["summary"],
+        additionalProperties: false,
+      },
+      parse(value) {
+        const summary = (value as { summary?: unknown }).summary;
+        if (typeof summary !== "string") throw new Error("summary is required");
+        return { summary };
+      },
+    }),
+  };
+  return { engine, request };
+}

package/examples/ollama.ts

@@ -0,0 +1,15 @@
+import { EngineRegistry } from "@vraxis/agent-v";
+import { OllamaRuntime } from "@vraxis/agent-v/ollama";
+
+export function createLocalOllama(model: string, baseURL = "http://127.0.0.1:11434") {
+  const ollama = new OllamaRuntime({ defaultModel: model, baseURL });
+  return {
+    ollama,
+    async registerWhenReady(engines: EngineRegistry) {
+      const readiness = await ollama.inspect();
+      if (readiness.availability !== "ready") return readiness;
+      engines.register(ollama.agent).register(ollama.structured);
+      return readiness;
+    },
+  };
+}

package/examples/sessions-and-events.ts

@@ -0,0 +1,18 @@
+import {
+  AgentV,
+  EngineRegistry,
+  MemoryRunEventStore,
+  MemorySessionStore,
+  type ToolAgentEngine,
+} from "@vraxis/agent-v";
+
+export function createStatefulRuntime(engine: ToolAgentEngine) {
+  const sessions = new MemorySessionStore();
+  const runEvents = new MemoryRunEventStore();
+  const runtime = new AgentV({
+    engines: new EngineRegistry().register(engine),
+    sessions,
+    runEvents,
+  });
+  return { runtime, sessions, runEvents };
+}

package/examples/smoke.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { MockLanguageModelV4 } from "ai/test";
+import { EngineRegistry } from "@vraxis/agent-v";
+import { createBasicAiAgent } from "./basic-ai-sdk.ts";
+import { createPublishContributionTool } from "./approved-tool.ts";
+import { createLocalOllama } from "./ollama.ts";
+import { createRepositorySummaryRequest } from "./local-cli.ts";
+import { createStatefulRuntime } from "./sessions-and-events.ts";
+import { createResolvedModelEngine } from "./custom-model-resolver.ts";
+import { registerFilesystemSkill } from "./filesystem-skill.ts";
+
+const usage = {
+  inputTokens: { total: 1, noCache: 1, cacheRead: undefined, cacheWrite: undefined },
+  outputTokens: { total: 1, text: 1, reasoning: undefined },
+};
+const model = new MockLanguageModelV4({
+  doGenerate: async () => ({
+    content: [{ type: "text", text: "example-ok" }],
+    finishReason: { unified: "stop", raw: undefined },
+    usage,
+    warnings: [],
+  }),
+});
+
+const basic = createBasicAiAgent(model);
+const result = await basic.runtime.run(basic.agent, { scope: basic.scope, input: { prompt: "Verify the example." } });
+assert.equal(result.text, "example-ok");
+
+assert.equal(createPublishContributionTool(async () => ({ channelId: "devto" })).requiresApproval, true);
+assert.equal(createLocalOllama("example-model").ollama.agent.descriptor.provider, "ollama");
+assert.equal(createRepositorySummaryRequest(process.cwd()).request.workspaceAccess, "read-only");
+assert.equal(createStatefulRuntime(basic.runtime.engines.require("primary-agent", "tool-agent")).sessions.constructor.name, "MemorySessionStore");
+assert.equal(createResolvedModelEngine(() => model).descriptor.id, "profiled-agent");
+assert.equal((await registerFilesystemSkill("skills/agent-v")).loaded.skill.id, "agent-v");
+assert.equal(new EngineRegistry().list().length, 0);

package/examples/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["./**/*.ts"]
+}

package/llms.txt

@@ -0,0 +1,13 @@
+# agent-v
+
+> Provider-neutral TypeScript execution contracts for scoped agents, validated tools, approvals, AI SDK models, local coding runtimes, Ollama, sessions, events, and portable skills.
+
+## Canonical guidance
+
+- README.md — supported consumer surface and installation
+- ARCHITECTURE.md — dependency, authority, and product boundaries
+- compatibility.json — machine-readable adapter strategies and dependency ranges
+- skills/agent-v/SKILL.md — portable coding-agent integration instructions
+- examples/ — compiled and executed consumer patterns
+
+Do not infer APIs from other agent frameworks. Verify imports against the installed package exports and type declarations.

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@vraxis/agent-v",
+  "version": "0.4.0",
+  "description": "A provider-neutral engine for building inspectable, extensible agentic products.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vequan23/agent-v.git"
+  },
+  "homepage": "https://github.com/Vequan23/agent-v#readme",
+  "bugs": "https://github.com/Vequan23/agent-v/issues",
+  "keywords": [
+    "agents",
+    "ai",
+    "tools",
+    "skills",
+    "local-first",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "bin": {
+    "agent-v": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md",
+    "AGENTS.md",
+    "compatibility.json",
+    "llms.txt",
+    "examples",
+    "skills",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./ai-sdk": {
+      "types": "./dist/adapters/ai-sdk/index.d.ts",
+      "import": "./dist/adapters/ai-sdk/index.js"
+    },
+    "./local-cli": {
+      "types": "./dist/adapters/local-cli/index.d.ts",
+      "import": "./dist/adapters/local-cli/index.js"
+    },
+    "./ollama": {
+      "types": "./dist/adapters/ollama/index.d.ts",
+      "import": "./dist/adapters/ollama/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./compatibility": "./compatibility.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --import tsx --test test/*.test.ts",
+    "test:examples": "tsc --noEmit -p examples/tsconfig.json && node --import tsx examples/smoke.ts",
+    "test:package": "node test/package-smoke.mjs",
+    "check": "npm run typecheck && npm test && npm run build && npm run test:examples && npm run test:package && npm pack --dry-run --cache .npm-cache"
+  },
+  "peerDependencies": {
+    "ai": ">=7.0.0 <8",
+    "ai-sdk-ollama": ">=4.2.0 <5"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "ai-sdk-ollama": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "ai": "^7.0.79",
+    "ai-sdk-ollama": "^4.2.0",
+    "tsx": "^4.23.12",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
+}

package/skills/agent-v/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: agent-v
+description: Integrate or extend the agent-v TypeScript library for scoped agents, tools, approvals, AI SDK models, local coding runtimes, Ollama, sessions, events, or Agent Skills.
+metadata:
+  version: "0.4.0"
+---
+
+# Use agent-v accurately
+
+Read the installed package's `README.md` and type declarations before coding. Do not infer methods from other agent frameworks or older `agent-v` examples.
+
+## Route by execution need
+
+- Use `@vraxis/agent-v` for contracts, scopes, agent blueprints, tool/skill definitions, registries, and policies.
+- Use `@vraxis/agent-v/ai-sdk` for structured model calls and tool-loop agents backed by AI SDK 7.
+- Use `@vraxis/agent-v/ollama` only for an Ollama model server. Inspect readiness before registration.
+- Use `@vraxis/agent-v/local-cli` when Codex, OpenCode, Claude Code, or another coding CLI must operate on a workspace.
+- Use `@vraxis/agent-v/node` for local sessions, run ledgers, diagnostics, and filesystem Agent Skills.
+- Use `@vraxis/agent-v/testing` for deterministic tests without provider calls.
+
+Do not substitute a coding CLI adapter for an ordinary model provider or treat Ollama as a coding-workspace runtime.
+
+## Preserve the execution contract
+
+- Supply `ExecutionScope` on every run. Use `localExecutionScope()` only for genuinely single-user local applications.
+- Declare every agent's skills, tools, and required capabilities explicitly.
+- Give each tool stable input and output contracts, version, risk, side-effect classification, permissions, approval behavior, and timeout.
+- Require approval for external side effects and privileged actions. Never weaken policy after a denial or adapter failure.
+- Treat artifacts as host-supplied evidence. Keep product-specific evidence judgment, retrieval, prompts, and UX in the consuming product.
+- Persist returned normalized events and provenance when runs must be auditable.
+- Use readiness results and capability declarations rather than assuming an installed CLI or daemon is usable.
+
+## Implement and verify
+
+Use the closest maintained example under `examples/` as the starting point. Read [references/integration-patterns.md](references/integration-patterns.md) for composition rules and common failure modes when creating or reviewing an integration.
+
+Run the consuming project's typecheck and tests. In this repository, run `npm run check`; it compiles and executes all examples against the built package surface.
+
+Do not make live provider calls, start daemons, download models, publish, or modify external systems unless the user authorized that action.

package/skills/agent-v/references/integration-patterns.md

@@ -0,0 +1,57 @@
+# Integration patterns
+
+## Contents
+
+- Choosing an engine
+- Defining tools safely
+- Composing an agent
+- Persistence and provenance
+- Common mistakes
+
+## Choosing an engine
+
+Choose from required behavior, not provider preference:
+
+| Need | Import | Contract |
+| --- | --- | --- |
+| One schema-bound model operation | `@vraxis/agent-v/ai-sdk` | `StructuredModelEngine` |
+| Bounded model/tool loop | `@vraxis/agent-v/ai-sdk` | `ToolAgentEngine` |
+| Local or remote Ollama model | `@vraxis/agent-v/ollama` | AI SDK engines through `OllamaRuntime` |
+| Coding agent against a workspace | `@vraxis/agent-v/local-cli` | `CodingRuntimeEngine` |
+| Local persistence or diagnostics | `@vraxis/agent-v/node` | Store and doctor ports |
+
+An executable being installed is not readiness evidence. Inspect first; use a bounded live probe only when its credentials, cost, and external effects are authorized.
+
+## Defining tools safely
+
+Use `defineTool()` and provide all required authority metadata. `risk` describes impact; `sideEffect` describes replay behavior; `requiredPermissions` is checked against the current execution scope. `requiresApproval` is mandatory for `external-side-effect` and `privileged` risks.
+
+Validate the tool's returned value with `output`. Tool implementation bugs must not become unvalidated model context.
+
+Keep product-specific tools with their product until their contract and safety semantics are demonstrably reusable.
+
+## Composing an agent
+
+Use `defineAgent()` with either `engineId` or `profileId`, never both. Profiles select deploy-time engine, model, credential reference, and provider options without changing the blueprint.
+
+When skills are selected, their combined tool allowlist constrains the blueprint. A mismatch is an agent-definition error, not a reason to silently omit a tool.
+
+Declare only capabilities the workflow actually needs. Selection should fail if the engine cannot enforce one.
+
+## Persistence and provenance
+
+Sessions and event queries are isolated by tenant, project, principal, and optional engagement. Preserve that scope when replacing the reference stores.
+
+Every `RunProvenance` has an `adapterStrategy`. Local CLI and Ollama runs also include the detected runtime version when available. Store provenance with outcomes so upstream changes can be correlated with regressions.
+
+Configuration contains credential references. Resolve credential values inside the host's model resolver; never write values to config, events, sessions, examples, or fixtures.
+
+## Common mistakes
+
+- Importing provider SDK types into product domain code instead of registering an adapter.
+- Omitting `ExecutionScope` or granting wildcard permissions outside a local single-user application.
+- Treating a skill's `allowed-tools` metadata as approval for side effects.
+- Assuming OpenCode can enforce read-only access or Cursor can guarantee structured output when their current adapter capabilities say otherwise.
+- Registering Ollama without checking that the daemon is reachable and the selected model is installed.
+- Retrying malformed output by removing the schema requirement.
+- Copying examples without compiling them against the installed package version.