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

package/src/modules/workspace/ripgrep-version.ts

@@ -0,0 +1,35 @@
+/**
+ * ripgrep is what the agents' `grep` tool searches with (`ripgrep-search.ts`),
+ * and there is no other search to fall back on. So its absence is found at
+ * boot, the way a git too old is (`git-version.ts`): by the deploy that
+ * produced the broken image, never by the first agent that searches.
+ *
+ * The Hexis Dockerfile installs it from Debian (`ripgrep`); a server run from
+ * source needs `rg` on its PATH.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('grep');
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Run `rg --version`, log what answered, and throw a worded error naming the
+ * binary when it cannot be run. Call once during startup.
+ */
+export async function assertRipgrep(): Promise<void> {
+  let stdout: string;
+  try {
+    ({ stdout } = await execFileAsync('rg', ['--version']));
+  } catch (err) {
+    throw new Error(
+      `ripgrep (\`rg\`) is required on the server's PATH but could not be run: ${String(err)}. ` +
+        'The grep tool searches with it. The Hexis Dockerfile installs it (Debian package `ripgrep`); ' +
+        'a server run from source needs ripgrep installed.',
+    );
+  }
+  log.info(`search engine: ${stdout.split('\n')[0]!.trim()}`);
+}

package/src/modules/workspace/routine-write-policy.ts

@@ -15,7 +15,7 @@
  * The executor sets the restriction before streaming and clears it after.
  */
 
