@vraxis/agent-v 0.6.0 → 0.7.1

package/examples/providers.ts

@@ -0,0 +1,35 @@
+import {
+  AgentV,
+  EngineRegistry,
+  MemoryConfigStore,
+  defineAgent,
+  defaultConfig,
+  type CredentialResolver,
+} from "@vraxis/agent-v";
+import { ProviderRuntime, defineProviderProfile } from "@vraxis/agent-v/providers";
+
+export function createHostedProviderAgent(credentials: CredentialResolver) {
+  const providers = new ProviderRuntime({ credentials });
+  const profile = defineProviderProfile({
+    id: "primary-provider",
+    name: "Primary hosted model",
+    provider: "openai",
+    credentialRef: "keychain://providers/openai",
+  });
+  const config = new MemoryConfigStore({ ...defaultConfig(), profiles: [profile] });
+  const runtime = new AgentV({
+    config,
+    engines: new EngineRegistry().register(providers.agent).register(providers.structured),
+  });
+  const agent = defineAgent({
+    id: "hosted-assistant",
+    name: "Hosted assistant",
+    profileId: profile.id,
+    instructions: "Answer clearly using only context supplied by the host.",
+    skills: [],
+    tools: [],
+    requiredCapabilities: ["streaming"],
+    maxSteps: 8,
+  });
+  return { runtime, agent, profile, providers };
+}

package/examples/runtime-kit.ts

@@ -0,0 +1,25 @@
+import { createAgentRuntime } from "@vraxis/agent-v/runtime";
+import { createStandardApprovalPolicy } from "@vraxis/agent-v/tools";
+import { createWorkspaceTools } from "@vraxis/agent-v/tools/node";
+import { FakeToolAgentEngine } from "@vraxis/agent-v/testing";
+
+export async function createReviewRuntime(projectRoot: string) {
+  const tools = await createWorkspaceTools({
+    rootPath: projectRoot,
+    allowedCommands: [process.execPath],
+  });
+  return createAgentRuntime({
+    execution: { type: "engine", engine: new FakeToolAgentEngine() },
+    agent: {
+      id: "project-reviewer",
+      name: "Project reviewer",
+      instructions: "Review the project against the product's supplied requirements.",
+      recipe: "review",
+      requiredCapabilities: ["tools"],
+    },
+    tools,
+    approvalPolicy: createStandardApprovalPolicy({
+      categories: { write: "denied", command: "denied", network: "denied", browser: "denied", credentials: "denied", destructive: "denied" },
+    }),
+  });
+}

package/examples/smoke.ts

