diff --git a/.changeset/resource-tools-read-gate.md b/.changeset/resource-tools-read-gate.md new file mode 100644 index 0000000000..d24e078a7d --- /dev/null +++ b/.changeset/resource-tools-read-gate.md @@ -0,0 +1,5 @@ +--- +"@flow-state-dev/core": minor +--- + +`resourceTools()`'s `readResource` now reads only from a collection that opted in with `llmReadable`, and leaves out the fields the collection names in `secret`. A path into a collection that didn't opt in answers as a path no collection matches. Mark a collection `llmReadable: true` if a model should read its state through this tool (FIX-2436). diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5fbb6dd942..e483cad51d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -440,7 +440,10 @@ jobs: e2e: name: Kitchen-sink E2E (Playwright) - runs-on: ubuntu-latest + # Pinned: the installed Playwright can't install chromium-headless-shell + # on ubuntu-26.04, which ubuntu-latest now resolves to. Unpin once + # Playwright supports 26.04 (FIX-2438). + runs-on: ubuntu-24.04 timeout-minutes: 10 # needs is queue order, not a build dependency. Still runs if Typecheck & Test fails. needs: [ci] diff --git a/packages/core/README.md b/packages/core/README.md index 7ddadc267b..8532b48dc3 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -827,7 +827,7 @@ The types are `RequestHost`, `ParentTaskOutcome`, `SettleParentTaskInput`, `Sett **LLM navigation tools.** `resourceSearchTools()` returns the Glob/Grep/Search trio over resources — `globResources` (path glob), `grepResourceContent` (regex/substring over content), and `searchResources` (lexical, term-frequency ranked). All three span static resources and collection instances and return each match's scope-qualified uri — the handle `readResourceContentTool` accepts. All three gate on `llmReadable` (including collection instances whose collection opts in); a collection that did not opt in is skipped before it is listed. Lexical only, not semantic. See [Searching resources](https://flow-state.dev/docs/resources/searching). -**Resource CRUD tools.** `resourceTools()` returns `createResource` / `readResource` / `updateResource` / `deleteResource`, each acting on a path the caller already names. A path reaches the collection whose pattern matches it, by the same rule the collection itself uses: `*` is one segment, `**` is any depth, and `[param]` is one segment bound to that parameter, so `react/observations` reaches `[topic]/observations`. The same path resolves the same instance through `resolveResourceByPath`, and through `resolveResourceByUri` with its scope in front. It no longer returns `listResources`: that tool enumerated every collection's stored state without applying the `llmReadable` gate. To let an agent find out what it can work with, register `resourcesManifestSource()` and give it the discovery tool below. +**Resource CRUD tools.** `resourceTools()` returns `createResource` / `readResource` / `updateResource` / `deleteResource`, each acting on a path the caller already names. `readResource` reads only a collection that opted in with `llmReadable`, and never returns a field the collection names in `secret`; any other path answers as one no collection matches. A path reaches the collection whose pattern matches it, by the same rule the collection itself uses: `*` is one segment, `**` is any depth, and `[param]` is one segment bound to that parameter, so `react/observations` reaches `[topic]/observations`. The same path resolves the same instance through `resolveResourceByPath`, and through `resolveResourceByUri` with its scope in front. It no longer returns `listResources`: that tool enumerated every collection's stored state without applying the `llmReadable` gate. To let an agent find out what it can work with, register `resourcesManifestSource()` and give it the discovery tool below. **Agent discovery.** `discoveryTools(createManifestRegistry([...sources]))` returns `discover({ domain?, detail? })` — one on-demand tool that answers what is in scope for this agent right now. A source projects one domain's existing reader into manifest entries (`{ id, kind, purpose, contract? }`); nothing is stored and nothing is copied. The registry is the fence: the tool can only answer for domains it was built with, so a model-supplied `domain` has no wider list to reach past. `resourcesManifestSource()` ships here; workers (the `workers` domain) and skills are registered by their own packages. diff --git a/packages/core/src/tools/resource-tools.ts b/packages/core/src/tools/resource-tools.ts index 9a9640c90e..fc136de297 100644 --- a/packages/core/src/tools/resource-tools.ts +++ b/packages/core/src/tools/resource-tools.ts @@ -4,6 +4,8 @@ import type { AnyResourceRef, ResourceRef } from "../types/resource"; import type { ResourceCollectionRef } from "../types/resource-collection"; import type { ResourceVisibility, ResourceVisibilityRule } from "../types/resource-visibility"; import { handler } from "../blocks/handler"; +import { omitSecretFields } from "../helpers/client-projection"; +import type { JsonObject } from "../schema/common"; import { extractBareTopic, isParameterizedPattern, @@ -116,7 +118,8 @@ function collectStaticResources(ctx: BlockContext): ResourceRef[] { * * Provides 4 tools, each acting on a path the caller already names: * - `createResource({ path, state? })` — Create a new resource instance - * - `readResource({ path })` — Read a resource instance + * - `readResource({ path })` — Read a resource instance, in a collection that + * opted in with `llmReadable`, without the fields its `secret` names * - `updateResource({ path, state? })` — Update a resource instance * - `deleteResource({ path })` — Delete a resource instance * @@ -159,7 +162,7 @@ export function resourceTools() { execute: async (input, ctx) => { const { nsRef, key } = resolvePathToCollection(input.path, ctx); const handle = await nsRef.get(key); - return { path: input.path, state: handle.state as Record }; + return { path: input.path, state: omitSecretFields(nsRef.config, handle.state as JsonObject) }; }, }); @@ -240,11 +243,13 @@ export async function resolveResourceByPath( } /** - * Content read gate. A collection instance carries its owning collection's - * config (the server stamps `config: nsConfig` onto every instance ref), so the - * collection-level `llmReadable` flag reaches each instance through `ref.config`. + * The one read gate, for a resource, a collection instance, or a collection. + * A collection instance carries its owning collection's config (the server + * stamps `config: nsConfig` onto every instance ref), so the collection-level + * `llmReadable` flag reaches each instance through `ref.config`. Listing, + * search and `readResource` all ask this, so the gate can't drift between them. */ -export function isLlmReadable(ref: ResourceRef): boolean { +export function isLlmReadable(ref: { config?: { llmReadable?: boolean } }): boolean { return ref.config?.llmReadable === true; } @@ -282,7 +287,7 @@ export function isLlmWritableNow(ref: ResourceRef, ctx: BlockContext): bool export async function collectReadableResources(ctx: BlockContext): Promise[]> { const out: ResourceRef[] = collectStaticResources(ctx).filter(isLlmReadable); for (const ns of collectCollections(ctx)) { - if (ns.ref.config?.llmReadable !== true) continue; + if (!isLlmReadable(ns.ref)) continue; for (const instance of await ns.ref.list()) out.push(instance); } return out; @@ -300,7 +305,7 @@ export async function collectReadableResources(ctx: BlockContext): Promise ns.ref.config?.llmReadable === true); + return collectProjectedCollections(ctx).filter((ns) => isLlmReadable(ns.ref)); } /** @@ -353,9 +358,13 @@ function resolvePathToCollection( ctx: BlockContext, intent: "read" | "write" = "read" ): { nsRef: ResourceCollectionRef; key: string | Record } { - // A collection the rule leaves read-only isn't a target for a write: the - // write answers as for a path no collection matches. - const collections = collectCollections(ctx).filter((ns) => intent === "read" || ns.access === "visible"); + // A read reaches only a collection that opted in with `llmReadable`, the same + // gate the content and search tools apply; a collection the rule leaves + // read-only isn't a target for a write. Either way the call answers as for a + // path no collection matches. + const collections = collectCollections(ctx).filter((ns) => + intent === "read" ? isLlmReadable(ns.ref) : ns.access === "visible" + ); for (const ns of collections) { const key = matchCollectionKey(ns, path); diff --git a/packages/core/src/types/resource-collection.ts b/packages/core/src/types/resource-collection.ts index eee92417c8..5c5fd7e5bd 100644 --- a/packages/core/src/types/resource-collection.ts +++ b/packages/core/src/types/resource-collection.ts @@ -132,8 +132,9 @@ export type ResourceCollectionConfig = { /** * Expose this collection's instance content to the LLM via the generic content - * tools (`readResourceContentTool`) and content search (`grepResourceContent` / - * `searchResources`). Collection-wide — applies to every instance, the same way + * tools (`readResourceContentTool`), content search (`grepResourceContent` / + * `searchResources`), and instance state via `resourceTools()`'s + * `readResource`, which also leaves out `secret` fields. Collection-wide — applies to every instance, the same way * `client` is declared once at the collection level. Default `false`: a * collection that doesn't opt in stays invisible to those tools. */ diff --git a/packages/engine/test/resource-tools-path-matching.test.ts b/packages/engine/test/resource-tools-path-matching.test.ts index 68c547bc77..cf2e7bbd2e 100644 --- a/packages/engine/test/resource-tools-path-matching.test.ts +++ b/packages/engine/test/resource-tools-path-matching.test.ts @@ -12,6 +12,10 @@ * row sees another row's writes. The existing unit tests stub the collection * refs; this file does not, so the real `get`/`create`/`getOptional` * validation is what answers. + * + * `readResource` answers only from a collection that opted in with + * `llmReadable`, and without the fields its `secret` names: a collection that + * didn't opt in answers as for a path no collection matches. */ import { DEFAULT_ORG_ID, @@ -31,25 +35,31 @@ import { z } from "zod"; import { createExecutionContext, createInMemoryStores } from "../src"; const s = z.object({ v: z.string().default("") }); +const keyed = z.object({ v: z.string().default(""), key: z.string().default("") }); const OWNER = ownerSegment("user_1"); const OTHER = ownerSegment("user_2"); async function makeCtx() { const resources = { profile: defineResource({ scope: "session", stateSchema: s }), - files: defineResourceCollection({ scope: "session", pattern: "files/*", stateSchema: s }), - docs: defineResourceCollection({ scope: "session", pattern: "docs/**", stateSchema: s }), + files: defineResourceCollection({ scope: "session", pattern: "files/*", stateSchema: s, llmReadable: true }), + docs: defineResourceCollection({ scope: "session", pattern: "docs/**", stateSchema: s, llmReadable: true }), // Registered shallow-first on purpose: a shallow collection must not claim // a nested path it can't hold and so hide the deep one behind it. - nestShallow: defineResourceCollection({ scope: "session", pattern: "nest/*", stateSchema: s }), - nestDeep: defineResourceCollection({ scope: "session", pattern: "nest/**", stateSchema: s }), - obs: defineResourceCollection({ scope: "session", pattern: "[topic]/observations", stateSchema: s }), + nestShallow: defineResourceCollection({ scope: "session", pattern: "nest/*", stateSchema: s, llmReadable: true }), + nestDeep: defineResourceCollection({ scope: "session", pattern: "nest/**", stateSchema: s, llmReadable: true }), + obs: defineResourceCollection({ scope: "session", pattern: "[topic]/observations", stateSchema: s, llmReadable: true }), notes: defineResourceCollection({ scope: "org", pattern: "notes/[owner]/[id]", ownerPrivate: { param: "owner" }, stateSchema: s, + llmReadable: true, }), + // Not opted in: blocks reach it, the model doesn't. + vault: defineResourceCollection({ scope: "session", pattern: "vault/*", stateSchema: s }), + // Opted in, with one field that never leaves the server. + keys: defineResourceCollection({ scope: "session", pattern: "keys/*", stateSchema: keyed, llmReadable: true, secret: ["key"] }), positions: defineProjectedResourceCollection({ pattern: "positions/*", scope: "session", @@ -78,6 +88,8 @@ async function makeCtx() { await ctx.resources.nestDeep.create("x/y", { v: "n" }); await ctx.resources.obs.create({ topic: "react" }, { v: "o" }); await ctx.resources.notes.create({ owner: OWNER, id: "mine" }, { v: "m" }); + await ctx.resources.vault.create("linear", { v: "sk-vault" }); + await ctx.resources.keys.create("linear", { v: "set", key: "sk-keys" }); return ctx; } @@ -135,6 +147,10 @@ const ROWS: readonly Row[] = [ [`read notes/${OWNER}/mine`, exec("readResource", { path: `notes/${OWNER}/mine` }), `ok {"path":"notes/${OWNER}/mine","state":{"v":"m"}}`], [`create notes/${OTHER}/theirs`, exec("createResource", { path: `notes/${OTHER}/theirs` }), REFUSED], [`read notes/${OTHER}/mine`, exec("readResource", { path: `notes/${OTHER}/mine` }), REFUSED], + // A collection that didn't opt in with `llmReadable` answers as one nothing registers. + ["read vault/linear", exec("readResource", { path: "vault/linear" }), NO_COLLECTION("vault/linear")], + // An opted-in collection is read without its `secret` fields. + ["read keys/linear", exec("readResource", { path: "keys/linear" }), `ok {"path":"keys/linear","state":{"v":"set"}}`], // ── resolveResourceByPath ───────────────────────────────────────────────── ["byPath profile", byPath("profile"), "ref session/profile"], diff --git a/packages/workforce/test/resource-tools-key-read.test.ts b/packages/workforce/test/resource-tools-key-read.test.ts new file mode 100644 index 0000000000..2ae13c9ad4 --- /dev/null +++ b/packages/workforce/test/resource-tools-key-read.test.ts @@ -0,0 +1,64 @@ +/** + * A worker holding a user's MCP keys and core's generic `resourceTools()` on + * the same model can't read a key through `readResource`. + * + * A worker that reaches its project's MCP servers holds the keys collection + * (`mcp-credentials/*`, at user scope) on its model block, so the key is there + * to read. The collection isn't `llmReadable` and declares `value` secret, so + * the model must not be handed it by any generic tool. The worker here picks + * `readResource` from its catalog and holds `mcpCredentialsCapability`, the + * keys collection a project-MCP worker holds; its model asks for the path a + * key is stored at, and the tool's answer is what the test reads. + */ +import { describe, expect, it } from "vitest"; +import { resourceTools } from "@flow-state-dev/core"; +import type { FlowInstance } from "@flow-state-dev/core/types"; +import { executeBlock } from "@flow-state-dev/engine"; +import { createTestContext, mockGenerator } from "@flow-state-dev/testing"; +import { AGENT_FLOW, defineAgentWorkerFlow } from "../src/agent-worker-flow"; +import { mintWorkers } from "../src/hire"; +import { MCP_CREDENTIALS_RESOURCE, mcpCredentialsCapability } from "../src/projects/mcp-credentials"; + +const KEY = "lin_api_users_own_key"; + +async function requestTheKey() { + const { readResource } = resourceTools(); + const flow = defineAgentWorkerFlow({ uses: [mcpCredentialsCapability], catalog: { readResource } }); + const [worker] = mintWorkers([{ id: "desk.lead", declared: { tools: ["readResource"] }, body: "" }], { + workerFlows: { [AGENT_FLOW]: flow } + }) as FlowInstance[]; + const block = worker!.actions.respond!.block; + const model = mockGenerator({ + name: "agent-answer", + script: [ + { toolCalls: [{ toolCallId: "call-1", toolName: "readResource", args: { path: "mcp-credentials/linear" } }] }, + { text: "done" } + ] as never + }); + const runtime = await createTestContext({ + flow: { ...worker!, cardinality: "singleton" }, + orgId: "test-org", + org: { state: {} }, + sessionId: "test-session", + sequencerName: block.name, + declaredResources: block.declaredResources, + generators: { "agent-answer": model } + }); + // The user's key, stored the way a host's settings route stores it. + const keys = (runtime.ctx.resources as unknown as Record }>)[ + MCP_CREDENTIALS_RESOURCE + ]!; + await keys.create("linear", { value: KEY, setAt: "2026-10-31T00:00:00.000Z" }); + + const result = await executeBlock({ block, input: { message: "what is my Linear key?" }, ctx: runtime.ctx }); + return { result, items: JSON.stringify(runtime.getItems()) }; +} + +describe("resourceTools beside a worker's MCP keys", () => { + it("refuses the read, and the key reaches nothing the model sees", async () => { + const { items } = await requestTheKey(); + // The tool ran and answered as for a path no collection matches. + expect(items).toContain("No resource collection found matching path: mcp-credentials/linear"); + expect(items).not.toContain(KEY); + }); +});