-import { ToolError } from '../tool-helpers/tool.contract.js';
+import { ToolError } from '../tool-helpers/index.js';
 
 export interface IRoutineWritePolicy {
   /**

package/src/modules/workspace/startup/__tests__/beside-checkout.test.ts

@@ -61,6 +61,17 @@ describe('noteBesideCheckout', () => {
     expect(notes).toEqual([]);
   });
 
+  it("says nothing about the platform's own tmp folder, and names a file or a link squatting its name", async () => {
+    await workspace('main', { dirs: ['tmp/u/chat-uploads'] });
+    await scan();
+    expect(notes).toEqual([]);
+    const dir = await workspace('bob%2Fdraft', { files: ['tmp'] });
+    await scan();
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toContain(`${BESIDE_CHECKOUT_NOTE} "tmp"`);
+    await expect(fs.stat(path.join(dir, 'tmp'))).resolves.toBeTruthy();
+  });
+
   it('marks the folders with a trailing slash so one line says which is which', async () => {
     await workspace('main', { dirs: ['Reports'], files: ['Reports.md'] });
     await scan();

package/src/modules/workspace/startup/beside-checkout.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { logger } from '../../../shared/logging.js';
 import { isAbsence } from '../../../shared/fs.contract.js';
 import { printable } from '../../../shared/printable.js';
+import { WORKSPACE_TMP_DIR } from '../workspace-tmp.js';
 
 const log = logger('kb-startup');
 
@@ -26,11 +27,14 @@ export const BESIDE_CHECKOUT_NOTE = 'Beside the checkout, not in the repository:
  * clone, and a boot that quietly removed it would be a data loss nobody asked
  * for. The operator cleans up, and the note stops on the next start.
  *
- * EVERYTHING other than the checkout folder is named, the platform's own
- * transient `tmp/` scratch included on the rare start that finds one (a run
- * clears it when it finishes). That is deliberate: the note's claim is about
- * what is not in the repository, and a note that quietly kept exceptions would
- * be a note an operator could not trust.
+ * EVERYTHING other than the checkout folder and the platform's own `tmp/`
+ * folder is named. `tmp/` is the one exception, stated here: it is the
+ * platform's (what the chat and the readers stage lives there, reached
+ * through the `__tmp__/` ref — see `workspace-tmp.ts`), it has a sweep of its
+ * own, and a note that told an operator to remove it by hand would be asking
+ * them to delete people's staged files. Everything else is a stray: the note's
+ * claim is about what is not in the repository, and a note that quietly kept
+ * further exceptions would be a note an operator could not trust.
  *
  * NOT a `OnServerStart` step, and deliberately outside the KB startup phase.
  * That phase is gated — it does nothing until the branch model and the
@@ -65,6 +69,10 @@ export async function noteBesideCheckout(
       // the service judges it: a clone mounted elsewhere is the operator's
       // business, here as it is there.
       if (entry.name === kbDirName && (await isDirectory(path.join(workspaceDir, entry.name)))) continue;
+      // The platform's own tmp folder, swept on its own (see the note above).
+      // Judged by `lstat`, as the sweep judges it: a `tmp` that is a link, or
+      // a file, is not that folder, and is named like any other stray.
+      if (entry.name === WORKSPACE_TMP_DIR && entry.isDirectory()) continue;
       // A trailing slash marks the folders, so one line says which is which
       // without the operator having to go and look. Then `printable`, because
       // every name here is disk-controlled text on its way into an operator's

package/src/modules/workspace/startup/kb-git.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { cloneCredentialArgs, credentialHelperValue } from '../../kb-fs/clone-config.js';
+import { cloneCredentialArgs, credentialHelperValue } from '../../kb-fs/index.js';
 import { GitRunError, type IGitRunner } from '../../../shared/git.contract.js';
 import { ClassifiedFailure, classifyGitFailure } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';

package/src/modules/workspace/startup/kb-startup-runner.ts

@@ -19,12 +19,11 @@ import {
   type GitFailureKind,
 } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';
-import { normalizeRepositoryAddress, sameRepository } from '../../kb-fs/remote-url.js';
+import { normalizeRepositoryAddress, sameRepository, assertValidBranchName } from '../../kb-fs/index.js';
 import { setAsideClone, setAsideRepository, setAsideRootFor, setAsideStamp } from '../set-aside-clone.js';
 import { workingCopyShape, type WorkingCopyShape } from '../kb-repository.js';
 import type { FetchOptions, IKbRepository } from '../kb-repository.contract.js';
 import { fetchInstant } from '../fetch-instant.js';
-import { assertValidBranchName } from '../../kb-fs/branch-name.js';
 
 /**
  * The KB startup phase: run every registered {@link OnServerStart} step, in

package/src/modules/workspace/startup/steps/groups-to-plugins.step.ts

@@ -11,9 +11,9 @@ import {
   PLUGIN_SKILLS_DIR,
   renderPluginManifest,
 } from '@bevel-software/platform-shared';
-import type { ToolManualDescriptor } from '../../../tool-manuals/tool-manuals.contract.js';
-import { normalizeToolManual } from '../../../tool-manuals/tool-manuals.service.js';
-import { parseOwnAccessEntries } from '../../../access-model/access-grammar.js';
+import type { ToolManualDescriptor } from '../../../tool-manuals/index.js';
+import { normalizeToolManual } from '../../../tool-manuals/index.js';
+import { parseOwnAccessEntries } from '../../../access-model/index.js';
 import { containsVariableReference } from '../../../../shared/variable-refs.js';
 import { IGNORE_FILENAME, isAbsence, isSkippedEntry, type IFsProbe, type ITreeWalker } from '../../../../shared/fs.contract.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';

package/src/modules/workspace/startup/steps/personal-spaces.step.ts

@@ -11,8 +11,8 @@ import {
   sourceVerbsFor,
   type ParsedEntry,
   type Verb,
-} from '../../../access-model/access-grammar.js';
-import { spliceGrant } from '../../../access-model/access-splice.js';
+} from '../../../access-model/index.js';
+import { spliceGrant } from '../../../access-model/index.js';
 import { isAbsence, type IFsProbe } from '../../../../shared/fs.contract.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 

package/src/modules/workspace/startup/steps/plugin-layout.ts

@@ -4,7 +4,7 @@ import {
   PLUGIN_MCP_FILE,
   PLUGIN_SKILLS_DIR,
 } from '@bevel-software/platform-shared';
-import { BUNDLE_FILE } from '../../../plugins/discovery/bundle-dialect/bundle.source.js';
+import { BUNDLE_FILE } from '../../../plugins/index.js';
 import { isSkippedEntry, type ITreeWalker, type WalkedEntry } from '../../../../shared/fs.contract.js';
 
 /**

package/src/modules/workspace/startup/steps/roles-yaml.step.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import type { IFsProbe } from '../../../../shared/fs.contract.js';
-import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
+import { renderRolesYaml } from '../../../access-model/index.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
 /**

package/src/modules/workspace/startup/steps/seed-tree.ts

@@ -2,12 +2,12 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { IFsProbe, ITreeWalker } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
-import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
+import { renderRolesYaml } from '../../../access-model/index.js';
 import { reservedRootDirs } from './template-files.step.js';
 import { TEMPLATE_SOURCE_FALLBACKS, TemplateSource, renderTemplateText } from './template-source.js';
 import { assertNotGitInternals, hasGitInternalsSegment } from '../../../../shared/git-internals.js';
 import { GitInternalsError } from '../../../../shared/domain-errors.js';
-import { isManagedGuide } from '../../../agent-guide/agent-guide.js';
+import { isManagedGuide } from '../../../agent-guide/index.js';
 import { utf8Text } from '../../../../shared/utf8-text.js';
 
 /**

package/src/modules/workspace/startup/steps/template-files.step.ts

@@ -7,8 +7,8 @@ import {
 } from '@bevel-software/platform-shared';
 import { IGNORE_FILENAME, isAbsence, type IFsProbe } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
-import { PREAMBLE_FILE } from '../../../agent-instructions/compose.js';
-import { isManagedGuide } from '../../../agent-guide/agent-guide.js';
+import { PREAMBLE_FILE } from '../../../agent-instructions/index.js';
+import { isManagedGuide } from '../../../agent-guide/index.js';
 import { TemplateSource } from './template-source.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 import { hasGitInternalsSegment } from '../../../../shared/git-internals.js';

package/src/modules/workspace/startup/steps/template-source.ts

@@ -3,8 +3,8 @@ import { gitignoreLiteral, renderKbLayoutPlaceholders, type KbLayout } from '@be
 import { IGNORE_FILENAME, isAbsence, type EntryStat, type IFsProbe } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
 
-import { PREAMBLE_FILE } from '../../../agent-instructions/compose.js';
-import { sharedFileRulesSection } from '../../../agent-instructions/shared-file-rules.js';
+import { PREAMBLE_FILE } from '../../../agent-instructions/index.js';
+import { sharedFileRulesSection } from '../../../agent-instructions/index.js';
 import { defaultKbTemplateDir } from '../../../../assets.js';
 import { logger } from '../../../../shared/logging.js';
 

package/src/modules/workspace/worker-pool.ts

@@ -0,0 +1,192 @@
+import type { Worker } from 'node:worker_threads';
+
+/**
+ * The pooled worker threads that keep CPU-bound work off the request thread:
+ * the mechanics every worker kind shares, whatever its worker runs. One kind
+ * uses it today, with a pool of its own — the document extractor every office,
+ * PDF and email extraction runs in (`file-readers/extract-in-worker.ts`).
+ *
+ * What a kind brings is how to start its worker; what the pool owns is the
+ * rest: at most `poolMax` workers, a capped queue of jobs waiting for one,
+ * idle workers that never hold a process's exit open, a worker that dies (or
+ * is discarded over its budget) leaving the pool and being replaced for the
+ * next waiting job, and `close()`, which ends them all.
+ *
+ * The owner of a pool is its kind's instance, and the owner of that is the
+ * composition root, which closes it when the graph stops (`lifecycle.ts`), so
+ * no worker outlives what it served.
+ */
+export interface WorkerPoolSizing {
+  /** Workers kept at once; a job past this waits for one to free up. */
+  poolMax: number;
+  /** Jobs that may wait for a worker at once; past it `acquire` refuses with the kind's busy error. */
+  maxWaiting: number;
+}
+
+type Waiter = { resolve: (w: Worker) => void; reject: (err: Error) => void };
+
+export class WorkerPool {
+  private readonly idle: Worker[] = [];
+  private readonly all = new Set<Worker>();
+  private readonly waiting: Waiter[] = [];
+  private closed = false;
+
+  constructor(
+    /** Starts one worker of this pool's kind. */
+    private readonly spawnWorker: () => Worker,
+    private readonly sizing: WorkerPoolSizing,
+    /** The kind's answer for "no worker now, and no room to wait for one" (and for any job after `close`). */
+    private readonly busy: () => Error,
+  ) {}
+
+  /** A worker for one job, given back with `release` — or, when it must not be reused, `discard`. */
+  async acquire(): Promise<Worker> {
+    if (this.closed) throw this.busy();
+    if (this.idle.length === 0 && this.all.size >= this.sizing.poolMax && this.waiting.length >= this.sizing.maxWaiting) {
+      throw this.busy();
+    }
+    const w =
+      this.idle.pop() ??
+      (this.all.size < this.sizing.poolMax
+        ? this.spawn()
+        : await new Promise<Worker>((resolve, reject) => this.waiting.push({ resolve, reject })));
+    w.ref();
+    return w;
+  }
+
+  /**
+   * A worker that has run no job yet, for a job that must not share a thread
+   * with any other job's leftovers. With the pool full, the worker `acquire`
+   * hands over (idle, or freed by another job after waiting in the same queue)
+   * is swapped for a new one in its own place, so the pool never holds more
+   * than `poolMax`.
+   */
+  async acquireFresh(): Promise<Worker> {
+    if (this.closed) throw this.busy();
+    if (this.all.size < this.sizing.poolMax) {
+      const w = this.spawn();
+      w.ref();
+      return w;
+    }
+    return this.swap(await this.acquire());
+  }
+
+  /** A worker whose job ended cleanly goes to the next waiting job, or idles. */
+  release(w: Worker): void {
+    const next = this.waiting.shift();
+    if (next) return next.resolve(w);
+    // An idle worker must not hold a process's exit open.
+    w.unref();
+    this.idle.push(w);
+  }
+
+  /**
+   * A worker that must not run another job — over its budget, or left in a
+   * state its job cannot vouch for — is terminated. Terminating is what stops
+   * a thread mid-computation. It leaves the pool at once, and a fresh worker
+   * goes to the next waiting job.
+   */
+  discard(w: Worker): void {
+    this.leave(w);
+    void w.terminate();
+  }
+
+  /** Ends every worker; a job waiting, or asking after this, is answered busy. */
+  async close(): Promise<void> {
+    this.closed = true;
+    for (const waiter of this.waiting.splice(0)) waiter.reject(this.busy());
+    const workers = [...this.all];
+    this.idle.length = 0;
+    await Promise.all(workers.map((w) => w.terminate()));
+  }
+
+  /**
+   * Terminates `w`, a worker held by the caller, and gives its place straight
+   * to a new one — not to the next waiting job, as `discard` does, which would
+   * leave the new worker one past `poolMax`.
+   */
+  private swap(w: Worker): Worker {
+    this.all.delete(w);
+    void w.terminate();
+    if (this.closed) throw this.busy();
+    const fresh = this.spawn();
+    fresh.ref();
+    return fresh;
+  }
+
+  private spawn(): Worker {
+    const w = this.spawnWorker();
+    this.all.add(w);
+    // A worker that dies — out of memory, or ending itself — leaves the pool.
+    w.once('exit', () => this.leave(w));
+    return w;
+  }
+
+  /** Takes `w` out of the pool, once, and hands its place to the next waiting job. */
+  private leave(w: Worker): void {
+    if (!this.all.delete(w)) return;
+    const at = this.idle.indexOf(w);
+    if (at >= 0) this.idle.splice(at, 1);
+    if (this.closed) return;
+    const next = this.waiting.shift();
+    if (next) next.resolve(this.spawn());
+  }
+}
+
+/**
+ * How one message to a worker ended: its reply; the timeout, with the worker
+ * still running (the caller decides whether to discard it); an error the
+ * worker raised and did not catch; or the worker's exit before it answered.
+ */
+export type Exchange<R> = { reply: R } | { timeout: true } | { error: Error } | { exited: number };
+
+/**
+ * Post `message` to `w` and wait at most `timeoutMs` for its one reply.
+ * `transfer` hands buffers over without copying them on this thread. Never
+ * rejects: every way the exchange can end is an {@link Exchange} the caller
+ * maps to its own answer, and every listener it adds is removed however it
+ * ends.
+ */
+export function exchange<R>(
+  w: Worker,
+  message: unknown,
+  timeoutMs: number,
+  transfer: readonly ArrayBuffer[] = [],
+): Promise<Exchange<R>> {
+  return new Promise((resolve) => {
+    const settle = (outcome: Exchange<R>) => {
+      clearTimeout(timer);
+      w.off('message', onMessage);
+      w.off('error', onError);
+      w.off('exit', onExit);
+      resolve(outcome);
+    };
+    const onMessage = (reply: R) => settle({ reply });
+    const onError = (error: Error) => settle({ error });
+    const onExit = (code: number) => settle({ exited: code });
+    const timer = setTimeout(() => settle({ timeout: true }), timeoutMs);
+    w.on('message', onMessage);
+    w.on('error', onError);
+    w.on('exit', onExit);
+    try {
+      w.postMessage(message, transfer as ArrayBuffer[]);
+    } catch (err) {
+      // A message that cannot be cloned is this exchange's error, not a throw.
+      settle({ error: err instanceof Error ? err : new Error(String(err)) });
+    }
+  });
+}
+
+/**
+ * The longest delay `setTimeout` honours. A longer one fires after 1 ms, so a
+ * budget past this would stop every job at once.
+ */
+export const MAX_TIMER_MS = 2_147_483_647;
+
+/** A sizing option as given, refused at construction unless it is an integer from `min` to `max`. */
+export function sizingOption(owner: string, name: string, value: number, min: number, max = Number.MAX_SAFE_INTEGER): number {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new RangeError(`${owner}: ${name} must be an integer from ${min} to ${max}, got ${value}.`);
+  }
+  return value;
+}