@@ -8,6 +8,8 @@ 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";
+import { createHostedProviderAgent } from "./providers.ts";
+import { createReviewRuntime } from "./runtime-kit.ts";
 
 const usage = {
   inputTokens: { total: 1, noCache: 1, cacheRead: undefined, cacheWrite: undefined },
@@ -34,3 +36,9 @@ assert.equal(createStatefulRuntime(basic.runtime.engines.require("primary-agent"
 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);
+const hosted = createHostedProviderAgent({ resolve: async () => crypto.randomUUID() });
+assert.equal(hosted.profile.options?.provider, "openai");
+assert.equal((await hosted.providers.inspect(hosted.profile)).availability, "ready");
+const review = await createReviewRuntime(process.cwd());
+assert.equal(review.agent.id, "project-reviewer");
+assert.equal(review.approvalPolicy.constructor.name, "StandardApprovalPolicy");

package/llms.txt

@@ -1,6 +1,6 @@
 # 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.
+> Provider-neutral TypeScript execution contracts for scoped agents, validated standard tools, categorized approvals, built-in hosted providers, local coding runtimes, Ollama, secure credential references, sessions, events, portable skills, and starter recipes.
 
 ## Canonical guidance
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vraxis/agent-v",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "A provider-neutral engine for building inspectable, extensible agentic products.",
   "repository": {
     "type": "git",
@@ -46,6 +46,26 @@
       "types": "./dist/adapters/ai-sdk/index.d.ts",
       "import": "./dist/adapters/ai-sdk/index.js"
     },
+    "./providers": {
+      "types": "./dist/adapters/providers/index.d.ts",
+      "import": "./dist/adapters/providers/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./skills": {
+      "types": "./dist/skills/index.d.ts",
+      "import": "./dist/skills/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js"
+    },
+    "./tools/node": {
+      "types": "./dist/tools/node/index.d.ts",
+      "import": "./dist/tools/node/index.js"
+    },
     "./local-cli": {
       "types": "./dist/adapters/local-cli/index.d.ts",
       "import": "./dist/adapters/local-cli/index.js"
@@ -72,27 +92,23 @@
     "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": {
+    "@ai-sdk/anthropic": "^4.0.46",
+    "@ai-sdk/deepseek": "^3.0.37",
+    "@ai-sdk/google": "^4.0.58",
+    "@ai-sdk/openai": "^4.0.52",
+    "@ai-sdk/openai-compatible": "^3.0.41",
+    "ai": "^7.0.85",
+    "ai-sdk-ollama": "^4.2.0",
     "jsonc-parser": "^3.3.1",
     "yaml": "^2.9.0"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.3.0"
   }
 }

package/skills/agent-v/SKILL.md

@@ -2,7 +2,7 @@
 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.6.0"
+  version: "0.7.1"
 ---
 
 # Use agent-v accurately
@@ -13,9 +13,14 @@ Read the installed package's `README.md` and type declarations before coding. Do
 
 - 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/providers` for built-in hosted-provider profiles and model resolution. Keep only credential references in profiles.
+- Use `@vraxis/agent-v/runtime` for the high-level, deny-by-default model/tool-loop factory.
+- Use `@vraxis/agent-v/tools` for pure utilities, allowlisted HTTP, browser-controller contracts, and standard approval policies.
+- Use `@vraxis/agent-v/tools/node` for canonical-root filesystem, Git-read, and allowlisted argument-array command tools.
+- Use `@vraxis/agent-v/skills` for opt-in operational skills and starter recipes. Supply product-owned instructions.
 - 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, filesystem Agent Skills, and cross-runtime skill inventory.
+- Use `@vraxis/agent-v/node` for local sessions, run ledgers, diagnostics, filesystem Agent Skills, cross-runtime skill inventory, environment credential resolution, and system-keyring storage.
 - 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.
@@ -26,6 +31,7 @@ Do not substitute a coding CLI adapter for an ordinary model provider or treat O
 - 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.
 - Use an agent `toolPolicy` when evidence reads must occur in an exact order. Require `tool-sequencing` and `tool-audit`, and inspect `result.toolAudit.sequenceSatisfied`.
+- Treat every standard host tool as opt-in. Supply explicit roots, command/host/origin allowlists, scope permissions, and approval decisions.
 - 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.

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

@@ -16,6 +16,11 @@ Choose from required behavior, not provider preference:
 | --- | --- | --- |
 | One schema-bound model operation | `@vraxis/agent-v/ai-sdk` | `StructuredModelEngine` |
 | Bounded model/tool loop | `@vraxis/agent-v/ai-sdk` | `ToolAgentEngine` |
+| Built-in hosted model provider | `@vraxis/agent-v/providers` | AI SDK engines through `ProviderRuntime` |
+| High-level model/tool runtime | `@vraxis/agent-v/runtime` | `createAgentRuntime()` with provider or custom engine selection |
+| Portable standard tools | `@vraxis/agent-v/tools` | Pure tools, HTTP/browser contracts, approval policy |
+| Bounded Node host tools | `@vraxis/agent-v/tools/node` | Filesystem, Git, and allowlisted commands |
+| Operational starter recipes | `@vraxis/agent-v/skills` | Coding, research, review, and document composition |
 | 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 |
@@ -30,6 +35,8 @@ Validate the tool's returned value with `output`. Tool implementation bugs must
 
 Keep product-specific tools with their product until their contract and safety semantics are demonstrably reusable.
 
+Standard tools grant no ambient authority. Node workspace tools require a canonical root; command tools require an allowlist; HTTP requires allowed hosts; browser tools require allowed origins and a host controller. Guarded tools carry an approval category, and the standard policy denies categories the host has not decided explicitly.
+
 ## 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.
@@ -38,6 +45,8 @@ When skills are selected, their combined tool allowlist constrains the blueprint
 
 Declare only capabilities the workflow actually needs. Selection should fail if the engine cannot enforce one.
 
+Starter recipes provide operational tool/skill composition, not product meaning. The product must supply the agent id, name, instructions, scope, persistence, and approval UX.
+
 For governed evidence-first loops, declare `toolPolicy.requiredSequence` on the blueprint and use `afterRequired: "disable"` when final synthesis must not invoke more tools. Include `tool-sequencing` and `tool-audit` in `requiredCapabilities`. Vraxis validates tool availability and step budget before inference and returns redacted execution evidence in `result.toolAudit`.
 
 ## Persistence and provenance
@@ -48,6 +57,8 @@ Every `RunProvenance` has an `adapterStrategy`. Local CLI and Ollama runs also i
 
 Configuration contains credential references. Resolve credential values inside the host's model resolver; never write values to config, events, sessions, examples, or fixtures.
 
+For built-in hosted providers, use `defineProviderProfile()` and `ProviderRuntime` instead of importing provider SDKs into a product. Use `SystemCredentialStore` or another host-owned `CredentialResolver`; persist only the `keychain://` or `env://` reference. Provider inspection is configuration-only and makes no inference request.
+
 ## Common mistakes
 
 - Importing provider SDK types into product domain code instead of registering an adapter.