@bevel-software/platform-core-backend 0.33.0 → 0.35.0

package/src/modules/database/core-schema.ts

@@ -41,6 +41,16 @@ export const users = pgTable('users', {
    * until an admin (or the user, from their Account page) sets one.
    */
   passwordHash: text('password_hash'),
+  /**
+   * Which generation of this account's sessions is honoured. Every session
+   * token carries the value it was issued at (`sv`; a token from before the
+   * column existed carries none and counts as 0), and one whose value is not
+   * the row's is refused. Changing the password moves it on, so every session
+   * opened with the old password ends at its next request — the one that
+   * made the change is handed a fresh token. Connection keys are not
+   * sessions and do not look at it.
+   */
+  sessionVersion: integer('session_version').default(0).notNull(),
   /**
    * The one onboarding fact the server keeps: has this person concluded the
    * connect-your-agent setup (the welcome page's Done, or the reminder
@@ -277,6 +287,15 @@ export const externalApiKeys = pgTable('api_tokens', {
    * deleted in one step.
    */
   deletedAt: timestamp('deleted_at'),
+  /**
+   * The agent configuration the key connects as — a repo-relative knowledge-base
+   * path, chosen when the key is minted. Null is Everything: the key sees
+   * every tool, skill and plugin its owner may read, exactly as before the
+   * column existed. The path is the whole record: the file is re-read on
+   * every surface build, so editing it changes what the key sees without a
+   * new key (see `modules/agent-scope`).
+   */
+  agentPath: text('agent_path'),
 }, (t) => ({
   byUser: index('api_tokens_by_user').on(t.userId),
 }));
