feat(integrations): run catalog tools with local credentials

docs/api-reference/veryfront/integrations.md

@@ -8,12 +8,12 @@ order: 14
 
 ```ts
 import {
+  createLocalIntegrationToolSource,
   createSalesforceServiceAccountToolSource,
   executeRemoteIntegrationTool,
   getConnector,
   getConnectorNames,
   getIcon,
-  getRemoteIntegrationToolDefinitions,
 } from "veryfront/integrations";
 ```
 
@@ -56,6 +56,7 @@ const runtimeTools = await getRemoteIntegrationToolDefinitions();
 
 | Name                                       | Description                                                                                                                                                                                                                                                   | Source                                                                                                              |
 | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `createLocalIntegrationToolSource`         | Create an explicitly granted, catalog-backed local integration tool source.                                                                                                                                                                                   | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/local-tool-source.ts#L591)          |
 | `createSalesforceServiceAccountToolSource` | Create a local Salesforce service-account tool source.                                                                                                                                                                                                        | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/salesforce-service-account.ts#L675) |
 | `executeRemoteIntegrationTool`             | Execute a remote integration tool via the API. Called by the agent runtime when a tool isn't found in the local registry. The request, response, and caller-supplied cancellation signal remain bounded for the complete network and response-body lifecycle. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/remote-tools.ts#L829)               |
 | `getConnector`                             | Return connector.                                                                                                                                                                                                                                             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/index.ts#L52)                       |
@@ -78,6 +79,8 @@ const runtimeTools = await getRemoteIntegrationToolDefinitions();
 | `IntegrationPrompt`                         | Public API contract for integration prompt.                                           | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/schema.ts#L497)                    |
 | `IntegrationTool`                           | Public API contract for integration tool.                                             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/types.ts#L68)                      |
 | `IntegrationToolMeta`                       | Public API contract for integration tool meta.                                        | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/schema.ts#L491)                    |
