@bevel-software/platform-core-backend 0.22.0 → 0.23.0

package/src/modules/workflow/workflow-hooks.ts

@@ -1,14 +1,13 @@
-import type { ValidationReport } from '@bevel-software/platform-shared';
+import type { AuthUser, ValidationReport } from '@bevel-software/platform-shared';
 
 /**
  * Workflow lifecycle hooks — the generic seam that replaced the
- * constructor-injected KB validator (and the core-owned ontology write block).
- * Core code invokes the hooks at fixed lifecycle points; the modules that OWN
- * the behavior (the enterprise kb/kb-graph modules today) register handlers in
- * the composition root, right after `createCoreServices` returns. Core
- * registers none, so a core-only deployment runs every hook point as a no-op.
+ * constructor-injected KB validator. Core code invokes the hooks at fixed
+ * lifecycle points; the modules that OWN the behavior register handlers in the
+ * composition root, right after `createCoreServices` returns. Core registers
+ * none, so a core-only deployment runs every hook point as a no-op.
  *
- * Two hook kinds with deliberately different failure semantics:
+ * Three hook kinds, with deliberately different failure semantics:
  *
  *   - `commitValidation` — ADVISORY. Runs at commit time in `GitService`
  *     (`commit` / `commitFile`), exactly where the injected `IKbValidator`
@@ -18,12 +17,18 @@ import type { ValidationReport } from '@bevel-software/platform-shared';
  *     `runValidation(workspaceId)` shape so `KbValidatorService` registers
  *     with a one-line adapter.
  *
- *   - `preWrite` — BLOCKING. Runs before a gated agent write (file-write
- *     tools) or a write-capable shell command; a hook that throws REJECTS the
- *     operation (the error propagates to the tool caller). This is where the
- *     enterprise ontology-session block registers; core registers nothing, so
- *     core never blocks (touch TRACKING stays core — see
- *     `session-ontology.gate.ts`).
+ *   - `agentRead` — BLOCKING. Runs before a gated agent READ of a
+ *     knowledge-base path (reads, `delete_file`, `delete_folder`, and each
+ *     file a `grep` walk opens). A hook that throws REFUSES the read.
+ *
+ *   - `preWrite` — BLOCKING. Runs before a gated agent WRITE (the file-write
+ *     tools, once per path) or a write-capable shell command, which carries no
+ *     path. A hook that throws REFUSES the operation, and the caller sees the
+ *     hook's own message and status.
+ *
+ * The two blocking hooks are the seam a deployment builds a per-conversation
+ * rule on: they carry the session id the call named, and core itself neither
+ * decides nor records anything (see `workspace/agent-access.gate.ts`).
  */
 
 /** What `GitService` knows at the advisory commit-validation point. */
@@ -47,19 +52,35 @@ export type CommitValidationHook = (
 ) => Promise<ValidationReport | void>;
 
 /**
- * What the pre-write gate knows when it consults the blocking hooks. The core
- * gate has already resolved all skip conditions (boundary flag off, neutral
- * path, non-agent caller, recovery bot, missing session id — see
- * `resolveGatedSession`), so by hook time there is always a session id.
+ * What an agent operation looks like to the blocking hooks. The core gate has
+ * already resolved the only two skips it owns (the caller is not an agent, or
+ * is the recovery bot), so every hook call describes a real agent operation.
+ *
+ * `sessionId` is present only when the call carried one — core does NOT fail
+ * closed on its absence, because whether a path needs a session is the
+ * registering deployment's rule, not core's.
  */