@@ -486,6 +505,12 @@ export const oauthAuthCodes = pgTable('oauth_auth_codes', {
   expiresAt: timestamp('expires_at').notNull(),
   consumedAt: timestamp('consumed_at'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
+  /**
+   * The "Connect as" choice made on the consent step, carried from Finish to
+   * the token exchange that makes (or finds) the agent connection — the code
+   * is the only thing that travels between the two. Null is Everything.
+   */
+  agentPath: text('agent_path'),
 }, (t) => ({
   // Sweep expired/spent rows without a full scan.
   byExpiry: index('oauth_auth_codes_by_expiry').on(t.expiresAt),
@@ -525,6 +550,14 @@ export const agentConnections = pgTable('agent_connections', {
   revokedAt: timestamp('revoked_at'),
   /** `owner` | `admin` — who ended it; null while live. Same vocabulary as `api_tokens.revoked_by`. */
   revokedBy: text('revoked_by'),
+  /**
+   * The agent configuration the person chose to connect as on the consent step — a
+   * repo-relative knowledge-base path — or null for Everything. Set by every
+   * consent that lands on the row, so re-authorising with another choice
+   * changes what the agent sees from its next request. Same meaning as
+   * `api_tokens.agent_path`.
+   */
+  agentPath: text('agent_path'),
 }, (t) => ({
   byUser: index('agent_connections_by_user').on(t.userId),
   liveUnq: uniqueIndex('agent_connections_live_unq')

package/src/modules/declared-variables/__tests__/declared-variables.route.test.ts

@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createDeclaredVariableRoutes } from '../declared-variables.routes.js';
 import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
 import type { ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
+import { ConnectionScope, type IAgentScopeResolver } from '../../agent-scope/index.js';
 
 /**
  * The one core route that releases secret VALUES. What is worth pinning here is
@@ -46,6 +47,9 @@ async function mount(opts: {
   source?: 'session' | 'external' | 'internal';
   manuals?: ToolManualSummary[];
   secrets?: Record<string, string>;
+  /** The `.agent` file the caller's connection was made as; absent is Everything. */
+  agentPath?: string;
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>;
 }): Promise<Harness> {
   const userId = opts.userId ?? 'user-1';
   const source = opts.source ?? 'external';
@@ -64,10 +68,18 @@ async function mount(opts: {
       toolManualService,
       secretsVault,
       (req, _res, next) => {
-        if (userId) req.toolAuth = { userId, source, scope: 'write' } as typeof req.toolAuth;
+        if (userId) {
+          req.toolAuth = {
+            userId,
+            source,
+            scope: 'write',
+            ...(opts.agentPath ? { agentPath: opts.agentPath } : {}),
+          } as typeof req.toolAuth;
+        }
         next();
       },
       async () => 'runner@x.eu',
+      opts.agentScope,
     ),
   );
   httpServer = await new Promise<HttpServer>((r) => {
@@ -133,6 +145,37 @@ describe('POST /agent/local-tools/:slug/variables', () => {
     expect(resolve).not.toHaveBeenCalled();
   });
 
+  it("releases only the variables of a connector the connection's .agent file loads", async () => {
+    const agent = { path: 'Agents/ops.agent', name: 'Ops' };
+    const loading = (connectors: string[]) => ({
+      resolve: async () => ConnectionScope.narrowed(agent, { skills: [], connectors, platformTools: null }, 'fp'),
+    });
+    // A folder entry over the tool's plugin loads it.
+    const inScope = await mount({
+      manuals: [GIT_TOOL],
+      secrets: { git_GITHUB_TOKEN: 'ghp_secret' },
+      agentPath: agent.path,
+      agentScope: loading(['Plugins/Engineering']),
+    });
+    expect((await fetch(`${inScope.base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(200);
+    await new Promise<void>((r) => httpServer!.close(() => r()));
+
+    // A readable tool the file does not load is as absent as an unreadable one.
+    const outOfScope = await mount({
+      manuals: [GIT_TOOL],
+      secrets: { git_GITHUB_TOKEN: 'ghp_secret' },
+      agentPath: agent.path,
+      agentScope: loading(['Plugins/billing.tool']),
+    });
+    expect((await fetch(`${outOfScope.base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(404);
+    expect(outOfScope.resolve).not.toHaveBeenCalled();
+    await new Promise<void>((r) => httpServer!.close(() => r()));
+
+    // A narrowed connection with no resolver wired loads nothing.
+    const unwired = await mount({ manuals: [GIT_TOOL], agentPath: agent.path });
+    expect((await fetch(`${unwired.base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(404);
+  });
+
   it('403s an unauthenticated caller', async () => {
     const { base } = await mount({ userId: '', manuals: [GIT_TOOL] });
     expect((await fetch(`${base}/agent/local-tools/git/variables`, { method: 'POST' })).status).toBe(403);

package/src/modules/declared-variables/declared-variables.routes.ts

@@ -5,6 +5,7 @@ const log = logger('declared-variables');
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IToolManualService } from '../tool-manuals/index.js';
 import type { ISecretsVaultService } from '../secrets-vault/index.js';
+import { resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 
 type ResolveUserEmail = (userId: string) => Promise<string | undefined>;
 
@@ -48,6 +49,12 @@ export function createDeclaredVariableRoutes(
   secretsVault: ISecretsVaultService,
   manualAuth: RequestHandler,
   resolveUserEmail: ResolveUserEmail,
+  /**
+   * Resolves the scope of a connection made as an agent configuration: such a
+   * connection is handed only the variables of a connector the file loads.
+   * Absent, a narrowed connection is handed none.
+   */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>,
 ): express.Router {
   const router = express.Router();
 
@@ -125,7 +132,11 @@ export function createDeclaredVariableRoutes(
       // `listAccessible` already applies the per-file read verdict, so an
       // unreadable manual is simply absent — same fail-closed read model the
       // catalog uses.
-      const manual = (await toolManualService.listAccessible(who.email)).find((m) => m.slug === slug);
+      const found = (await toolManualService.listAccessible(who.email)).find((m) => m.slug === slug);
+      // A connection made as an agent configuration is handed only the variables of
+      // a connector it loads; another is as absent as an unreadable one.
+      const scope = found ? await resolveConnectionScope(agentScope, who.email, req.toolAuth?.agentPath) : null;
+      const manual = found && scope?.allowsConnector(found.path) ? found : undefined;
       if (!manual) return void res.status(404).json({ error: 'Not found' });
       if (manual.remote !== false) {
         return void res.status(409).json({

package/src/modules/embed/__tests__/embed.tools.test.ts

@@ -281,6 +281,18 @@ describe('open_page: refusals', () => {
     expect(embedService.mintForUser).not.toHaveBeenCalled();
   });
 
+  it('refuses a tmp ref — no knowledge-base page — reading and minting nothing', async () => {
+    const read = vi.fn<ReadForTool>();
+    const { call, embedService } = await serve({ read });
+    const { status, body } = await call({ path: '__tmp__/chat-uploads/plan.xlsx' });
+    expect(status).toBe(400);
+    expect(body.kind).toBe('tmp-ref-read-only');
+    expect(body.error).toContain('open_page does not take one there');
+    expect(body.error).toContain('copy_file');
+    expect(read).not.toHaveBeenCalled();
+    expect(embedService.mintForUser).not.toHaveBeenCalled();
+  });
+
   it('refuses a path outside the knowledge base, and a missing one', async () => {
     const { call, embedService } = await serve();
     expect((await call({ path: '' })).status).toBe(400);

package/src/modules/embed/embed.tools.ts

@@ -6,6 +6,7 @@ import type { KbContext } from '../../shared/kb-context.js';
 import type { ReadForTool } from '../workspace/index.js';
 import type { IEmbedService } from './embed.interface.js';
 import { requireExternalSource } from '../tool-auth/index.js';
+import { assertTmpRefsTaken } from '../kb-fs/index.js';
 import { SESSION_ID_INPUT, type ToolDescriptionNotes, sessionIdInputOf } from '../workspace/index.js';
 
 /** The tool name, in one place: the app manifest keys its view by it. */
@@ -149,6 +150,10 @@ export function registerEmbedTools(
     toolHandler(async (args, ctx: ToolContext) => {
       const raw = typeof args.path === 'string' ? args.path.trim() : '';
       if (!raw) throw new ToolError('`path` is required.', 400);
+      // A tmp ref (`__tmp__/…`) is no knowledge-base page: refused by the one
+      // admission gate the normalised tools pass, before `toRepoRelative`
+      // would read it as the repository path `<kbDirName>/__tmp__/…`.
+      assertTmpRefsTaken(OPEN_PAGE_TOOL, { path: raw });
       const heading = typeof args.heading === 'string' && args.heading.trim() ? args.heading.trim() : undefined;
       const repoRelative = toRepoRelative(raw, kbDirName);
       if (repoRelative === null) throw new ToolError(OUTSIDE_REPO(kbDirName), 400);

package/src/modules/kb-fs/__tests__/locking-filesystem.test.ts

@@ -1482,6 +1482,31 @@ describe('LockingFilesystem — a destination that is taken is refused, never re
     expect(await fs.readFile(onDisk(TAKEN), 'utf-8')).toBe('the winner of the race');
   });
 
+  /**
+   * The same race for an EXCLUSIVE write (`overwrite: false`), which is how
+   * `copy_file` lands bytes read out of the workspace's tmp folder: the
+   * refusal is the clash sentence, and the lock releases untouched rather
+   * than discarding the winner's queued file.
+   */
+  it('an exclusive write onto a taken name is the same refusal, and releases UNTOUCHED', async () => {
+    const workflow = makeWorkflow();
+    const layer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+    );
+    await fs.writeFile(onDisk(TAKEN), 'the winner of the race');
+
+    await expect(layer.writeFile(TAKEN, 'the loser', { overwrite: false })).rejects.toMatchObject({
+      name: 'DestinationTakenError',
+      message: 'A file named taken.md already exists in KnowledgeBase.',
+    });
+
+    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', TAKEN, USER);
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(await fs.readFile(onDisk(TAKEN), 'utf-8')).toBe('the winner of the race');
+  });
+
   it.skipIf(process.platform === 'win32')('answers the clash sentence when a DANGLING link holds the name', async () => {
     // A link to nothing still owns the directory entry, so the exclusive
     // create fails — and an existence probe that follows links would say the

package/src/modules/kb-fs/__tests__/repo-path.test.ts

@@ -231,8 +231,8 @@ describe('a line break in a path — one name to the gates, two object names to
   });
 
   it('refuses it through normalizePathArgs, which is where the MCP tools meet the rule', () => {
-    expect(() => normalizePathArgs({ path: INJECTED }, KB)).toThrow(/control character/);
-    expect(() => normalizePathArgs({ files: [{ path: INJECTED }] }, KB)).toThrow(/control character/);
+    expect(() => normalizePathArgs({ path: INJECTED }, KB, { tool: 'read_file' })).toThrow(/control character/);
+    expect(() => normalizePathArgs({ files: [{ path: INJECTED }] }, KB, { tool: 'read_file' })).toThrow(/control character/);
   });
 });
 
@@ -360,6 +360,8 @@ describe('assertRepoRootNameFree', () => {
 });
 
 describe('normalizePathArgs', () => {
+  const T = { tool: 'read_file' };
+
   it('normalizes every path-shaped tool argument, batch entries included', () => {
     expect(
       normalizePathArgs(
@@ -372,6 +374,7 @@ describe('normalizePathArgs', () => {
           files: [{ path: 'e.md', content: '/x' }],
         },
         KB,
+        T,
       ),
     ).toEqual({
       branch: '/main',
@@ -385,22 +388,64 @@ describe('normalizePathArgs', () => {
 
   it('leaves a spill ref alone — it belongs to no workspace', () => {
     expect(
-      normalizePathArgs({ path: '__tool_chain_spill__/abc.json' }, KB, (v) => v.startsWith('__tool_chain_spill__/')),
+      normalizePathArgs({ path: '__tool_chain_spill__/abc.json' }, KB, { tool: 'read_file', skip: (v) => v.startsWith('__tool_chain_spill__/') }),
     ).toEqual({ path: '__tool_chain_spill__/abc.json' });
   });
 
+  it('still takes the earlier call form, a skip predicate or nothing, and refuses a tmp ref in every input there', () => {
+    const spill = (v: string) => v.startsWith('__tool_chain_spill__/');
+    expect(normalizePathArgs({ path: '__tool_chain_spill__/abc.json' }, KB, spill)).toEqual({ path: '__tool_chain_spill__/abc.json' });
+    expect(normalizePathArgs({ path: 'a.md' }, KB)).toEqual({ path: 'knowledge-base/a.md' });
+    for (const legacy of [undefined, spill]) {
+      expect(() => normalizePathArgs({ path: '__tmp__/x.md' }, KB, legacy)).toThrow(/this tool does not take one there/);
+    }
+  });
+
   it('leaves an absent or empty path to the handler\'s own required-argument message', () => {
-    expect(normalizePathArgs({ path: undefined }, KB)).toEqual({ path: undefined });
-    expect(normalizePathArgs({ path: '' }, KB)).toEqual({ path: '' });
-    expect(normalizePathArgs({ branch: 'main' }, KB)).toEqual({ branch: 'main' });
+    expect(normalizePathArgs({ path: undefined }, KB, T)).toEqual({ path: undefined });
+    expect(normalizePathArgs({ path: '' }, KB, T)).toEqual({ path: '' });
+    expect(normalizePathArgs({ branch: 'main' }, KB, T)).toEqual({ branch: 'main' });
   });
 
   it('collapses the spellings so two callers take one lock row', () => {
-    expect(normalizePathArgs({ path: './knowledge-base//a.md' }, KB)).toEqual({ path: 'knowledge-base/a.md' });
+    expect(normalizePathArgs({ path: './knowledge-base//a.md' }, KB, T)).toEqual({ path: 'knowledge-base/a.md' });
+  });
+
+  it('admits a tmp ref, as written, in exactly the inputs the tool names', () => {
+    expect(normalizePathArgs({ src: '__tmp__/a.pdf', dest: 'a.pdf' }, KB, { tool: 'copy_file', tmpRefInputs: ['src'] })).toEqual({
+      src: '__tmp__/a.pdf',
+      dest: 'knowledge-base/a.pdf',
+    });
+  });
+
+  it('refuses a tmp ref in every other input, lists included, naming the tool and copy_file', () => {
+    const calls: Array<Record<string, unknown>> = [
+      { path: '__tmp__/a.md' },
+      { src: '__tmp__/a.md' },
+      { dest: '__tmp__/a.md' },
+      { destination: '__tmp__' },
+      { files: [{ path: 'ok.md' }, { path: '__tmp__/a.md' }] },
+      { paths: ['ok.md', '__tmp__/a.md'] },
+      { resolutions: [{ path: 'ok.md', choose: 'ours' }, { path: '__tmp__/a.md', content: 'x' }] },
+    ];
+    for (const args of calls) {
+      expect(() => normalizePathArgs(args, KB, { tool: 'save_file' })).toThrow(
+        /is a tmp ref, and save_file does not take one there: the workspace's tmp folder is read-only through the ref\..*copy_file/,
+      );
+    }
+    // A tool that takes a ref in `src` still refuses one in `dest`.
+    expect(() => normalizePathArgs({ dest: '__tmp__/a.md' }, KB, { tool: 'copy_file', tmpRefInputs: ['src'] })).toThrow(
+      /copy_file does not take one there/,
+    );
+  });
+
+  it('reads a path that only contains the prefix as an ordinary repository path', () => {
+    expect(normalizePathArgs({ path: 'knowledge-base/__tmp__/a.md' }, KB, T)).toEqual({ path: 'knowledge-base/__tmp__/a.md' });
+    expect(normalizePathArgs({ path: '/knowledge-base/__tmp__/a.md' }, KB, T)).toEqual({ path: 'knowledge-base/__tmp__/a.md' });
   });
 
   it('refuses a traversing tool argument', () => {
-    expect(() => normalizePathArgs({ path: '../escape.md' }, KB)).toThrow(/outside the knowledge base repository/);
+    expect(() => normalizePathArgs({ path: '../escape.md' }, KB, T)).toThrow(/outside the knowledge base repository/);
   });
 });
 

package/src/modules/kb-fs/index.ts

@@ -8,6 +8,7 @@ export { WorkspaceMutex, WorkspaceIdMutex } from './mutex.js';
 export { readRefSha, readRevSha, type RefFileAnswer } from './ref-files.js';
 export { gitDirOf, readGitfile } from './git-dir.js';
 export { normalizeWorkspacePath } from './repo-path.js';
+export { TMP_REF_PREFIX, assertTmpRefsTaken, isTmpRef, tmpRefReadOnlyRefusal } from './tmp-ref.js';
 // Reached by other modules; exported here so they stop importing the files.
 export { BevelIgnoreStack } from './bevel-ignore.js';
 export { assertValidBranchName, assertValidRelativePath, isBranchAuthoredBy, isOwnSuggestionsBranch } from './branch-name.js';
@@ -18,3 +19,4 @@ export { LockingFilesystem, MoveLockedError, MoveRacedError } from './locking-fi
 export { ReadOnlyFilesystem } from './read-only-filesystem.js';
 export { normalizeRepositoryAddress, sameRepository } from './remote-url.js';
 export { assertInsideRepo, assertKbDirNameFree, assertRepoRootNameFree, assertRepoRootNameFreeArgs, hasControlCharacter, isInsideRepo, normalizePathArgs } from './repo-path.js';
+export type { NormalizePathArgsOptions } from './repo-path.js';

package/src/modules/kb-fs/locking-filesystem.ts

@@ -226,9 +226,15 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     const plan = await this.planCreate(inputPath, 'file');
     if (plan?.kind === 'seed-access-md') await this.seedAccessMd(plan);
     const toWrite = content;
+    // An EXCLUSIVE write (`overwrite: false`, the `wx` flag) that finds the
+    // name taken is refused as a copy is (`asTakenRefusal`): the refusal is a
+    // `DestinationTakenError`, so the lock is released untouched. Left as the
+    // raw failure it would be a failed op, and the discard that follows resets
+    // the PATH — throwing away the winner's file, whose commit is still queued.
+    const land = () => super.writeFile(inputPath, toWrite, options);
     return this.withLock(
       inputPath,
-      () => super.writeFile(inputPath, toWrite, options),
+      () => (options?.overwrite === false ? this.asTakenRefusal(inputPath, land) : land()),
       (check || validate) &&
         (async () => {
           // The caller's verdict first: it decides whether this write happens

package/src/modules/kb-fs/repo-path.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { WorkflowValidationError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';
+import { assertTmpRefsTaken, isTmpRef } from './tmp-ref.js';
 
 /**
  * Workspace-relative paths and the repository folder.
@@ -312,6 +313,16 @@ export function assertKbDirNameFree(
   );
 }
 
+/** How {@link normalizePathArgs} treats one tool's call. */
+export interface NormalizePathArgsOptions {
+  /** The tool the call is to, named in a tmp-ref refusal. */
+  tool: string;
+  /** The inputs of `tool` that take a tmp ref (`__tmp__/…`); every other refuses one. */
+  tmpRefInputs?: readonly string[];
+  /** A value that is no workspace path at all, passed to the handler as written. */
+  skip?: (value: string) => boolean;
+}
+
 /** The tool inputs that carry a workspace path. */
 const PATH_ARG_KEYS = ['path', 'src', 'dest', 'destination'] as const;
 
@@ -321,19 +332,34 @@ const PATH_ARG_KEYS = ['path', 'src', 'dest', 'destination'] as const;
  * copy. This is where the MCP surface meets the normaliser — one call, before
  * any handler runs, so no tool keeps a resolver of its own.
  *
- * `skip` is for the one input that is not a workspace path at all: `read_file`
- * also takes a `__tool_chain_spill__/…` ref, which belongs to no workspace and
- * must reach the handler as written. An absent or non-string value is left
- * alone too — the handler's own required-argument message is better than a
- * path refusal about `undefined`.
+ * It is also where a tmp ref (`__tmp__/…`) is admitted or refused, first:
+ * {@link assertTmpRefsTaken} refuses one in every input of `tool` that
+ * `tmpRefInputs` does not name, and a ref in an input that does name it
+ * reaches the handler as written — so no tool whose paths pass through here
+ * can read the ref as the repository path `<kbDirName>/__tmp__/…`.
+ *
+ * `skip` is for the other input that is not a workspace path at all:
+ * `read_file` also takes a `__tool_chain_spill__/…` ref, which belongs to no
+ * workspace and must reach the handler as written. An absent or non-string
+ * value is left alone too — the handler's own required-argument message is
+ * better than a path refusal about `undefined`.
+ *
+ * The earlier call form — a `skip` predicate (or nothing) as the third
+ * argument — is still taken, for a distribution's own tool written against
+ * it: such a call names no tool and takes a tmp ref in no input, so the ref is
+ * refused there as read-only, under the name "this tool".
  */
 export function normalizePathArgs(
   args: Record<string, unknown>,
   kbDirName: string,
-  skip?: (value: string) => boolean,
+  options?: NormalizePathArgsOptions | ((value: string) => boolean),
 ): Record<string, unknown> {
+  const { tool, tmpRefInputs, skip } =
+    typeof options === 'object' ? options : { tool: 'this tool', tmpRefInputs: undefined, skip: options };
+  assertTmpRefsTaken(tool, args, tmpRefInputs);
+  // Every tmp ref still here is in an input that takes one.
   const one = (value: unknown): unknown =>
-    typeof value !== 'string' || value.length === 0 || skip?.(value)
+    typeof value !== 'string' || value.length === 0 || isTmpRef(value) || skip?.(value)
       ? value
       : normalizeWorkspacePath(value, kbDirName);
   const out: Record<string, unknown> = { ...args };

package/src/modules/kb-fs/tmp-ref.ts

@@ -0,0 +1,81 @@
+import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { sanitizedPath } from '../../shared/printable.js';
+
+/**
+ * The tmp ref's admission: which tool inputs may carry one, and the refusal
+ * every other input answers. What the ref REACHES is `workspace/workspace-tmp.ts`'s;
+ * whether a tool may be HANDED one is decided here, once, by
+ * {@link assertTmpRefsTaken} — which {@link normalizePathArgs} runs before it
+ * places any path under the checkout, so no tool surface that takes a path
+ * can turn `__tmp__/x` into the repository path `<kbDirName>/__tmp__/x` and
+ * write, read or show it as if the ref had been honoured. A surface that
+ * resolves its paths without the normaliser (`open_page`) calls the gate
+ * itself.
+ */
+
+/** The ref's prefix. A ref is `__tmp__/<path inside the workspace's tmp folder>`. */
+export const TMP_REF_PREFIX = '__tmp__/';
+
+/**
+ * Whether a tool argument is a tmp ref rather than a repository path: the
+ * prefix as written, or the prefix's own folder name alone (which names the
+ * folder, and is refused as such by the resolver). A path that only CONTAINS
+ * the name — `/__tmp__/x`, `knowledge-base/__tmp__/x` — is an ordinary
+ * repository path.
+ */
+export function isTmpRef(value: unknown): boolean {
+  return typeof value === 'string' && (value === TMP_REF_PREFIX.slice(0, -1) || value.startsWith(TMP_REF_PREFIX));
+}
+
+/**
+ * Why a tool refuses a tmp ref in an input that is not one of the four that
+ * take it: the folder is read-only through the ref, and a file is kept by
+ * copying it into the repository. A 400 with a `kind` to branch on, before
+ * any gate, lock or write.
+ */
+export function tmpRefReadOnlyRefusal(ref: string, tool: string): WorkflowValidationError {
+  const shown = sanitizedPath(ref);
+  return new WorkflowValidationError(
+    `"${shown}" is a tmp ref, and ${tool} does not take one there: the workspace's tmp folder is read-only through ` +
+      'the ref. read_file, file_stat and grep read the one file it names; to keep the file, copy_file it to a ' +
+      'repository path (the ref as `src`, the repository path as `dest`).',
+    { kind: 'tmp-ref-read-only', path: shown, tool },
+  );
+}
+
+/** The tool inputs that carry a workspace path as a string. */
+const PATH_INPUTS = ['path', 'src', 'dest', 'destination'] as const;
+
+/**
+ * Every path a tool call carries, with the input it came in: the string
+ * inputs, and for EVERY list input, each entry that is a path itself
+ * (`paths` of `request_file_download`) or an object carrying one in `path`
+ * (`files[].path` of a batch write, `resolutions[].path` of
+ * `update_branch`). Read by shape rather than by a list of tool inputs, so a
+ * list a tool adds later is gated without anyone remembering to name it here.
+ */
+function pathEntries(args: Record<string, unknown>): Array<[string, unknown]> {
+  const entries: Array<[string, unknown]> = PATH_INPUTS.map((key) => [key, args[key]]);
+  for (const [key, value] of Object.entries(args)) {
+    if (!Array.isArray(value)) continue;
+    for (const item of value as unknown[]) {
+      if (typeof item === 'string') {
+        if (key === 'paths') entries.push([key, item]);
+      } else if (item && typeof item === 'object') {
+        entries.push([key, (item as Record<string, unknown>).path]);
+      }
+    }
+  }
+  return entries;
+}
+
+/**
+ * Refuse a tmp ref in any input of `tool` that is not in `takes` — with
+ * {@link tmpRefReadOnlyRefusal}, before anything else runs. `takes` is empty
+ * for every tool but the four reads of the one file a ref names.
+ */
+export function assertTmpRefsTaken(tool: string, args: Record<string, unknown>, takes: readonly string[] = []): void {
+  for (const [key, value] of pathEntries(args)) {
+    if (isTmpRef(value) && !takes.includes(key)) throw tmpRefReadOnlyRefusal(value as string, tool);
+  }
+}