+| `LocalIntegrationCredentialProvider`        | Resolve one local integration credential by its canonical environment-variable name.  | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/local-tool-source.ts#L58)          |
+| `LocalIntegrationToolSourceOptions`         | Options for a catalog-backed local integration tool source.                           | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/local-tool-source.ts#L63)          |
 | `OAuthConfig`                               | Configuration used by oauth.                                                          | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/schema.ts#L489)                    |
 | `OAuthField`                                | Public API contract for oauth field.                                                  | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/schema.ts#L487)                    |
 | `RemoteIntegrationToolDiscoveryResult`      | Result of listing the integration tools available to the current run.                 | [source](https://github.com/veryfront/veryfront-code/blob/main/src/integrations/remote-tools.ts#L86)               |

docs/architecture/19-integration-runtime.md

@@ -1,13 +1,14 @@
 # Integration runtime
 
 This page describes the connector catalog, integration metadata schemas, and
-remote integration tool loading and execution. It does not cover OAuth route
-handlers or local tool definitions.
+the remote and local integration tool execution paths. It does not cover OAuth
+route handlers or project-authored tools.
 
 ## Responsibility
 
-Integration code exposes connector metadata, icons, and per-request remote tools
-fetched from the configured API layer.
+Integration code exposes connector metadata, icons, per-request remote tools
+fetched from the configured API layer, and exact-grant local tools backed by
+project-owned credentials.
 
 Primary source areas:
 
@@ -16,6 +17,8 @@ Primary source areas:
 - [`src/integrations/schema.ts`](../../src/integrations/schema.ts)
 - [`src/integrations/_data.ts`](../../src/integrations/_data.ts)
 - [`src/integrations/remote-tools.ts`](../../src/integrations/remote-tools.ts)
+- [`src/integrations/local-tool-source.ts`](../../src/integrations/local-tool-source.ts)
+- [`src/integrations/local-endpoint-executor.ts`](../../src/integrations/local-endpoint-executor.ts)
 - [`src/integrations/types.ts`](../../src/integrations/types.ts)
 
 ## Runtime flow
@@ -36,6 +39,12 @@ flowchart TD
   readiness --> execute
   execute --> api[Integrations tools API]
   api --> result[Structured tool result or sanitized error]
+
+  localGrant[Exact local tool grant] --> localTool[Build local tool definitions]
+  localTool --> localCall[Model requests local integration tool]
+  localCall --> credential[Resolve named project credential]
+  credential --> provider[Call supported provider REST endpoint]
+  provider --> localResult[Structured tool result or sanitized error]
 ```
 
 1. Connector metadata defines supported providers, auth requirements, tools,
@@ -51,20 +60,28 @@ flowchart TD
 7. Remote tool helpers resolve request-scoped or environment API credentials.
 8. Tool definitions are fetched per request so source-declared integration
    requests remain project-scoped.
-9. Tool execution is delegated to the configured API layer and normalized for
-   the agent runtime.
+9. Remote tool execution is delegated to the configured API layer and normalized
+   for the agent runtime.
+10. A local source can instead grant exact catalog tool IDs, resolve catalog-
+    named credentials immediately before each call, and execute supported HTTPS
+    REST endpoints without a Veryfront account or project token.
 
 ## Boundaries
 
-- Integration runtime owns connector metadata and remote tool bridge behavior.
+- Integration runtime owns connector metadata, the remote tool bridge, and the
+  bounded local endpoint executor.
 - Agent source owns the agent's integration tool declaration.
 - Exact-source `veryfront.config.ts` owns an optional monotonic allowlist. Its
   absence is unrestricted; it never enables an integration or grants credentials.
 - The control plane owns optional project policy and connection inventory.
 - OAuth runtime owns provider redirects, callbacks, and token storage.
-- Local project tools belong in [agent runtime](./05-agent-runtime.md) and the
+- Project-authored tools belong in [agent runtime](./05-agent-runtime.md) and the
   public [Tools](../guides/tools.md) guide.
-- The backing API owns actual third-party API calls and provider token access.
+- The backing API owns provider token access and third-party API calls for remote
+  integration tools.
+- A local integration source owns only its exact tool grant. The runtime resolves
+  catalog-named credentials from the project boundary and makes supported direct
+  provider calls without exposing credentials to tool arguments or the model.
 
 Effective integration capability is the intersection of agent selection,
 connector catalog, source configuration, and control-plane policy. No policy
@@ -82,6 +99,8 @@ child; handler-local tool-list rewriting is not an authorization boundary.
   metadata.
 - Add remote-tool tests when changing request-scoped token resolution, tool
   listing, call payloads, or result normalization.
+- Add local-source and endpoint-executor tests when changing exact-grant
+  admission, credential resolution, request construction, or response handling.
 - Keep per-project tool visibility scoped to the active request or environment
   token.
 - Keep config caches qualified by the exact branch, release, or environment;

docs/architecture/20-support-matrix.md

@@ -32,22 +32,23 @@ These are the runtime capability profiles modeled by the framework.
 This matrix separates open-core framework support from capabilities that depend
 on a backing API or cloud bootstrap.
 
-| Capability                                                            | Current support shape                             | Notes                                                                                                                         |
-| --------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Routing, rendering, middleware, API routes                            | Open-core                                         | Core framework capability.                                                                                                    |
-| App MCP server                                                        | Open-core on runtimes that can host it            | Not available on constrained runtimes like Cloudflare Workers.                                                                |
-| Internal AG-UI transport                                              | Open-core runtime surface                         | Separate from the app MCP contract.                                                                                           |
-| Direct provider integrations (`openai`, `anthropic`, `google`, local) | Open-core with provider credentials/runtime setup | Depends on the selected provider configuration.                                                                               |
-| Extension contracts (auth, bundler, CSS, parser, observability, etc.) | Open-core                                         | First-party `@veryfront/ext-*` packages provide implementations.                                                              |
-| Workflow engine (in-memory and Redis backends)                        | Open-core                                         | In-memory, Redis, and process run execution work without Kubernetes.                                                          |
-| Discovery (tools, agents, workflows, prompts, resources, skills)      | Open-core                                         | Convention-based file-system discovery at server startup.                                                                     |
-| Veryfront Cloud model routing                                         | Requires Veryfront Cloud bootstrap                | Depends on project/auth context and cloud gateway configuration.                                                              |
-| Veryfront Cloud blob storage                                          | Requires Veryfront Cloud bootstrap                | Uses project-scoped cloud upload APIs.                                                                                        |
-| Veryfront Cloud agent service                                         | Requires Veryfront Cloud bootstrap                | Hosted agent execution with project steering and runtime system messages.                                                     |
-| Runs client                                                           | Requires backing API/service layer                | Exposed as SDK/API surface for task, workflow, and agent execution.                                                           |
-| Sandbox                                                               | Requires backing API/service layer                | Depends on authenticated sandbox session APIs.                                                                                |
-| Remote integration tools                                              | Local source or backing API/service layer         | Salesforce supports an explicit local service account source. Managed and other connector paths use the configured API layer. |
-| Control-plane agent routing                                           | Requires Veryfront Cloud bootstrap                | EdDSA-signed request validation for hosted agent orchestration.                                                               |
+| Capability                                                            | Current support shape                             | Notes                                                                                                                              |
+| --------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Routing, rendering, middleware, API routes                            | Open-core                                         | Core framework capability.                                                                                                         |
+| App MCP server                                                        | Open-core on runtimes that can host it            | Not available on constrained runtimes like Cloudflare Workers.                                                                     |
+| Internal AG-UI transport                                              | Open-core runtime surface                         | Separate from the app MCP contract.                                                                                                |
+| Direct provider integrations (`openai`, `anthropic`, `google`, local) | Open-core with provider credentials/runtime setup | Depends on the selected provider configuration.                                                                                    |
+| Extension contracts (auth, bundler, CSS, parser, observability, etc.) | Open-core                                         | First-party `@veryfront/ext-*` packages provide implementations.                                                                   |
+| Workflow engine (in-memory and Redis backends)                        | Open-core                                         | In-memory, Redis, and process run execution work without Kubernetes.                                                               |
+| Discovery (tools, agents, workflows, prompts, resources, skills)      | Open-core                                         | Convention-based file-system discovery at server startup.                                                                          |
+| Veryfront Cloud model routing                                         | Requires Veryfront Cloud bootstrap                | Depends on project/auth context and cloud gateway configuration.                                                                   |
+| Veryfront Cloud blob storage                                          | Requires Veryfront Cloud bootstrap                | Uses project-scoped cloud upload APIs.                                                                                             |
+| Veryfront Cloud agent service                                         | Requires Veryfront Cloud bootstrap                | Hosted agent execution with project steering and runtime system messages.                                                          |
+| Runs client                                                           | Requires backing API/service layer                | Exposed as SDK/API surface for task, workflow, and agent execution.                                                                |
+| Sandbox                                                               | Requires backing API/service layer                | Depends on authenticated sandbox session APIs.                                                                                     |
+| Remote integration tools                                              | Requires backing API/service layer                | Tool definitions and execution are fetched per request from the configured API layer.                                              |
+| Local catalog integration tools                                       | Open-core with provider credentials/runtime setup | Exact-grant local sources execute supported HTTPS REST endpoints directly. Salesforce also has a dedicated service-account source. |
+| Control-plane agent routing                                           | Requires Veryfront Cloud bootstrap                | EdDSA-signed request validation for hosted agent orchestration.                                                                    |
 
 ## Extension contract matrix
 

docs/guides/errors.md

@@ -74,6 +74,20 @@ Configuration validation failed.
 - **HTTP status:** 400
 - **What to do:** Check configuration values against requirements
 
+### local-integration-config-invalid
+
+Invalid local integration configuration.
+
+- **HTTP status:** 400
+- **What to do:** Use exact catalog tool IDs and supported local credential and endpoint contracts
+
+### local-integration-credentials-missing
+
+Local integration credentials are missing.
+
+- **HTTP status:** 400
+- **What to do:** Set the named environment variables or configure a credential provider
+
 ### webhook-config-invalid
 
 Invalid webhook configuration.
@@ -230,6 +244,27 @@ Middleware execution error.
 - **HTTP status:** 500
 - **What to do:** Check middleware function for errors
 
+### local-integration-credential-unavailable
+
+Local integration credential is unavailable.
+
+- **HTTP status:** 503
+- **What to do:** Check the local credential provider and retry
+
+### local-integration-request-failed
+
+Local integration request failed.
+
+- **HTTP status:** 502
+- **What to do:** Check the provider status and local integration configuration, then retry
+
+### local-integration-response-invalid
+
+Local integration response is invalid.
+
+- **HTTP status:** 502
+- **What to do:** Check the provider response contract and retry
+
 ### trigger-target-not-found
 
 Trigger target not found.
@@ -540,6 +575,13 @@ SSR output limit exceeded.
 - **HTTP status:** 500
 - **What to do:** Reduce the rendered HTML size or split the response into smaller pages
 
+### local-integration-request-invalid
+
+Local integration request is invalid.
+
+- **HTTP status:** 400
+- **What to do:** Pass only the documented tool arguments with their declared JSON types
+
 ## Development tooling
 
 Raised by the local development workflow.