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

package/dist/shared/oauth-token-error.js

@@ -0,0 +1,47 @@
+/**
+ * The error codes a token endpoint may answer with, as RFC 6749 §5.2 and OIDC
+ * Core §3.1.2.6 define them. A finite list, on purpose: a code is taken from
+ * a refusing provider's body only when it is exactly one of these, so no other
+ * string a provider puts in that field (a secret, a secret with a suffix, free
+ * text) reaches a message, a verdict or a log.
+ *
+ * Shared, not a module's own: the OIDC configuration check reads a provider's
+ * refusal through it and the secrets vault a token endpoint's, and one list is
+ * the only way the two cannot disagree about which codes are standard. Each
+ * caller keeps its own sentence per code (what a tool owner should do differs
+ * from what a sign-in administrator should do); the set of codes is one.
+ */
+export const OAUTH_TOKEN_ERROR_CODES = Object.freeze([
+    'invalid_request',
+    'invalid_client',
+    'invalid_grant',
+    'unauthorized_client',
+    'unsupported_grant_type',
+    'invalid_scope',
+    'access_denied',
+    'server_error',
+    'temporarily_unavailable',
+]);
+/** Whether `code` is one of the standard token-endpoint error codes, and so safe to echo. */
+export function isStandardTokenErrorCode(code) {
+    return typeof code === 'string' && OAUTH_TOKEN_ERROR_CODES.includes(code);
+}
+/**
+ * The standard `error` code in a refusing token endpoint's JSON body, or null:
+ * when the body is not JSON, not an object, carries no string `error`, or
+ * carries one that is not a standard code.
+ */
+export function standardTokenErrorCode(bodyText) {
+    let json;
+    try {
+        json = JSON.parse(bodyText);
+    }
+    catch {
+        return null;
+    }
+    if (!json || typeof json !== 'object' || Array.isArray(json))
+        return null;
+    const { error } = json;
+    return isStandardTokenErrorCode(error) ? error : null;
+}
+//# sourceMappingURL=oauth-token-error.js.map

package/dist/shared/oauth-token-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-token-error.js","sourceRoot":"","sources":["../../src/shared/oauth-token-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACtE,iBAAiB;IACjB,gBAAgB;IAChB,eAAe;IACf,qBAAqB;IACrB,wBAAwB;IACxB,eAAe;IACf,eAAe;IACf,cAAc;IACd,yBAAyB;CAC1B,CAAC,CAAC;AAEH,6FAA6F;AAC7F,MAAM,UAAU,wBAAwB,CAAC,IAAa;IACpD,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,uBAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,MAAM,EAAE,KAAK,EAAE,GAAG,IAA+B,CAAC;IAClD,OAAO,wBAAwB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC"}

package/dist/shared/read-capped.d.ts

@@ -0,0 +1,19 @@
+/**
+ * At most `limit` bytes of a response body, decoded as text, the rest of the
+ * stream cancelled.
+ *
+ * Each CHUNK is sliced to the remaining budget before being decoded, not just
+ * counted against it: a provider that answers in one 5MB chunk would otherwise
+ * put the whole thing through the decoder before the loop noticed it was over,
+ * which is the bound bypassed by the very party it is meant to bound. Never a
+ * byte past the limit: once the budget is spent the read stops without asking
+ * for more, so a body of exactly `limit` bytes on a stream that stays open
+ * returns at once. And the read never falls back to `res.text()` on a live
+ * stream: a cap applied after that read bounds nothing.
+ *
+ * Shared, not a module's own: the connection probe reads a provider's
+ * rejection with it and the secrets vault a token endpoint's refusal, and one
+ * reader is the only way the two cannot disagree about what "bounded" means.
+ */
+export declare function readCapped(res: Response, limit: number): Promise<string>;
+//# sourceMappingURL=read-capped.d.ts.map

package/dist/shared/read-capped.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-capped.d.ts","sourceRoot":"","sources":["../../src/shared/read-capped.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB9E"}

package/dist/shared/read-capped.js

