Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/resource-tools-read-gate.md
Original file line number Diff line number Diff line change
@@ -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).
2 changes: 1 addition & 1 deletion packages/core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
28 changes: 17 additions & 11 deletions packages/core/src/tools/resource-tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -116,7 +118,8 @@ function collectStaticResources(ctx: BlockContext): ResourceRef<any>[] {
*
* 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
*
Expand Down Expand Up @@ -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<string, unknown> };
return { path: input.path, state: omitSecretFields(nsRef.config, handle.state as JsonObject) };
},
});

Expand Down Expand Up @@ -240,11 +243,10 @@ 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`.
* Content read gate. `config.llmReadable === true`, on a static resource, a
* collection, or an instance (an instance carries its collection's config).
*/
export function isLlmReadable(ref: ResourceRef<any>): boolean {
export function isLlmReadable(ref: ResourceRef<any> | ResourceCollectionRef<any>): boolean {
return ref.config?.llmReadable === true;
}

Expand Down Expand Up @@ -282,7 +284,7 @@ export function isLlmWritableNow(ref: ResourceRef<any>, ctx: BlockContext): bool
export async function collectReadableResources(ctx: BlockContext): Promise<ResourceRef<any>[]> {
const out: ResourceRef<any>[] = 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;
Expand All @@ -300,7 +302,7 @@ export async function collectReadableResources(ctx: BlockContext): Promise<Resou
* collection that did not opt in is filtered out before anything reaches it.
*/
export function collectReadableProjectedCollections(ctx: BlockContext): CollectionEntry[] {
return collectProjectedCollections(ctx).filter((ns) => ns.ref.config?.llmReadable === true);
return collectProjectedCollections(ctx).filter((ns) => isLlmReadable(ns.ref));
}

/**
Expand Down Expand Up @@ -353,9 +355,13 @@ function resolvePathToCollection(
ctx: BlockContext,
intent: "read" | "write" = "read"
): { nsRef: ResourceCollectionRef<any>; key: string | Record<string, string> } {
// 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);
Expand Down
5 changes: 3 additions & 2 deletions packages/core/src/types/resource-collection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -132,8 +132,9 @@ export type ResourceCollectionConfig<TState extends JsonObject = JsonObject> = {

/**
* 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.
*/
Expand Down
26 changes: 21 additions & 5 deletions packages/engine/test/resource-tools-path-matching.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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",
Expand Down Expand Up @@ -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;
}

Expand Down Expand Up @@ -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"],
Expand Down
64 changes: 64 additions & 0 deletions packages/workforce/test/resource-tools-key-read.test.ts
Original file line number Diff line number Diff line change
@@ -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<string, { create(k: string, s: object): Promise<unknown> }>)[
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);
});
});
Loading