@bevel-software/platform-core-backend 0.34.0 → 0.36.1

package/dist/modules/workspace/workspace.tools.js

@@ -5,9 +5,9 @@ import { hasHttpStatus, ToolError, BRANCH_INPUT, toolDef, CAN_WRITE_CLAUSE, defa
 import { notifyAgentRead, assertAgentWriteAllowed, SESSION_ID_INPUT, } from './agent-access.gate.js';
 import { requireInternalSource, requireExternalSource } from '../tool-auth/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import { GitInternalsError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { GitInternalsError, VersionControlValidationError } from '../../shared/domain-errors.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
-// relies on) — not a workflow service, so this stays inside the module boundary.
+// relies on) — not a version-control service, so this stays inside the module boundary.
 import { assertInsideRepo, assertRepoRootNameFree, assertRepoRootNameFreeArgs, hasControlCharacter, isInsideRepo, isTmpRef, normalizePathArgs, normalizeWorkspacePath, } from '../kb-fs/index.js';
 import { GitGuardedFilesystem, MoveLockedError, MoveRacedError } from '../kb-fs/index.js';
 import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
@@ -142,6 +142,12 @@ async function keepFolderOf(fs, ctx, branch, removedPath, kbDirName) {
 }
 const int = (description) => ({ type: 'integer', description });
 const str = (description) => ({ type: 'string', description });
+/**
+ * A write to the default branch is live at once, so the agent asks first. Said on the four
+ * tools behind 87 of the 91 writes there in the agent-guide benchmark (2026-10-26); `start-here`
+ * says it for the other write tools.
+ */
+const ASK_BEFORE_DEFAULT_BRANCH = ' On the default branch a write is live for everyone at once: unless the person already said where, ask them first whether to write there or propose it on a draft.';
 /**
  * The upload route, named on every tool that takes content as a JSON string.
  *
@@ -483,7 +489,7 @@ function refuseEntry(entry, err) {
         entry.message = err.message;
         return;
     }
-    if (err instanceof GitInternalsError || err instanceof WorkflowValidationError) {
+    if (err instanceof GitInternalsError || err instanceof VersionControlValidationError) {
         entry.error = err.payload?.kind ?? 'refused';
         entry.message = err.message;
         return;
@@ -829,8 +835,9 @@ changeGate,
  */
 uploads, 
 /**
- * The platform's agent guide (see `modules/agent-guide`), which `read_file`
- * and `file_stat` answer at the guide's name in the repository root — after
+ * The start of the platform's agent guide and the list of its sections
+ * (`guideStartText` in `modules/agent-guide`), which `read_file` and
+ * `file_stat` answer at the guide's name in the repository root — after
  * the knowledge base's own file of that name, when it has one. Optional for
  * the harnesses that are about the file primitives; without it the two
  * tools read the disk and nothing else.
@@ -853,7 +860,8 @@ starterPacks,
 /**
  * The one tree walk (see `shared/fs.contract.ts`), for the `firstRun`
  * note's look at the knowledge folder. Optional for the harnesses about the
- * file primitives; without it `start_session` answers the id alone.
+ * file primitives; without it `start_session` answers
+ * `{ sessionId, defaultBranch }` and never `firstRun`.
  */
 disk, 
 /**
@@ -1208,7 +1216,7 @@ patternMatcher) {
     };
     /**
      * The paths among `paths` the caller may NOT write, judged exactly as the
-     * lock gate judges them (`WorkflowService.acquireLock`): on a protected
+     * lock gate judges them (`VersionControlService.acquireLock`): on a protected
      * branch only, against the access tree at HEAD, with no rules at HEAD
      * meaning allow. Empty on a draft branch — changes there reach a protected
      * branch only through a change request.
@@ -1636,16 +1644,17 @@ patternMatcher) {
     // transport hiccup on its first call as an unrecoverable start.
     const startSessionDef = toolDef({
         name: 'start_session',
-        description: 'Mint this conversation\'s id: the `sessionId` KnowledgeBase tools take. Call this ONCE, at the start of your work — minting a new id mid-run starts a second conversation as far as the server is concerned. The id is also a chat session in the app, so you can hand the SAME id to the `ask` tool: your reads and your questions are then one conversation. Pass the returned id as `sessionId` on every later KnowledgeBase tool call, inside `call_tool_chain` too. RETRYING IS SAFE: a call that fails created nothing, so retry it. If a retry lands after a success you hold two independent ids, which is harmless: keep passing the one you already used and ignore the other. Returns `{ sessionId }`, plus `firstRun` while the knowledge base is still empty: a note to act on.',
+        description: 'Mint this conversation\'s id: the `sessionId` KnowledgeBase tools take. Call this ONCE, at the start of your work — minting a new id mid-run starts a second conversation as far as the server is concerned. Pass the returned id as `sessionId` to every tool whose arguments list it, inside `call_tool_chain` too; the others refuse it. Where the deployment offers an `ask` tool, hand it the SAME id: your reads and your questions are then one conversation. RETRYING IS SAFE: a call that fails created nothing, so retry it. If a retry lands after a success you hold two independent ids, which is harmless: keep passing the one you already used and ignore the other. Returns `{ sessionId, defaultBranch }`, plus `firstRun` while the knowledge base is empty: a note to act on.',
         path: '/api/agent/tools/start_session',
         inputs: { type: 'object', properties: {}, additionalProperties: false },
         outputs: {
             type: 'object',
             properties: {
-                sessionId: str('The minted session id — pass it as `sessionId` on subsequent KnowledgeBase tool calls and to `ask`.'),
+                sessionId: str('The minted session id — pass it as `sessionId` to the tools that take one, and to `ask` where there is one.'),
+                defaultBranch: str("The deployment's default branch: the branch people read, and the one to pass as `branch` unless you are working on a draft."),
                 firstRun: str(`Present only while the knowledge base holds nothing but its starter guide (and a starter pack's untouched pages): what to offer the person (the guide's \`${FIRST_RUN_SECTION_ID}\` section says how).`),
             },
-            required: ['sessionId'],
+            required: ['sessionId', 'defaultBranch'],
         },
         tags: ['workspace'],
     });
@@ -1661,8 +1670,11 @@ patternMatcher) {
     // per-chat sessionIds over its lifetime.
     requireExternalSource, toolHandler(async (_args, ctx) => {
         const { sessionId } = await sessionSink.createSession(ctx.user.id, new Date());
+        // Read here, not at registration: the setup save applies a branch model
+        // to the running graph, and the name in effect is the one to give.
+        const defaultBranch = kb.defaultBranch;
         const firstRun = await firstRunFor(ctx);
-        return firstRun ? { sessionId, firstRun } : { sessionId };
+        return firstRun ? { sessionId, defaultBranch, firstRun } : { sessionId, defaultBranch };
     }));
     /**
      * The `firstRun` note (see `first-run.ts`) while the default branch's
@@ -1843,7 +1855,7 @@ patternMatcher) {
         description: 'Read a workspace file as text. Returns `{ path, content, canWrite }`. Per the shared content rule: text as ' +
             'text, documents and email as extracted text, an image as the picture, anything else as a one-line ' +
             'description. Also reads a `__tool_chain_spill__/…` ref back from a truncated `call_tool_chain`: it ' +
-            'belongs to no workspace, so `branch` is ignored and no `canWrite` comes back. `offset`/`limit` slice the ' +
+            'belongs to no workspace: any existing `branch` will do, and no `canWrite` comes back. `offset`/`limit` slice the ' +
             'content (characters; bytes for a spill ref; ignored for an image): page through large files and ' +
             'spills, never read multi-MB whole. `canWrite`: may you change this file directly on the default branch. ' +
             CAN_WRITE_CLAUSE,
@@ -1852,8 +1864,8 @@ patternMatcher) {
             properties: {
                 branch: BRANCH_INPUT,
                 path: str(`Path to read, under \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`), with or without a leading slash — a path without that prefix is placed under \`${kbDirName}/\` — or a \`__tool_chain_spill__/…\` ref from a truncated \`call_tool_chain\`, or a \`__tmp__/…\` ref to a file you staged in the workspace's tmp folder.`),
-                offset: int('Start character index (default 0).'),
-                limit: int('Max characters to return from `offset`.'),
+                offset: int('Start character index (bytes for a spill ref; default 0).'),
+                limit: int('Max characters to return from `offset` (bytes for a spill ref).'),
                 sessionId: SESSION_ID_INPUT,
             },
             required: ['branch', 'path'],
@@ -2515,6 +2527,7 @@ patternMatcher) {
         gated: true,
         description: 'Write a workspace TEXT file. The change is committed + pushed as you. Returns `{ path, bytes, outcome }`, where `outcome` is ' +
             '`created`, `replaced` or `updated`.' +
+            ASK_BEFORE_DEFAULT_BRANCH +
             UPLOAD_ROUTE_NOTE,
         inputs: {
             type: 'object',
@@ -2595,6 +2608,7 @@ patternMatcher) {
             '`created` / `replaced` / `updated` for a path it wrote, or `refused` with `error` (the code) and `message` (why) for a ' +
             'path it could not. `count` is how many were written. A path it refuses — the mode said no, or the file is not text — ' +
             'does not stop the others; read `files` to see what landed.' +
+            ASK_BEFORE_DEFAULT_BRANCH +
             UPLOAD_ROUTE_NOTE,
         inputs: {
             type: 'object',
@@ -2632,7 +2646,7 @@ patternMatcher) {
                                 enum: ['created', 'replaced', 'updated', 'refused'],
                                 description: 'What happened at this path. `refused` means nothing was written there and the file is untouched.',
                             },
-                            error: str('Present when `outcome` is `refused`: the refusal code — `exists`, `missing` or `binary_not_writable`.'),
+                            error: str('Present when `outcome` is `refused`: the refusal code, such as `exists`, `missing`, `binary_not_writable` or a code of the deployment\'s own write check.'),
                             message: str('Present when `outcome` is `refused`: the full refusal, the same one write_file would have given.'),
                         },
                         required: ['path', 'outcome'],
@@ -2661,7 +2675,7 @@ patternMatcher) {
                 writePolicy.assertPathWritable(ctx.sessionId, f.path);
             const fs = await ctx.getFilesystem(a.branch);
             // `write: true` guarantees a LockingFilesystem here; `writeFiles` lands the
-            // batch as one commit. Structural cast avoids a workflow-internal import.
+            // batch as one commit. Structural cast avoids a version-control-internal import.
             const batching = fs;
             const writes = [];
             const outcomes = [];
@@ -2761,6 +2775,7 @@ patternMatcher) {
         name: 'edit_file',
         gated: true,
         description: 'Replace an exact string in a workspace TEXT file. `old_string` must appear exactly once unless `replace_all`. Committed + pushed as you.' +
+            ASK_BEFORE_DEFAULT_BRANCH +
             UPLOAD_ROUTE_NOTE,
         inputs: {
             type: 'object',
@@ -2839,7 +2854,8 @@ patternMatcher) {
     mount({
         name: 'delete_file',
         gated: true,
-        description: 'Delete ONE workspace file. Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`.',
+        description: 'Delete ONE workspace file. Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`.' +
+            ASK_BEFORE_DEFAULT_BRANCH,
         inputs: {
             type: 'object',
             properties: {
@@ -3003,7 +3019,7 @@ patternMatcher) {
                 // ordering trick to keep the rest governed on the way — nothing lands
                 // until all of it does. The placeholders go too: this is the one
                 // operation that removes a folder. Structural cast, as `write_files`
-                // does, to avoid importing the workflow-internal class here.
+                // does, to avoid importing the version-control-internal class here.
                 if (files.length > 0) {
                     const batch = fs;
                     await batch.writeFiles([], `Delete ${path} and its ${content.length} file(s)`, files);
@@ -3061,10 +3077,11 @@ patternMatcher) {
         // the shared rules now, which are rebuilt from the layout where they live.
         description: 'Move or rename a workspace FILE or FOLDER; a folder moves recursively, with everything under it. `dest` is the full new path, not the folder to move into. Committed + pushed as you. ' +
             'The destination must not exist — a move never overwrites a file or merges into a folder. Access follows the ' +
-            'DESTINATION folder, so a move can change what you (and others) may do with the file: the dry run answers ' +
-            '`{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }`, where `access` is your ' +
-            'own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the move has landed, ' +
-            'with every `access.md` inside a moved folder counted at its new place, and a move whose `accessChanges` is true wants `confirm: true`. ' +
+            'DESTINATION folder, so a move can change who may open or edit the file. You must be able to read what moves and the folder it lands in, ' +
+            'or it is refused as read_file refuses. The dry run answers ' +
+            '`{ src, dest, kind, descendants, access: { before, after }, accessChanges, holderChanges?, allowed, reason? }`: your own ' +
+            'access at both ends, and who else loses or gains it. A move that changes either wants `confirm: true`; tell the person ' +
+            'who loses and who gains before you confirm. ' +
             'Links are rewritten by default, in one commit with the move: those in the moved files and those in other markdown files pointing at them (`links` reports them). `rewriteLinks: false` turns that off. Path mentions in plain prose or code are never changed.',
         inputs: {
             type: 'object',
@@ -3073,7 +3090,7 @@ patternMatcher) {
                 src: wsPath(kbDirName, 'Source path (file or folder)'),
                 dest: wsPath(kbDirName, 'Destination path — the full new path; must not exist yet'),
                 dryRun: { type: 'boolean', description: 'Answer with the impact and change nothing.' },
-                confirm: { type: 'boolean', description: 'Required when the move changes your access. Set it only after a dry run.' },
+                confirm: { type: 'boolean', description: 'Required when the move changes your access or anyone else\'s. Set it only after a dry run.' },
                 rewriteLinks: { type: 'boolean', description: 'Rewrite the links into, out of and between the moved files (default true). `false` moves without touching any link.' },
                 sessionId: SESSION_ID_INPUT,
             },
@@ -3087,8 +3104,13 @@ patternMatcher) {
                 dest: str('Destination path (echoes the input).'),
                 kind: str('`file` or `folder`.'),
                 descendants: int('Files that move: 1 for a file, the file count under a folder.'),
-                access: { type: 'object', description: 'Your `{ read, write, download, owner }` at the source (`before`) and at the destination once the move has landed (`after`).' },
+                access: { type: 'object', description: 'Your `{ read, write, download, owner }` at the source (`before`) and at the destination once the move has landed (`after`), with every `access.md` inside a moved folder counted at its new place.' },
                 accessChanges: { type: 'boolean', description: 'True when any of your verdicts differs between `before` and `after`.' },
+                holderChanges: {
+                    type: 'object',
+                    description: 'Who loses and who gains opening (`read`) or editing (`write`) it once the move has landed: `{ lose, gain }`, each ' +
+                        '`[{ kind, name, email?, verb }]` with `kind` `group`, `role`, `plugin` or `person`. Absent when nobody\'s access changes.',
+                },
                 allowed: { type: 'boolean', description: 'Whether the move may run.' },
                 reason: str('Why it may not, when `allowed` is false.'),
                 dryRun: { type: 'boolean', description: 'True on a dry run.' },
@@ -3117,6 +3139,23 @@ patternMatcher) {
             // source already deleted.
             await assertAgentWriteAllowed(agentAccessGate, ctx, branch, src);
             await assertAgentWriteAllowed(agentAccessGate, ctx, branch, dest);
+            // What moves and the folder it lands in must both be readable to the
+            // caller, refused as read_file refuses them, on every branch: a move
+            // preview reads both ends (the caller's own verdicts there, who else is
+            // affected), and the folder's rules are what the names are made of. The
+            // verdict comes BEFORE every other look, so neither end's existence is
+            // told to someone who may not know it. The deployment's read hook is
+            // asked first, as read_file asks it, and its refusal is the answer: a
+            // move the hook would not let read is not previewed at all, since even
+            // "this move asks for confirm" would tell what the comparison found. A
+            // folder the caller may read moves with everything in it, files they
+            // may not read included: those travel, they are not read.
+            const destFolder = dest.slice(0, dest.lastIndexOf('/'));
+            await notifyAgentRead(agentAccessGate, ctx, branch, src);
+            await notifyAgentRead(agentAccessGate, ctx, branch, destFolder);
+            const gate = readGateFor(branch, ctx);
+            await assertCanRead(gate, src);
+            await assertCanRead(gate, destFolder);
             const fs = await ctx.getFilesystem(branch);
             const root = await workspaceRoot(branch, ctx);
             // Before the kind check, which stats THROUGH a link: a dangling link at
@@ -3140,6 +3179,17 @@ patternMatcher) {
                 accessAfter(branch, ctx, src, dest),
             ]);
             const accessChanges = verbsDiffer(before, after);
+            // Who ELSE gains or loses opening or editing it: the lists the app's move
+            // confirmation shows people. The caller may read both ends (the hook and
+            // the rules, gated above, as the app's route gates), so the names go to
+            // them, and a change asks for `confirm`. Outside the repository no rules
+            // travel.
+            const fromRel = toKbRelative(src, kbDirName);
+            const toRel = toKbRelative(dest, kbDirName);
+            const changes = fromRel !== null && toRel !== null
+                ? await accessControl.prospectiveHolderChanges(workspaceIdForBranch(branch), fromRel, toRel)
+                : undefined;
+            const othersChange = changes !== undefined && (changes.lose.length > 0 || changes.gain.length > 0);
             // The placeholder moves with its folder, but it is never content.
             const descendants = srcFiles.filter((f) => !isFolderPlaceholder(f)).length;
             // Neither end may be the platform's own: a move neither takes a platform
@@ -3243,6 +3293,7 @@ patternMatcher) {
                 descendants,
                 access: { before, after },
                 accessChanges,
+                ...(othersChange ? { holderChanges: changes } : {}),
                 allowed: moveReason === undefined,
                 ...(moveReason !== undefined ? { reason: moveReason } : {}),
                 ...(linkPlan ? { links: linkPlan.report } : {}),
@@ -3262,12 +3313,16 @@ patternMatcher) {
                 throw new ToolError(reason, 409);
             if (linkPlan?.overCap !== undefined)
                 throw new ToolError(linkPlan.overCap, 400);
-            if (accessChanges && a.confirm !== true) {
+            if ((accessChanges || othersChange) && a.confirm !== true) {
+                const why = [
+                    ...(accessChanges ? [`your access at "${dest}" differs from "${src}"`] : []),
+                    ...(othersChange ? ['it changes who else may open or edit it (`holderChanges`)'] : []),
+                ];
                 return {
                     ...impact,
                     confirmationRequired: true,
                     moved: false,
-                    message: `Nothing was moved: your access at "${dest}" differs from "${src}", so this move requires confirm: true.`,
+                    message: `Nothing was moved: ${why.join(', and ')}, so this move requires confirm: true.`,
                 };
             }
             // The look above is what produces the sentence; the filesystem's own
@@ -3320,8 +3375,8 @@ patternMatcher) {
         name: 'copy_file',
         gated: true,
         description: 'Copy a workspace FILE to a new path. The destination must not exist — like a move, a copy never overwrites a file or a folder; to change what is in a file that already exists, write it. Committed + pushed as you. `src` may be a `__tmp__/<path>` ref to a file you staged in the workspace\'s tmp folder: the copy is how such a file is kept, as a normal repository file. ' +
-            'Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the copy has landed, with every `access.md` inside a copied folder counted at its new place. ' +
-            'One exception to that shape: when the destination is one you may not write, the answer is the refusal alone — `allowed: false` with `reason`, and no `kind` and no `descendants`, because nothing about the source is read before that verdict.',
+            'Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the copy has landed, with the copy\'s own rules counted at its new place. ' +
+            'One exception to that shape: when the destination is one you may not write, the answer is the refusal (`allowed: false` with `reason`, and the access figures) with no `kind` and no `descendants`, because nothing about the source is read before that verdict.',
         inputs: {
             type: 'object',
             properties: {
@@ -3741,7 +3796,7 @@ patternMatcher) {
                 '`replaced` / `updated`, or `refused` with `error` (the code) and `message` (why). `count` is how many landed and ' +
                 '`total` how many paths there were; `files` is cut to the first 25 unless you pass `all: true`. ' +
                 'Every path is judged one by one — by your write access, the platform-file rules and what is already there — ' +
-                'exactly as `write_file` judges it, and a refused path does not stop the others. ' +
+                'as `write_file` judges it, except that platform files are refused and binary content is fine; a refused path does not stop the others. ' +
                 'The token is single-use: it is spent by the apply that lands it, and refused if you use it twice, let it ' +
                 'expire, or present one issued to somebody else. `mode` means what it means on `write_file`.',
             inputs: {
@@ -3820,7 +3875,7 @@ patternMatcher) {
                 'each one inside a folder too, is included only if you may read AND download that file. Returns ' +
                 '`{ expiresAt, expiresInSeconds, files: [{ path, bytes, sha256, downloadUrl }], folders: [{ path, bytes, ' +
                 'downloadUrl, files }], refused: [{ path, reason }] }`: a link per file, with its own content type, and per ' +
-                `folder a zip at full repository paths (\`apply_file_upload\` it at \`${kbDirName}/\` to put every file back). ` +
+                `folder a zip at full repository paths (\`apply_file_upload\` it at \`${kbDirName}/\` to put them back). ` +
                 'Fetch with any HTTP client (`curl -o <name> "<downloadUrl>"`, or the address without its last segment and an ' +
                 '`x-download-token` header). Each link works ONCE, for 15 minutes, and serves the files as they are now. ' +
                 'Refused: `not found` (missing or named-but-unreadable; folders omit unreadable files), ' +