@@ -0,0 +1,45 @@
+/**
+ * At most `limit` bytes of a response body, decoded as text, the rest of the
+ * stream cancelled.
+ *
+ * Each CHUNK is sliced to the remaining budget before being decoded, not just
+ * counted against it: a provider that answers in one 5MB chunk would otherwise
+ * put the whole thing through the decoder before the loop noticed it was over,
+ * which is the bound bypassed by the very party it is meant to bound. Never a
+ * byte past the limit: once the budget is spent the read stops without asking
+ * for more, so a body of exactly `limit` bytes on a stream that stays open
+ * returns at once. And the read never falls back to `res.text()` on a live
+ * stream: a cap applied after that read bounds nothing.
+ *
+ * Shared, not a module's own: the connection probe reads a provider's
+ * rejection with it and the secrets vault a token endpoint's refusal, and one
+ * reader is the only way the two cannot disagree about what "bounded" means.
+ */
+export async function readCapped(res, limit) {
+    const reader = res.body?.getReader();
+    // No stream (a mocked or already-consumed response): fall back to the whole
+    // body, which for those cases is ours and small.
+    if (!reader)
+        return (await res.text()).slice(0, limit);
+    const decoder = new TextDecoder();
+    let out = '';
+    let read = 0;
+    try {
+        while (read < limit) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const remaining = limit - read;
+            const chunk = value.byteLength > remaining ? value.subarray(0, remaining) : value;
+            read += chunk.byteLength;
+            out += decoder.decode(chunk, { stream: true });
+            if (chunk.byteLength < value.byteLength)
+                break;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return out;
+}
+//# sourceMappingURL=read-capped.js.map

package/dist/shared/read-capped.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-capped.js","sourceRoot":"","sources":["../../src/shared/read-capped.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAa,EAAE,KAAa;IAC3D,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;IACrC,4EAA4E;IAC5E,iDAAiD;IACjD,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,KAAK,EAAE,CAAC;YACpB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,MAAM,SAAS,GAAG,KAAK,GAAG,IAAI,CAAC;YAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAClF,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC;YACzB,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/C,IAAI,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU;gBAAE,MAAM;QACjD,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.34.0",
-    "@bevel-software/platform-shared": "0.34.0"
+    "@bevel-software/platform-mcp-core": "0.35.0",
+    "@bevel-software/platform-shared": "0.35.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",
@@ -68,6 +68,7 @@
     "@types/pg": "^8.20.0",
     "@types/qs": "^6.15.1",
     "drizzle-kit": "^0.31.10",
+    "js-tiktoken": "^1.0.21",
     "tsx": "^4.19.0",
     "typescript": "^5.8.0",
     "vitest": "^3.2.6"

package/src/__tests__/hexis-catalog.ts

@@ -0,0 +1,144 @@
+import express from 'express';
+import { codeModeMetaTools } from '@bevel-software/platform-mcp-core';
+import { testKbContext } from './kb-context.js';
+import { EXTERNAL_KB_MANUAL_NAME, registerToolManualsTools } from '../modules/tool-manuals/index.js';
+import { ToolRegistry, guideFirstDescription, type UtcpTool } from '../modules/tool-registry/index.js';
+import type { ToolAuth } from '../modules/tool-auth/index.js';
+import { RipgrepPatternMatcher, ToolDescriptionNotes } from '../modules/workspace/index.js';
+import { registerPluginsTools } from '../modules/plugins/index.js';
+import { registerSkillsTools } from '../modules/skills/index.js';
+import { agentGuideSections, registerAgentGuideTool } from '../modules/agent-guide/index.js';
+import {
+  RoutineWritePolicyService,
+  UuidSessionSink,
+  WorkflowHooks,
+  createToolHandlerFactory,
+  registerChangeRequestReadTools,
+  registerEmbedTools,
+  registerWorkflowTools,
+  registerWorkspaceTools,
+} from './tool-wiring.js';
+
+/**
+ * The tool catalog Hexis itself registers, built on stand-ins for the tests
+ * that read what an agent is TOLD: the description caps, the guide checks and
+ * the guide's budgets. Every registrar Hexis owns is mounted, because the
+ * definitions are the only thing under test: a stand-in that is never called
+ * is honest about that. Tools PROXIED from connected MCP servers are not here:
+ * their text is the other server's.
+ */
+
+/** Dependencies the registrars take but never touch while they are only building defs. */
+export const unused = <T,>(): T => ({}) as T;
+
+/** A `.tool` catalog with nothing in it: the shortest honest answer for a listing. */
+const emptyManuals = {
+  listLocalOnly: async () => [],
+  listAll: async () => [],
+  list: async () => [],
+  listInvalid: async () => [],
+} as unknown as Parameters<typeof registerToolManualsTools>[4];
+
+/** A skill catalog with nothing in it — the per-user skill line is then one fixed sentence. */
+export const emptySkills = { listSkills: async () => [] } as unknown as Parameters<typeof registerSkillsTools>[4];
+
+/**
+ * The meta-tools as the hosted endpoint builds them (`mcp.service.ts`):
+ * examples written against the namespace it registers the knowledge-base tools
+ * under and against the catalog it serves, and the chain without the rules it
+ * states only in the shared places. So the chain description measured here
+ * carries the worked call a client is really sent, which is its longest form.
+ */
+export function servedMetaTools(external: readonly UtcpTool[]) {
+  return codeModeMetaTools(
+    EXTERNAL_KB_MANUAL_NAME,
+    external.map((t) => ({ utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`, inputSchema: t.inputs })),
+    { sharedRulesPointer: '' },
+    // As the hosted endpoint serves them: opening with the guide-first
+    // sentence, through the one helper the endpoint itself uses.
+  ).map((t) => ({ ...t, description: guideFirstDescription(t.description) }));
+}
+
+/**
+ * Every tool Hexis itself registers, by surface: what the in-process agent is
+ * handed, what the hosted endpoint lists to an MCP client, and the three
+ * meta-tools it lists beside them.
+ */
+export async function hexisCatalog(
+  skills: Parameters<typeof registerSkillsTools>[4] = emptySkills,
+): Promise<{ internal: UtcpTool[]; external: UtcpTool[]; metaTools: ReturnType<typeof servedMetaTools> }> {
+  const registry = new ToolRegistry();
+  const router = express.Router();
+  const toolAuth = ((_req, _res, next) => next()) as unknown as ToolAuth;
+  const toolHandler = createToolHandlerFactory(unused());
+  const kb = testKbContext();
+  const gate = { recoveryBotEmail: 'bot@x', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() };
+
+  // The change-request readers come first, as the root mounts them: they
+  // gate their whole payload on the caller's read access and take the access
+  // service and nothing else.
+  registerChangeRequestReadTools(registry, router, toolAuth, toolHandler, unused(), kb);
+  const workspaceTools = registerWorkspaceTools(
+    registry,
+    router,
+    toolAuth,
+    toolHandler,
+    unused(),
+    unused(),
+    unused(),
+    kb,
+    gate,
+    new RoutineWritePolicyService(),
+    new UuidSessionSink(),
+    undefined,
+    undefined,
+    // The two upload tools are mounted only when a store is supplied, and
+    // every real composition supplies one: without it they would be the two
+    // descriptions this suite never measured.
+    unused(),
+    // The guide reader, not needed to build defs; then the download store,
+    // mounted on the same terms as the upload one.
+    undefined,
+    unused(),
+    // Starter packs and the tree walk, not needed; then the grep matcher,
+    // mounted on the same terms (it spawns no worker until a search runs).
+    undefined,
+    undefined,
+    new RipgrepPatternMatcher(),
+  );
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
+  registerPluginsTools(registry, kb);
+  registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
+  registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
+    accessControl: unused(),
+    variableStatus: unused(),
+    kb,
+  });
+  // `open_page`, on the file tools' router with `read_file`'s own read, as the
+  // root mounts it; its stand-ins answer nothing, since only its def is read.
+  registerEmbedTools(registry, router, toolAuth, toolHandler, {
+    embedService: unused(),
+    kb,
+    readForTool: workspaceTools.readForTool,
+    canBeReached: () => true,
+    appUrlFor: () => '',
+    notes: gate.notes,
+  });
+  // The guide's own tool, with the platform's sections: the one description
+  // that lists the sections is measured with the list it really carries.
+  registerAgentGuideTool(registry, router, toolAuth, toolHandler, () => agentGuideSections(kb.layout));
+
+  // The meta-tools as a client is served them (`mcp.service.ts` opens each
+  // with the guide-first sentence at the mount), so the catalog measured here
+  // is the catalog that goes out rather than the bare constant.
+  const external = (await registry.listExternal()) as UtcpTool[];
+  return { internal: (await registry.listInternal()) as UtcpTool[], external, metaTools: servedMetaTools(external) };
+}
+
+/** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
+export async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = emptySkills): Promise<UtcpTool[]> {
+  const { internal, external, metaTools } = await hexisCatalog(skills);
+  const byName = new Map<string, UtcpTool>();
+  for (const tool of [...internal, ...external, ...metaTools]) byName.set(tool.name, tool as UtcpTool);
+  return [...byName.values()];
+}

package/src/__tests__/real-disk.ts

@@ -0,0 +1,21 @@
+import { NodeFs } from '../modules/kb-fs/node-fs.js';
+import { KbPluginSource } from '../modules/plugins/index.js';
+import type { KbContext } from '../shared/kb-context.js';
+
+/**
+ * The real disk, and the plugin source that reads it, wired the way the
+ * composition root wires them (`core/create-core-services.ts`: one `NodeFs`,
+ * one `KbPluginSource` over it). A module's suite that drives its service over
+ * real files takes them from HERE rather than constructing another module's
+ * implementation itself: the root is the one place that knows those files
+ * (`NodeFs` is on no module entry, by design — a filesystem arrives by
+ * injection), and this fixture stands in for the root, as `kb-context.ts`
+ * does for the knowledge-base context.
+ */
+export function realDisk(): NodeFs {
+  return new NodeFs();
+}
+
+export function realPluginSource(disk: NodeFs, kb: KbContext): KbPluginSource {
+  return new KbPluginSource(disk, kb);
+}

package/src/__tests__/tokens.ts

@@ -0,0 +1,19 @@
+import { Tiktoken } from 'js-tiktoken/lite';
+import o200kBase from 'js-tiktoken/ranks/o200k_base';
+import { GUIDE_TOKEN_ENCODING } from '../modules/agent-guide/index.js';
+
+/**
+ * Token counts for the tests that hold agent-facing text to a budget
+ * (`modules/agent-guide/guide-budget.ts`): a real BPE tokenizer, offline and
+ * deterministic, so a count in CI is the count on a laptop. Built once: the
+ * rank table is large and the counts never change between calls.
+ */
+const encoder = new Tiktoken(o200kBase);
+
+if (GUIDE_TOKEN_ENCODING !== 'o200k_base') {
+  throw new Error(`The budgets name ${GUIDE_TOKEN_ENCODING}, but the counter is built on o200k_base.`);
+}
+
+export function countTokens(text: string): number {
+  return encoder.encode(text).length;
+}

package/src/__tests__/tool-manuals.ts

@@ -0,0 +1,32 @@
+import { ToolManualService, type McpAuthDiscoveryPort } from '../modules/tool-manuals/tool-manuals.service.js';
+import type { IAccessControl } from '../modules/access/index.js';
+import type { WorkspaceService } from '../modules/workspace/index.js';
+import type { KbContext } from '../shared/kb-context.js';
+import { realDisk, realPluginSource } from './real-disk.js';
+
+export type { McpAuthDiscoveryPort };
+
+/**
+ * The tool-manual service over real files, wired the way the composition root
+ * wires it (`core/create-core-services.ts`): the real disk, the plugin source
+ * reading that same disk, and the discovery port set afterwards. A suite that
+ * drives the service over real tool files takes it from HERE and never
+ * constructs the class from its file — the class is on no module entry (a
+ * service arrives by injection), and this fixture stands in for the root, as
+ * `kb-context.ts` and `real-disk.ts` do for what they wire.
+ */
+export function realToolManualService(
+  deps: {
+    workspaceService: WorkspaceService;
+    accessControl: IAccessControl;
+    kb: KbContext;
+    /** The disk the suite writes its files to; the service reads the same one. */
+    disk?: ReturnType<typeof realDisk>;
+  },
+  discovery?: McpAuthDiscoveryPort,
+): ToolManualService {
+  const disk = deps.disk ?? realDisk();
+  const svc = new ToolManualService(deps.workspaceService, deps.accessControl, deps.kb, disk, realPluginSource(disk, deps.kb));
+  if (discovery) svc.setMcpAuthDiscovery(discovery);
+  return svc;
+}

package/src/__tests__/tool-wiring.ts

@@ -0,0 +1,25 @@
+/**
+ * The pieces the composition root wires from module internals, for a suite
+ * that builds a tool surface the way `core/create-core-server.ts` does: the
+ * handler factory and context resolver, the tool-auth middleware, the two
+ * registrars that take their dependencies by hand, the session sink, the
+ * routine write policy, the access resolver and the workflow hooks.
+ *
+ * A module's entry holds its contracts, and a suite asserts through entries.
+ * These are not contracts: they are what the root composes, so a suite that
+ * needs them reaches them here, the one root fixture that imports past the
+ * entries, as the root itself does. A suite that imports one of these files
+ * directly is a second wiring that drifts from the root's.
+ */
+export { createToolHandlerFactory } from '../modules/tool-helpers/tool-handler.js';
+export { createToolContextResolver } from '../modules/tool-helpers/tool-context.js';
+export { createToolAuthMiddleware } from '../modules/tool-auth/tool-auth.middleware.js';
+export { InternalTokenService } from '../modules/tool-auth/internal-token.service.js';
+export { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
+export { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.tools.js';
+export { registerChangeRequestReadTools } from '../modules/workflow/agent-tools/change-request-read.tools.js';
+export { registerEmbedTools } from '../modules/embed/embed.tools.js';
+export { UuidSessionSink } from '../modules/workspace/session-sink.js';
+export { RoutineWritePolicyService } from '../modules/workspace/routine-write-policy.js';
+export { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
+export { WorkflowHooks, type AgentOperationContext } from '../modules/workflow/workflow-hooks.js';

package/src/core/__tests__/oauth-sign-in-real-file.test.ts

@@ -0,0 +1,179 @@
+import type { Server as HttpServer } from 'node:http';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { createSecretsVaultRoutes } from '../../modules/secrets-vault/index.js';
+import { KbPluginSource } from '../../modules/plugins/index.js';
+import type { WorkspaceService } from '../../modules/workspace/index.js';
+import type { IAccessControl } from '../../modules/access/index.js';
+// The two concrete services this suite wires, it wires the way the composition
+// root does (`create-core-services.ts`): their modules publish them as types
+// only, and the composition root is the one place that constructs them from
+// their files. This suite stands in for that root — the routes of one module
+// over the real parser of another — which is why it lives beside it.
+import { ToolManualService } from '../../modules/tool-manuals/tool-manuals.service.js';
+import { realDisk } from '../../__tests__/real-disk.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { testKbContext } from '../../__tests__/kb-context.js';
+
+/**
+ * The sign-in start against REAL tool files: the routes are wired to the real
+ * `ToolManualService` over a workspace on disk, so what the start answers is
+ * what the parser makes of the file, not what a stub says it makes of it.
+ *
+ * The case this exists for (Local Testing, 2026-10-27): a declaration edited to
+ * `tokenUrl: http://127.0.0.1/token` is refused by the parser before the vault
+ * ever validates it — and the start answered "Tool or variable not found"
+ * instead of the validation's message.
+ */
+
+const KB_DIR = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+const USER = 'owner@x.com';
+const AUTHORIZE = 'https://auth.crm.example/authorize';
+const TOKEN = 'https://auth.crm.example/token';
+
+let root: string;
+let httpServer: HttpServer | undefined;
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'signin-live-'));
+  await mkdir(join(root, wsId, KB_DIR, 'Plugins', 'GTM'), { recursive: true });
+});
+afterEach(async () => {
+  await new Promise<void>((r) => (httpServer ? httpServer.close(() => r()) : r()));
+  httpServer = undefined;
+  await rm(root, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+const toolPath = () => join(root, wsId, KB_DIR, 'Plugins', 'crm.tool');
+const writeTool = (oauth: Record<string, unknown>) =>
+  writeFile(
+    toolPath(),
+    JSON.stringify({
+      name: 'crm',
+      type: 'http',
+      url: 'https://api.crm.example/openapi.json',
+      variables: [{ name: 'SIGNIN', scope: 'user', oauth }],
+    }),
+  );
+const writePlugin = (oauth: Record<string, unknown>) =>
+  Promise.all([
+    writeFile(
+      join(root, wsId, KB_DIR, 'Plugins', 'GTM', 'mcp.json'),
+      JSON.stringify({ mcpServers: { hubspot: { type: 'streamable-http', url: 'https://mcp.hubspot.example/mcp' } } }),
+    ),
+    writeFile(
+      join(root, wsId, KB_DIR, 'Plugins', 'GTM', 'plugin.json'),
+      JSON.stringify({
+        name: 'gtm',
+        extensions: {
+          'software.bevel.hexis': {
+            mcpServers: {
+              hubspot: {
+                headers: { Authorization: 'Bearer ${HUBSPOT_TOKEN}' },
+                variables: [{ name: 'HUBSPOT_TOKEN', scope: 'user', oauth }],
+              },
+            },
+          },
+        },
+      }),
+    ),
+  ]);
+
+async function serve() {
+  const disk = realDisk();
+  const kb = testKbContext({ kbDirName: KB_DIR });
+  const accessControl = {
+    canRead: async () => true,
+    canWrite: async () => true,
+    canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+  } as unknown as IAccessControl;
+  const workspaceService = {
+    getOrCreateForBranch: async () => ({ id: wsId }),
+    getWorkspacePath: async (id: string) => join(root, id),
+  } as unknown as WorkspaceService;
+  const toolManualService = new ToolManualService(workspaceService, accessControl, kb, disk, new KbPluginSource(disk, kb));
+  toolManualService.setMcpAuthDiscovery({ statusFor: async () => ({ status: 'open' as const }) });
+  const beginToolOAuthByKey = vi.fn(async () => ({ id: 'row-1', url: `${AUTHORIZE}?client_id=x` }));
+  const deps = {
+    secretsVault: { beginToolOAuthByKey },
+    toolManualService,
+    accessControl,
+    connectionProbe: {},
+    kb: { defaultWorkspaceId: () => wsId },
+    stateSecret: 'state-secret',
+    publicBackendUrl: 'http://localhost:3000',
+    publicFrontendUrl: 'http://localhost:5173',
+  } as unknown as Parameters<typeof createSecretsVaultRoutes>[0];
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userId = 'user-1';
+    req.userEmail = USER;
+    next();
+  });
+  app.use('/api', createSecretsVaultRoutes(deps));
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const base = `http://127.0.0.1:${(httpServer.address() as { port: number }).port}/api/secrets/tools`;
+  const start = (slug: string, varName: string) => fetch(`${base}/${slug}/vars/${varName}/oauth/start`, { method: 'POST' });
+  return { toolManualService, beginToolOAuthByKey, start };
+}
+
+describe('POST …/oauth/start — through a real tool file', () => {
+  it('a client id edited in the .tool after the catalog was scanned is the one handed to the vault', async () => {
+    await writeTool({ clientId: 'client-A', authorizationUrl: AUTHORIZE, tokenUrl: TOKEN });
+    const s = await serve();
+    await s.toolManualService.listAccessible(USER); // the catalog caches client A
+    await writeTool({ clientId: 'client-B', authorizationUrl: AUTHORIZE, tokenUrl: TOKEN });
+
+    expect((await s.start('crm', 'SIGNIN')).status).toBe(200);
+    expect(s.beginToolOAuthByKey.mock.calls[0][0]).toMatchObject({
+      key: 'crm_SIGNIN',
+      provider: { clientId: 'client-B', authorizationUrl: AUTHORIZE, tokenUrl: TOKEN, pkce: true },
+    });
+  });
+
+  it.each([
+    ['an http:// token endpoint', 'http://127.0.0.1/token', '`variables[0].oauth.tokenUrl` must use https'],
+    ['a private token endpoint', 'https://10.0.0.5/token', '`variables[0].oauth.tokenUrl` host is not allowed'],
+  ])('a .tool naming %s is refused with the validation message, sending nothing', async (_n, tokenUrl, message) => {
+    await writeTool({ clientId: 'client-A', authorizationUrl: AUTHORIZE, tokenUrl: TOKEN });
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const s = await serve();
+    await s.toolManualService.listAccessible(USER); // the catalog still holds the valid version
+    await writeTool({ clientId: 'client-A', authorizationUrl: AUTHORIZE, tokenUrl });
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+    const res = await s.start('crm', 'SIGNIN');
+    expect(res.status).toBe(422);
+    expect(((await res.json()) as { error: string }).error).toBe(message);
+    expect(s.beginToolOAuthByKey).not.toHaveBeenCalled();
+    // The one fetch is the test's own call to the route: nothing went to a provider.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('a plugin.json sign-in naming an http:// token endpoint is refused with the validation message, sending nothing', async () => {
+    await writePlugin({ clientId: 'owner-app', authorizationUrl: AUTHORIZE, tokenUrl: 'http://127.0.0.1/token' });
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const s = await serve();
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+    const res = await s.start('hubspot', 'HUBSPOT_TOKEN');
+    expect(res.status).toBe(422);
+    expect(((await res.json()) as { error: string }).error).toContain('`variables[0].oauth.tokenUrl` must use https');
+    expect(s.beginToolOAuthByKey).not.toHaveBeenCalled();
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('a slug no file declares is still not found', async () => {
+    const s = await serve();
+    expect((await s.start('nothing', 'SIGNIN')).status).toBe(404);
+  });
+});

package/src/core/create-core-server.ts

@@ -487,7 +487,7 @@ export async function createCoreServer(
   // because they are the only ones that gate their whole payload on the
   // caller's read access, so they take the access service and nothing else.
   registerChangeRequestReadTools(core.toolRegistry, toolsRouter, ta, th, core.accessControl, core.kb);
-  const workspaceTools = registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuide, core.agentDownloadStore, core.starterPackService, core.disk, core.patternMatcher);
+  const workspaceTools = registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuideStart, core.agentDownloadStore, core.starterPackService, core.disk, core.patternMatcher);
   // `open_page` — the knowledge-base page shown inside a chat. Registered
   // here, on the same router as the file tools, because it answers with
   // `read_file`'s own read: the read hook, the access gate and the

package/src/core/create-core-services.ts

@@ -171,6 +171,7 @@ import { AgentAuditService, retentionDaysFrom } from '../modules/audit/agent-aud
 import { readAgentPreamble, type AgentPreambleReader } from '../modules/agent-instructions/index.js';
 import {
   agentGuideSections,
+  guideStartText,
   joinGuideSections,
   type AgentGuideReader,
   type AgentGuideSectionsReader,
@@ -296,6 +297,12 @@ export interface CoreServices {
    * `read_file` of the guide's name answer. See modules/agent-guide.
    */
   agentGuide: AgentGuideReader;
+  /**
+   * The start of that guide and the list of its sections: what a `read_file`
+   * of the guide's name answers, the same as `get_agent_guide` with no
+   * `section`. See `guideStartText`.
+   */
+  agentGuideStart: AgentGuideReader;
   /** The same guide as its sections, each with its title — what `get_agent_guide` lists and serves one of. */
   agentGuideSections: AgentGuideSectionsReader;
   mcpServerEditService: McpServerEditService;
@@ -1376,11 +1383,13 @@ export async function createCoreServices(
   // serves the same composition to the local bridge and the frontend card.
   const readPreamble: AgentPreambleReader = () => readAgentPreamble(workspaceService, kb, disk);
   // The guide every agent is told to read first, composed when asked for —
-  // the layout is read per call, so a name the setup save applies lands
-  // without a restart, and the distribution's hook sees every composition.
+  // the layout and the default branch are read per call, so a name the setup
+  // save applies lands without a restart, and the distribution's hook sees
+  // every composition.
   const agentGuideSectionsReader: AgentGuideSectionsReader = () =>
-    agentGuideSections(kb.layout, ports.agentGuide, { kbDirName });
+    agentGuideSections(kb.layout, ports.agentGuide, { kbDirName, defaultBranch: kb.defaultBranch });
   const agentGuide: AgentGuideReader = async () => joinGuideSections(await agentGuideSectionsReader());
+  const agentGuideStart: AgentGuideReader = async () => guideStartText(await agentGuideSectionsReader());
   // The Audit log. Records through the proxy below (every call an external
   // agent makes), reads keys through the key service so their shape is
   // defined once, and prunes past the retention setting — read per sweep, so
@@ -1723,6 +1732,7 @@ export async function createCoreServices(
     pendingToolsService,
     readAgentPreamble: readPreamble,
     agentGuide,
+    agentGuideStart,
     agentGuideSections: agentGuideSectionsReader,
     pluginIndexService,
     pluginProvisionService,