-export type PreWriteContext =
-  /** A path-addressed content write (write_file/edit_file/mkdir/move/copy/unzip…). */
-  | { kind: 'file-write'; sessionId: string; wsPath: string }
-  /** A write-capable operation with no resolvable target path (execute_command). */
-  | { kind: 'shell'; sessionId: string };
+export interface AgentOperationContext {
+  /** The conversation the call belongs to, when it named one. */
+  sessionId?: string;
+  /**
+   * The workspace-relative path the operation targets. Absent for a
+   * write-capable operation with no resolvable target (`execute_command`).
+   */
+  wsPath?: string;
+  /** The branch (draft) whose workspace the operation acts on. */
+  branch: string;
+  /** The calling user. */
+  user: AuthUser;
+  /** Whether the caller is the in-app agent (`internal`) or an external one. */
+  source: 'internal' | 'external';
+}
 
-/** Blocking pre-write hook: throw to reject the write; return to allow. */
-export type PreWriteHook = (ctx: PreWriteContext) => Promise<void>;
+/** Blocking pre-read hook: throw to refuse the read; return to allow. */
+export type AgentReadHook = (ctx: AgentOperationContext) => Promise<void>;
+
+/** Blocking pre-write hook: throw to refuse the write; return to allow. */
+export type PreWriteHook = (ctx: AgentOperationContext) => Promise<void>;
 
 /**
  * The registry instance. ONE per composition (created in
@@ -68,6 +89,7 @@ export type PreWriteHook = (ctx: PreWriteContext) => Promise<void>;
  */
 export class WorkflowHooks {
   private readonly commitValidation: CommitValidationHook[] = [];
+  private readonly agentRead: AgentReadHook[] = [];
   private readonly preWrite: PreWriteHook[] = [];
 
   /** Register an advisory commit-time validation hook. */
@@ -75,6 +97,11 @@ export class WorkflowHooks {
     this.commitValidation.push(hook);
   }
 
+  /** Register a blocking pre-read hook. */
+  onAgentRead(hook: AgentReadHook): void {
+    this.agentRead.push(hook);
+  }
+
   /** Register a blocking pre-write hook. */
   onPreWrite(hook: PreWriteHook): void {
     this.preWrite.push(hook);
@@ -88,12 +115,23 @@ export class WorkflowHooks {
     return this.commitValidation;
   }
 
+  /**
+   * Run every blocking pre-read hook in registration order. The first throw
+   * propagates and refuses the read; with no hooks registered (core-only)
+   * this resolves immediately.
+   */
+  async runAgentRead(ctx: AgentOperationContext): Promise<void> {
+    for (const hook of this.agentRead) {
+      await hook(ctx);
+    }
+  }
+
   /**
    * Run every blocking pre-write hook in registration order. The first throw
-   * propagates and rejects the write; with no hooks registered (core-only)
+   * propagates and refuses the write; with no hooks registered (core-only)
    * this resolves immediately.
    */
-  async runPreWrite(ctx: PreWriteContext): Promise<void> {
+  async runPreWrite(ctx: AgentOperationContext): Promise<void> {
     for (const hook of this.preWrite) {
       await hook(ctx);
     }

package/src/modules/workflow/workflow.service.ts

@@ -63,7 +63,7 @@ import {
   isPlatformRestoreShape,
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
-import { and, desc, eq, inArray, isNotNull, isNull, lt, ne, or } from 'drizzle-orm';
+import { and, desc, eq, inArray, isNotNull, isNull, lt, ne, or, sql } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { changeRequests } from '../database/schema.js';
 import type { GitService } from './git/git.service.js';
@@ -324,9 +324,9 @@ export class WorkflowService implements IWorkflowService {
      * the composition root registers module-owned behavior against it
      * (`core.workflowService.hooks.onCommitValidation(…)` /
      * `.onPreWrite(…)`) after `createCoreServices` returns. The composition
-     * root passes the SAME instance `GitService` and the session-ontology
-     * gate consult; the default keeps test constructions (which don't
-     * exercise hooks) unchanged.
+     * root passes the SAME instance `GitService` and the agent-access gate
+     * consult; the default keeps test constructions (which don't exercise
+     * hooks) unchanged.
      */
     public readonly hooks: WorkflowHooks = new WorkflowHooks(),
   ) {
@@ -910,6 +910,22 @@ export class WorkflowService implements IWorkflowService {
     return this.git.fileContentsAtCommit(workspaceId, path, sha);
   }
 
+  /**
+   * The BYTES of one file at a change — what the file page's byte-reading
+   * viewers (pdf, image, docx, pptx, xlsx, email) need to show a past save,
+   * and what "Download this version" hands over. `fileAtChange` above cannot
+   * serve them: it decodes to UTF-8, which ruins every format that is not
+   * text.
+   */
+  fileBytesAtChange(
+    workspaceId: string,
+    path: string,
+    sha: string,
+    side: 'after' | 'before',
+  ): Promise<{ bytes: Buffer; blobId: string } | null> {
+    return this.git.fileBytesAtCommit(workspaceId, path, sha, side);
+  }
+
   /**
    * Resolve write permission for `targetPath` against the access tree at
    * `HEAD` of `branch`. Throws `AccessDeniedError` on denial with the
@@ -3024,6 +3040,107 @@ export class WorkflowService implements IWorkflowService {
     return closed;
   }
 
+  /**
+   * How many change requests are open right now.
+   *
+   * Read by the setup screen's repository-change confirmation, which has to
+   * say how many requests the admin is deciding about BEFORE the address is
+   * saved. A plain count — nothing here reaches the repository, so it answers
+   * just as well for a repository that is already gone.
+   */
+  async countOpenChangeRequests(): Promise<number> {
+    const [row] = await this.db
+      .select({ open: sql<number>`count(*)::int` })
+      .from(changeRequests)
+      .where(eq(changeRequests.state, 'open'));
+    return row?.open ?? 0;
+  }
+
+  /**
+   * Close every open change request because the knowledge-base REPOSITORY was
+   * replaced, and answer how many were closed.
+   *
+   * The admin's own choice on the setup screen: a repository that merely
+   * MOVED keeps its requests (the branches came along), while a repository
+   * that was REPLACED has none of those branches, so every request points at
+   * something this deployment can no longer fetch. Nothing is deleted — the
+   * rows stay, closed, carrying `closed_reason = 'repository-replaced'` so
+   * the reason survives the person who chose it.
+   *
+   * Locks held on those branches go with them. Their holder cannot publish
+   * the bytes (the branch is not in the new repository) and cannot release
+   * the lock by finishing (the request is closed), so the row would sit there
+   * refusing the path until its TTL ran out — and a still-connected client's
+   * heartbeat keeps pushing that out.
+   *
+   * The close is ONE statement per pass — `update … where state = 'open'
+   * returning` — not a count followed by a row-at-a-time loop. Read first and
+   * then written, every request opened while the loop ran would be missed and
+   * left open against a branch the new repository does not have. One
+   * set-shaped statement cannot miss a row that exists when it runs, and the
+   * guard is the statement's own `where`, so a merge or a withdrawal racing it
+   * wins and its request is simply not in the returned set.
+   *
+   * Repeated while a pass still finds something, because a request can be
+   * opened BETWEEN passes: the caller has not saved the new address yet, so
+   * the deployment is still live and `POST /change-requests` is still being
+   * served. Bounded, so a client opening requests in a loop cannot hold the
+   * save open forever — what survives the last pass is a request opened after
+   * the repository was replaced, which the deleted-branch sweep closes on its
+   * own terms.
+   */
+  async closeOpenChangeRequestsAsRepositoryReplaced(): Promise<number> {
+    let closed = 0;
+    for (let pass = 0; pass < 5; pass++) {
+      const now = new Date();
+      const justClosed = await this.db
+        .update(changeRequests)
+        .set({ state: 'closed', closedAt: now, updatedAt: now, closedReason: 'repository-replaced' })
+        .where(eq(changeRequests.state, 'open'))
+        .returning({ number: changeRequests.number, sourceBranch: changeRequests.sourceBranch });
+      if (justClosed.length === 0) break;
+      for (const cr of justClosed) {
+        // Best effort, per branch: a lock table that will not answer must not
+        // leave the requests half closed — the close is the decision the admin
+        // made, and the locks expire on their own within the minute.
+        try {
+          const released = await this.fileLocks.releaseAllOnBranch(cr.sourceBranch);
+          if (released > 0) {
+            crLog.info(`released ${released} file lock(s) held on "${cr.sourceBranch}"`);
+          }
+        } catch (err) {
+          crLog.warn(`could not release the file locks on "${cr.sourceBranch}":`, { err });
+        }
+        // The bytes a release already enqueued belong to the repository that
+        // is gone — see `markNeedsAttentionOnBranch`. Taken out of the
+        // worker's reach in the same breath as the locks, because dropping a
+        // lock is precisely what leaves a row behind.
+        try {
+          const quarantined = await this.pendingCommits.markNeedsAttentionOnBranch(
+            cr.sourceBranch,
+            'The knowledge-base repository was replaced while this commit was still queued, so it was never ' +
+              'written. The bytes are kept here: the branch it was meant for belongs to the previous repository.',
+          );
+          if (quarantined > 0) {
+            crLog.warn(
+              `${quarantined} queued commit(s) on "${cr.sourceBranch}" need attention: the repository was replaced ` +
+                'before they landed, so they were not written to the new one.',
+            );
+          }
+        } catch (err) {
+          crLog.warn(`could not set aside the queued commits on "${cr.sourceBranch}":`, { err });
+        }
+        this.prs.invalidateDetailCache(cr.number);
+        this.events?.emit({ kind: 'change-request-rejected', number: cr.number });
+        closed++;
+      }
+    }
+    if (closed > 0) {
+      crLog.info(`closed ${closed} change request(s): the knowledge-base repository was replaced`);
+    }
+    return closed;
+  }
+
   /**
    * The sweep above, on demand. Boot runs it once (`create-core-server`),
    * which clears requests stranded BEFORE the process started; a branch that

package/src/modules/workspace/__tests__/agent-access.gate.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it, beforeEach } from 'vitest';
+import {
+  notifyAgentRead,
+  assertAgentWriteAllowed,
+  SESSION_ID_DESCRIPTION,
+  SESSION_ID_INPUT,
+  ToolDescriptionNotes,
+  type AgentAccessGate,
+} from '../agent-access.gate.js';
+import { WorkflowHooks, type AgentOperationContext } from '../../workflow/workflow-hooks.js';
+import { ToolError, type ToolContext } from '../../tool-helpers/tool.contract.js';
+
+const RECOVERY_EMAIL = 'recovery-bot@bevel.local';
+const P_FILE = 'knowledge-base/KnowledgeBase/Product/Knowledge/Roadmap.md';
+
+function ctx(over: Partial<ToolContext> = {}): ToolContext {
+  return {
+    user: { id: 'u1', email: 'a@b.c', name: 'A' },
+    scope: 'write',
+    source: 'external',
+    sessionId: 's1',
+    abortSignal: new AbortController().signal,
+    workspaceService: {} as never,
+    workflowService: {} as never,
+    events: {} as never,
+    getFilesystem: async () => ({}) as never,
+    ...over,
+  } as ToolContext;
+}
+
+/** A gate with a fresh hook registry, plus the two lists of what the hooks saw. */
+function makeGate(): { gate: AgentAccessGate; reads: AgentOperationContext[]; writes: AgentOperationContext[] } {
+  const hooks = new WorkflowHooks();
+  const reads: AgentOperationContext[] = [];
+  const writes: AgentOperationContext[] = [];
+  hooks.onAgentRead(async (op) => {
+    reads.push(op);
+  });
+  hooks.onPreWrite(async (op) => {
+    writes.push(op);
+  });
+  return { gate: { recoveryBotEmail: RECOVERY_EMAIL, hooks, notes: new ToolDescriptionNotes() }, reads, writes };
+}
+
+describe('notifyAgentRead', () => {
+  it('calls the read hook once with the session, path, branch, user and source', async () => {
+    const { gate, reads, writes } = makeGate();
+    await notifyAgentRead(gate, ctx(), 'draft-1', P_FILE);
+    expect(reads).toEqual([
+      {
+        sessionId: 's1',
+        wsPath: P_FILE,
+        branch: 'draft-1',
+        user: { id: 'u1', email: 'a@b.c', name: 'A' },
+        source: 'external',
+      },
+    ]);
+    expect(writes).toEqual([]);
+  });
+
+  it('carries the in-app agent as source `internal`', async () => {
+    const { gate, reads } = makeGate();
+    await notifyAgentRead(gate, ctx({ source: 'internal' }), 'main', P_FILE);
+    expect(reads[0].source).toBe('internal');
+  });
+
+  it('calls the hook with no session id when the call carried none — the hook decides', async () => {
+    const { gate, reads } = makeGate();
+    await notifyAgentRead(gate, ctx({ sessionId: undefined }), 'main', P_FILE);
+    expect(reads).toHaveLength(1);
+    expect(reads[0].sessionId).toBeUndefined();
+  });
+
+  it('never reaches the hooks for a caller that is not an agent', async () => {
+    const { gate, reads } = makeGate();
+    await notifyAgentRead(gate, ctx({ source: 'session' }), 'main', P_FILE);
+    expect(reads).toEqual([]);
+  });
+
+  it('never reaches the hooks for the recovery bot, whatever the case of its address', async () => {
+    const { gate, reads } = makeGate();
+    await notifyAgentRead(gate, ctx({ user: { id: 'bot', email: 'Recovery-Bot@Bevel.local', name: 'bot' } }), 'main', P_FILE);
+    expect(reads).toEqual([]);
+  });
+
+  it('refuses the read with the hook\'s own message and status', async () => {
+    const hooks = new WorkflowHooks();
+    hooks.onAgentRead(async () => {
+      throw new ToolError('Not in this conversation.', 403);
+    });
+    const gate: AgentAccessGate = { recoveryBotEmail: RECOVERY_EMAIL, hooks, notes: new ToolDescriptionNotes() };
+    await expect(notifyAgentRead(gate, ctx(), 'main', P_FILE)).rejects.toMatchObject({
+      message: 'Not in this conversation.',
+      status: 403,
+    });
+  });
+
+  it('is a no-op with no hook registered', async () => {
+    const gate: AgentAccessGate = {
+      recoveryBotEmail: RECOVERY_EMAIL,
+      hooks: new WorkflowHooks(),
+      notes: new ToolDescriptionNotes(),
+    };
+    await expect(notifyAgentRead(gate, ctx({ sessionId: undefined }), 'main', P_FILE)).resolves.toBeUndefined();
+  });
+});
+
+describe('assertAgentWriteAllowed', () => {
+  it('calls the write hook with the path, and never the read hook', async () => {
+    const { gate, reads, writes } = makeGate();
+    await assertAgentWriteAllowed(gate, ctx(), 'draft-1', P_FILE);
+    expect(reads).toEqual([]);
+    expect(writes).toHaveLength(1);
+    expect(writes[0]).toMatchObject({ sessionId: 's1', wsPath: P_FILE, branch: 'draft-1', source: 'external' });
+  });
+
+  it('calls the write hook with NO path for a write-capable call that has none', async () => {
+    const { gate, writes } = makeGate();
+    await assertAgentWriteAllowed(gate, ctx(), 'main');
+    expect(writes).toHaveLength(1);
+    expect(writes[0].wsPath).toBeUndefined();
+    expect(writes[0].branch).toBe('main');
+  });
+
+  it('refuses the write with the hook\'s own message and status', async () => {
+    const hooks = new WorkflowHooks();
+    hooks.onPreWrite(async () => {
+      throw new ToolError('Not in this conversation.', 403);
+    });
+    const gate: AgentAccessGate = { recoveryBotEmail: RECOVERY_EMAIL, hooks, notes: new ToolDescriptionNotes() };
+    await expect(assertAgentWriteAllowed(gate, ctx(), 'main', P_FILE)).rejects.toMatchObject({
+      message: 'Not in this conversation.',
+      status: 403,
+    });
+  });
+
+  it('runs every registered write hook, in registration order, until one throws', async () => {
+    const hooks = new WorkflowHooks();
+    const seen: string[] = [];
+    hooks.onPreWrite(async () => {
+      seen.push('first');
+    });
+    hooks.onPreWrite(async () => {
+      seen.push('second');
+      throw new ToolError('no', 403);
+    });
+    hooks.onPreWrite(async () => {
+      seen.push('third');
+    });
+    const gate: AgentAccessGate = { recoveryBotEmail: RECOVERY_EMAIL, hooks, notes: new ToolDescriptionNotes() };
+    await expect(assertAgentWriteAllowed(gate, ctx(), 'main', P_FILE)).rejects.toThrow('no');
+    expect(seen).toEqual(['first', 'second']);
+  });
+
+  it('never reaches the hooks for a person in the app or for the recovery bot', async () => {
+    const { gate, writes } = makeGate();
+    await assertAgentWriteAllowed(gate, ctx({ source: 'session' }), 'main', P_FILE);
+    await assertAgentWriteAllowed(gate, ctx({ user: { id: 'bot', email: RECOVERY_EMAIL, name: 'bot' } }), 'main', P_FILE);
+    expect(writes).toEqual([]);
+  });
+
+  it('is a no-op with no hook registered, with or without a session id', async () => {
+    const gate: AgentAccessGate = {
+      recoveryBotEmail: RECOVERY_EMAIL,
+      hooks: new WorkflowHooks(),
+      notes: new ToolDescriptionNotes(),
+    };
+    await expect(assertAgentWriteAllowed(gate, ctx(), 'main', P_FILE)).resolves.toBeUndefined();
+    await expect(assertAgentWriteAllowed(gate, ctx({ sessionId: undefined }), 'main', P_FILE)).resolves.toBeUndefined();
+  });
+});
+
+describe('ToolDescriptionNotes', () => {
+  let notes: ToolDescriptionNotes;
+  beforeEach(() => {
+    notes = new ToolDescriptionNotes();
+  });
+
+  it('has no note registered by default, which is every Hexis-only deployment', () => {
+    expect(notes.gatedToolNote()).toBe('');
+    expect(notes.sessionIdDescription()).toBe(SESSION_ID_DESCRIPTION);
+  });
+
+  it('appends a registered gated-tool note and a registered sessionId note', () => {
+    notes.registerGatedToolNote(' Stay put.');
+    notes.registerSessionIdNote(' It also pins the boundary.');
+    expect(notes.gatedToolNote()).toBe(' Stay put.');
+    expect(notes.sessionIdDescription()).toBe(`${SESSION_ID_DESCRIPTION} It also pins the boundary.`);
+  });
+
+  it('tells its subscribers on every registration, so mounted tools re-describe', () => {
+    let calls = 0;
+    notes.onChange(() => {
+      calls++;
+    });
+    notes.registerGatedToolNote(' a');
+    notes.registerSessionIdNote(' b');
+    expect(calls).toBe(2);
+  });
+
+  it('the default sessionId input says what the id is, and mentions no ontology', () => {
+    expect(SESSION_ID_INPUT.description).toBe(SESSION_ID_DESCRIPTION);
+    expect(SESSION_ID_DESCRIPTION).toMatch(/conversation/i);
+    expect(SESSION_ID_DESCRIPTION).toMatch(/start_session/);
+    expect(SESSION_ID_DESCRIPTION).toMatch(/ask/);
+    expect(SESSION_ID_DESCRIPTION.toLowerCase()).not.toContain('ontolog');
+  });
+});