@bevel-software/platform-core-backend 0.1.0

package/dist/modules/tool-auth/tool-auth.middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-auth.middleware.js","sourceRoot":"","sources":["../../../src/modules/tool-auth/tool-auth.middleware.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-helpers/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The tool-author SDK — everything needed to build a tool, in ONE import.
+ * Internal tools use it today; it is the surface a third-party marketplace
+ * plugin will code against (eventually shipped as a standalone `@bevel-software/tool-sdk`
+ * package). A tool author never needs the registry internals, the Express
+ * middleware, or the internal-token service — only what is re-exported here.
+ *
+ *   import { validateToken, toolDef, ToolError } from '<tool-sdk>';
+ *
+ *   // in your endpoint:
+ *   const ctx = await validateToken(bearerToken, body);   // verify + resolve, throws ToolError
+ *   const fs = await ctx.getFilesystem();                  // lock-aware (write) / read-only (read)
+ *   const def = toolDef({ name, description, inputs, path }); // self-describing UTCP Tool to register
+ */
+export { createToolValidator, type ValidateToken, type ToolValidatorDeps } from './validate-token.js';
+export { toolDef, type ToolDefSpec } from './tool-def.js';
+export { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from './tool.contract.js';
+export type { JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/tool-helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAClG,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/modules/tool-helpers/index.js

@@ -0,0 +1,18 @@
+/**
+ * The tool-author SDK — everything needed to build a tool, in ONE import.
+ * Internal tools use it today; it is the surface a third-party marketplace
+ * plugin will code against (eventually shipped as a standalone `@bevel-software/tool-sdk`
+ * package). A tool author never needs the registry internals, the Express
+ * middleware, or the internal-token service — only what is re-exported here.
+ *
+ *   import { validateToken, toolDef, ToolError } from '<tool-sdk>';
+ *
+ *   // in your endpoint:
+ *   const ctx = await validateToken(bearerToken, body);   // verify + resolve, throws ToolError
+ *   const fs = await ctx.getFilesystem();                  // lock-aware (write) / read-only (read)
+ *   const def = toolDef({ name, description, inputs, path }); // self-describing UTCP Tool to register
+ */
+export { createToolValidator } from './validate-token.js';
+export { toolDef } from './tool-def.js';
+export { ToolError, hasHttpStatus } from './tool.contract.js';
+//# sourceMappingURL=index.js.map

package/dist/modules/tool-helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,mBAAmB,EAA8C,MAAM,qBAAqB,CAAC;AACtG,OAAO,EAAE,OAAO,EAAoB,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,aAAa,EAAsC,MAAM,oBAAoB,CAAC"}

package/dist/modules/tool-helpers/tool-context.d.ts

@@ -0,0 +1,35 @@
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { ICreatorAccess } from '../access/creator-access.js';
+import { type WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { AuthService } from '../auth/auth.service.js';
+import { type ToolContext } from './tool.contract.js';
+import type { ToolAuth } from '../tool-auth/tool-auth.middleware.js';
+export interface ToolContextDeps {
+    authService: AuthService;
+    workspaceService: WorkspaceService;
+    workflowService: IWorkflowService;
+    events: WorkflowEventBus;
+    /** KB dir name — used to recognise (and validate) writes to `roles.yaml`. */
+    kbDirName: string;
+    /**
+     * Creator read-grant planner, threaded into the LockingFilesystem so agent
+     * creations in unreadable spots stay visible to the driving user (see
+     * `modules/access/creator-access`).
+     */
+    creatorAccess: ICreatorAccess;
+}
+export type ResolveToolContext = (auth: ToolAuth, abortSignal: AbortSignal, sessionId?: string) => Promise<ToolContext>;
+/**
+ * Build the per-call `ToolContext` from a verified `ToolAuth`. Identity (user,
+ * scope, source) is resolved up front; the WORKSPACE is resolved on demand by
+ * `getFilesystem(branch)` and cached per branch. Internal and external callers
+ * are identical — the credential is identity-only, so the workspace always comes
+ * from the `branch` the tool passes (`getOrCreateForUser` clones the per-branch
+ * workspace if needed). A tool that never touches the KB never calls
+ * `getFilesystem`, so it resolves no workspace. Writes through the
+ * LockingFilesystem auto-commit+push as `user`. Framework-agnostic — never reads
+ * a request body; `branch` arrives as an explicit argument from the tool.
+ */
+export declare function createToolContextResolver(deps: ToolContextDeps): ResolveToolContext;
+//# sourceMappingURL=tool-context.d.ts.map

package/dist/modules/tool-helpers/tool-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAIxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAChG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,eAAe,EAAE,gBAAgB,CAAC;IAClC,MAAM,EAAE,gBAAgB,CAAC;IACzB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,EAAE,cAAc,CAAC;CAC/B;AAED,MAAM,MAAM,kBAAkB,GAAG,CAC/B,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,WAAW,EACxB,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,WAAW,CAAC,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,eAAe,GAAG,kBAAkB,CAqDnF"}

package/dist/modules/tool-helpers/tool-context.js

@@ -0,0 +1,66 @@
+import { LockingFilesystem } from '../workflow/locking-filesystem.js';
+import { ReadOnlyFilesystem } from '../workflow/read-only-filesystem.js';
+import { makeRolesYamlWriteValidator } from '../access/roles-yaml-guard.js';
+import { branchForWorkspaceId } from '../workspace/workspace.service.js';
+import { ToolError } from './tool.contract.js';
+/**
+ * Build the per-call `ToolContext` from a verified `ToolAuth`. Identity (user,
+ * scope, source) is resolved up front; the WORKSPACE is resolved on demand by
+ * `getFilesystem(branch)` and cached per branch. Internal and external callers
+ * are identical — the credential is identity-only, so the workspace always comes
+ * from the `branch` the tool passes (`getOrCreateForUser` clones the per-branch
+ * workspace if needed). A tool that never touches the KB never calls
+ * `getFilesystem`, so it resolves no workspace. Writes through the
+ * LockingFilesystem auto-commit+push as `user`. Framework-agnostic — never reads
+ * a request body; `branch` arrives as an explicit argument from the tool.
+ */
+export function createToolContextResolver(deps) {
+    // Reject an agent write that would leave roles.yaml unparseable (app-wide
+    // admin lockout) before it reaches disk — the agent gets a tool error and the
+    // file is untouched, mirroring the human editor's save-time gate.
+    const validateRolesWrite = makeRolesYamlWriteValidator(deps.kbDirName);
+    return async function resolveToolContext(auth, abortSignal, sessionId) {
+        const user = await deps.authService.getUserById(auth.userId);
+        if (!user)
+            throw new ToolError('Your account is no longer available.', 401);
+        const fsCache = new Map();
+        const getFilesystem = async (branch) => {
+            const cached = fsCache.get(branch);
+            if (cached)
+                return cached;
+            const ws = await deps.workspaceService.getOrCreateForUser(user, branch);
+            const workspaceId = ws.id;
+            const basePath = await deps.workspaceService.getWorkspacePath(workspaceId);
+            const fs = auth.scope === 'write'
+                ? new LockingFilesystem({ basePath, contained: true }, {
+                    workflow: deps.workflowService,
+                    workspaceId,
+                    branch: branchForWorkspaceId(workspaceId),
+                    user,
+                    validateWrite: validateRolesWrite,
+                    creatorAccess: deps.creatorAccess,
+                })
+                : new ReadOnlyFilesystem({ basePath, contained: true });
+            fsCache.set(branch, fs);
+            return fs;
+        };
+        return {
+            user,
+            scope: auth.scope,
+            source: auth.source,
+            tokenId: auth.tokenId,
+            // For `internal` callers the signed token claim is the ONLY trustworthy
+            // session: honoring a body value would let one per-run token switch to a
+            // fresh `sessionId` and shed its accumulated touched-set. The body path is
+            // only for `external`/`session` callers, whose token carries no claim and
+            // whose `sessionId` is injected by the MCP proxy's continuity convention.
+            sessionId: auth.source === 'internal' ? auth.sessionId : sessionId ?? auth.sessionId,
+            abortSignal,
+            workspaceService: deps.workspaceService,
+            workflowService: deps.workflowService,
+            events: deps.events,
+            getFilesystem,
+        };
+    };
+}
+//# sourceMappingURL=tool-context.js.map

package/dist/modules/tool-helpers/tool-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-context.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,OAAO,EAAE,oBAAoB,EAAyB,MAAM,mCAAmC,CAAC;AAGhG,OAAO,EAAE,SAAS,EAAoB,MAAM,oBAAoB,CAAC;AAwBjE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAqB;IAC7D,0EAA0E;IAC1E,8EAA8E;IAC9E,kEAAkE;IAClE,MAAM,kBAAkB,GAAG,2BAA2B,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEvE,OAAO,KAAK,UAAU,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS;QACnE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,SAAS,CAAC,sCAAsC,EAAE,GAAG,CAAC,CAAC;QAE5E,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;QACnD,MAAM,aAAa,GAAG,KAAK,EAAE,MAAc,EAA4B,EAAE;YACvE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACnC,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;YAC1B,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACxE,MAAM,WAAW,GAAG,EAAE,CAAC,EAAE,CAAC;YAC1B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;YAC3E,MAAM,EAAE,GACN,IAAI,CAAC,KAAK,KAAK,OAAO;gBACpB,CAAC,CAAC,IAAI,iBAAiB,CACnB,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,EAC7B;oBACE,QAAQ,EAAE,IAAI,CAAC,eAAe;oBAC9B,WAAW;oBACX,MAAM,EAAE,oBAAoB,CAAC,WAAW,CAAC;oBACzC,IAAI;oBACJ,aAAa,EAAE,kBAAkB;oBACjC,aAAa,EAAE,IAAI,CAAC,aAAa;iBAClC,CACF;gBACH,CAAC,CAAC,IAAI,kBAAkB,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACxB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QAEF,OAAO;YACL,IAAI;YACJ,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,wEAAwE;YACxE,yEAAyE;YACzE,2EAA2E;YAC3E,0EAA0E;YAC1E,0EAA0E;YAC1E,SAAS,EAAE,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS;YACpF,WAAW;YACX,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,aAAa;SACd,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/modules/tool-helpers/tool-def.d.ts

@@ -0,0 +1,33 @@
+import '@utcp/http';
+import type { JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
+/**
+ * The required `branch` input every KB tool declares — the model names the
+ * workspace (draft) the call acts on. Since the credential is identity-only
+ * (internal token == connection key), the workspace is never implied; it always
+ * comes from this argument.
+ */
+export declare const BRANCH_INPUT: JsonSchema;
+/** Add a required `branch` property to an object input schema (KB tools). */
+export declare function withBranchInput(inputs: JsonSchema): JsonSchema;
+export interface ToolDefSpec {
+    /** Unique within its surface; also the namespace member the agent calls (`Bevel.<name>`). */
+    name: string;
+    description: string;
+    /** The LOGICAL (flat) input schema — what the handler receives and the agent passes. */
+    inputs: JsonSchema;
+    outputs?: JsonSchema;
+    tags?: string[];
+    /** The route the owning module hosts, e.g. `/agent/tools/list_branches`. */
+    path: string;
+}
+/**
+ * Build a self-describing UTCP `Tool` def for a module-hosted endpoint. The flat
+ * `inputs` are wrapped under a single `body` property (`body_field: 'body'`) —
+ * the only standard-http way to ride multiple fields in the JSON body — so the
+ * agent calls `Bevel.<name>({ body: { ... } })` and the endpoint reads `req.body`
+ * as the flat args. The URL + bearer are `${API_URL}` / `${CONNECTION_KEY}`
+ * placeholders the consumer resolves (public URL + key for external; loopback +
+ * internal token for our agent), so one def serves both surfaces.
+ */
+export declare function toolDef(spec: ToolDefSpec): UtcpTool;
+//# sourceMappingURL=tool-def.d.ts.map

package/dist/modules/tool-helpers/tool-def.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-def.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-def.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAK9E;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,UAI1B,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAO9D;AAED,MAAM,WAAW,WAAW;IAC1B,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,CAqBnD"}

package/dist/modules/tool-helpers/tool-def.js

@@ -0,0 +1,57 @@
+import '@utcp/http';
+import { HttpCallTemplateSerializer } from '@utcp/http';
+import { ToolSerializer } from '@utcp/sdk';
+const httpTemplate = new HttpCallTemplateSerializer();
+const toolSerializer = new ToolSerializer();
+/**
+ * The required `branch` input every KB tool declares — the model names the
+ * workspace (draft) the call acts on. Since the credential is identity-only
+ * (internal token == connection key), the workspace is never implied; it always
+ * comes from this argument.
+ */
+export const BRANCH_INPUT = {
+    type: 'string',
+    minLength: 1,
+    description: 'The branch (draft) whose workspace this operates on — pass the branch you are currently working on.',
+};
+/** Add a required `branch` property to an object input schema (KB tools). */
+export function withBranchInput(inputs) {
+    const o = inputs;
+    return {
+        ...inputs,
+        properties: { ...(o.properties ?? {}), branch: BRANCH_INPUT },
+        required: [...new Set([...(o.required ?? []), 'branch'])],
+    };
+}
+/**
+ * Build a self-describing UTCP `Tool` def for a module-hosted endpoint. The flat
+ * `inputs` are wrapped under a single `body` property (`body_field: 'body'`) —
+ * the only standard-http way to ride multiple fields in the JSON body — so the
+ * agent calls `Bevel.<name>({ body: { ... } })` and the endpoint reads `req.body`
+ * as the flat args. The URL + bearer are `${API_URL}` / `${CONNECTION_KEY}`
+ * placeholders the consumer resolves (public URL + key for external; loopback +
+ * internal token for our agent), so one def serves both surfaces.
+ */
+export function toolDef(spec) {
+    return toolSerializer.validateDict({
+        name: spec.name,
+        description: spec.description,
+        inputs: {
+            type: 'object',
+            properties: { body: spec.inputs },
+            required: ['body'],
+            additionalProperties: false,
+        },
+        outputs: spec.outputs ?? { type: 'object', properties: {} },
+        tags: spec.tags ?? [],
+        tool_call_template: httpTemplate.validateDict({
+            call_template_type: 'http',
+            http_method: 'POST',
+            url: `\${API_URL}${spec.path}`,
+            content_type: 'application/json',
+            headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+            body_field: 'body',
+        }),
+    });
+}
+//# sourceMappingURL=tool-def.js.map

package/dist/modules/tool-helpers/tool-def.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-def.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-def.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AACpB,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,MAAM,YAAY,GAAG,IAAI,0BAA0B,EAAE,CAAC;AACtD,MAAM,cAAc,GAAG,IAAI,cAAc,EAAE,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAe;IACtC,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,qGAAqG;CACnH,CAAC;AAEF,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,MAAkB;IAChD,MAAM,CAAC,GAAG,MAA0E,CAAC;IACrF,OAAO;QACL,GAAG,MAAM;QACT,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE;QAC7D,QAAQ,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;KAC5C,CAAC;AAClB,CAAC;AAcD;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,OAAO,cAAc,CAAC,YAAY,CAAC;QACjC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE;YACjC,QAAQ,EAAE,CAAC,MAAM,CAAC;YAClB,oBAAoB,EAAE,KAAK;SAC5B;QACD,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QAC3D,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,kBAAkB,EAAE,YAAY,CAAC,YAAY,CAAC;YAC5C,kBAAkB,EAAE,MAAM;YAC1B,WAAW,EAAE,MAAM;YACnB,GAAG,EAAE,cAAc,IAAI,CAAC,IAAI,EAAE;YAC9B,YAAY,EAAE,kBAAkB;YAChC,OAAO,EAAE,EAAE,aAAa,EAAE,0BAA0B,EAAE;YACtD,UAAU,EAAE,MAAM;SACnB,CAAC;KACH,CAAC,CAAC;AACL,CAAC"}

package/dist/modules/tool-helpers/tool-handler.d.ts

@@ -0,0 +1,19 @@
+import type { Request, Response } from 'express';
+import { type ToolHandler } from './tool.contract.js';
+import type { ResolveToolContext } from './tool-context.js';
+import '../tool-auth/tool-auth.middleware.js';
+export interface ToolHandlerOptions {
+    /** Mutating tool — refuse read-scoped callers up front (defense in depth). */
+    write?: boolean;
+}
+/**
+ * Wrap a pure tool handler into an Express handler. Resolves the `ToolContext`
+ * from `req.toolAuth` (set by `toolAuth`), enforces write-scope, runs the
+ * handler, and serializes the result — JSON for a value, SSE for an
+ * async-iterable (streaming). `ToolError`/`hasHttpStatus` map to HTTP status.
+ * The handler receives `req.body` as the flat args (UTCP's `body_field` already
+ * delivered the inner body as the request body).
+ */
+export declare function createToolHandlerFactory(resolve: ResolveToolContext): (handler: ToolHandler, opts?: ToolHandlerOptions) => (req: Request, res: Response) => Promise<void>;
+export type ToolHandlerFactory = ReturnType<typeof createToolHandlerFactory>;
+//# sourceMappingURL=tool-handler.d.ts.map

package/dist/modules/tool-helpers/tool-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-handler.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,sCAAsC,CAAC;AAU9C,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,kBAAkB,IACtC,SAAS,WAAW,EAAE,OAAM,kBAAuB,MAC/D,KAAK,OAAO,EAAE,KAAK,QAAQ,KAAG,OAAO,CAAC,IAAI,CAAC,CA4D5D;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/modules/tool-helpers/tool-handler.js

@@ -0,0 +1,84 @@
+import { hasHttpStatus } from './tool.contract.js';
+import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
+function isAsyncIterable(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        typeof v[Symbol.asyncIterator] === 'function');
+}
+/**
+ * Wrap a pure tool handler into an Express handler. Resolves the `ToolContext`
+ * from `req.toolAuth` (set by `toolAuth`), enforces write-scope, runs the
+ * handler, and serializes the result — JSON for a value, SSE for an
+ * async-iterable (streaming). `ToolError`/`hasHttpStatus` map to HTTP status.
+ * The handler receives `req.body` as the flat args (UTCP's `body_field` already
+ * delivered the inner body as the request body).
+ */
+export function createToolHandlerFactory(resolve) {
+    return function toolHandler(handler, opts = {}) {
+        return async (req, res) => {
+            const auth = req.toolAuth;
+            if (!auth) {
+                res.status(401).json({ error: 'Unauthenticated' });
+                return;
+            }
+            if (opts.write && auth.scope === 'read') {
+                res.status(403).json({ error: 'This tool requires write access.' });
+                return;
+            }
+            const abort = new AbortController();
+            req.on('close', () => {
+                if (!res.writableEnded)
+                    abort.abort();
+            });
+            const body = req.body;
+            if (body !== undefined && body !== null && (typeof body !== 'object' || Array.isArray(body))) {
+                res.status(400).json({ error: 'Request body must be a JSON object.' });
+                return;
+            }
+            const args = (body ?? {});
+            // `sessionId` rides the tool body like `branch` does: the external MCP
+            // proxy injects it (ask-tool continuity convention) and the in-process
+            // agent passes its thread id. Surfaced on the context so the ontology
+            // gate can scope to one run without each handler re-reading args.
+            const sessionId = typeof args.sessionId === 'string' && args.sessionId.length > 0
+                ? args.sessionId
+                : undefined;
+            try {
+                const ctx = await resolve(auth, abort.signal, sessionId);
+                const out = await handler(args, ctx);
+                if (isAsyncIterable(out)) {
+                    res.setHeader('Content-Type', 'text/event-stream');
+                    res.setHeader('Cache-Control', 'no-cache');
+                    res.setHeader('Connection', 'keep-alive');
+                    for await (const chunk of out) {
+                        res.write(`data: ${JSON.stringify(chunk)}\n\n`);
+                    }
+                    res.end();
+                }
+                else {
+                    res.json(out);
+                }
+            }
+            catch (err) {
+                // A handler can throw after streaming has begun (headers committed); in
+                // that case we can only end the stream, not rewrite the status.
+                if (res.headersSent) {
+                    if (hasHttpStatus(err))
+                        console.error('[tools] handler failed post-stream:', err.message);
+                    else
+                        console.error('[tools] handler failed post-stream:', err instanceof Error ? err.message : err);
+                    res.end();
+                    return;
+                }
+                if (hasHttpStatus(err)) {
+                    res.status(err.status).json({ error: err.message });
+                    return;
+                }
+                const msg = err instanceof Error ? err.message : 'Unknown error';
+                console.error('[tools] handler failed:', msg);
+                res.status(500).json({ error: msg });
+            }
+        };
+    };
+}
+//# sourceMappingURL=tool-handler.js.map

package/dist/modules/tool-helpers/tool-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-handler.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-handler.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-helpers/tool.contract.d.ts

@@ -0,0 +1,64 @@
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { LocalFilesystem } from '@mastra/core/workspace';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkflowEventBus } from '../workflow/event-bus.js';
+/**
+ * The hosting/execution contract a module works against when it lets `toolHelpers`
+ * host its endpoint (`toolHandler`). It is NOT a registry concern — the registry
+ * only cares that a tool is a valid UTCP `Tool`. A provider hosting its own
+ * transport (websocket, its own server) never touches any of this.
+ *
+ * The normalized context every tool handler receives, regardless of whether the
+ * caller authenticated with a connection key (external) or an internal token.
+ * The route layer resolves it once via `resolveToolContext`; handlers never look
+ * at the auth source.
+ *
+ * `branch` is passed BY THE TOOL — a KB tool declares a required `branch` input
+ * the model fills, and hands it to `getFilesystem(branch)`. Internal and external
+ * callers are identical: the credential is identity-only, so the workspace always
+ * comes from this argument (the per-branch clone, `workspaceIdForBranch(branch)`).
+ * A tool that never touches the KB never calls `getFilesystem`, so it never
+ * resolves a workspace. Resolution is cached after the first call.
+ */
+export interface ToolContext {
+    user: AuthUser;
+    scope: 'read' | 'write';
+    source: 'internal' | 'external' | 'session';
+    /** Connection-key id (external key callers only) — for daily-token metering. */
+    tokenId?: string;
+    /**
+     * The agent run / conversation id this call belongs to (the agent thread id).
+     * Supplied as a `sessionId` field on the tool's input body — the external MCP
+     * proxy injects it via the `ask`-tool continuity convention, and the
+     * in-process agent passes its thread id. Used to scope the ontology-session
+     * boundary to one run. Absent for non-agent or unthreaded calls.
+     */
+    sessionId?: string;
+    abortSignal: AbortSignal;
+    workspaceService: WorkspaceService;
+    workflowService: IWorkflowService;
+    events: WorkflowEventBus;
+    /** Build the lock-aware filesystem for `branch`'s workspace (cached). The tool supplies `branch` from its own input. */
+    getFilesystem(branch: string): Promise<LocalFilesystem>;
+}
+/**
+ * A tool's implementation: a pure function of `(args, ctx)`. Return a value for
+ * a normal JSON tool, or an async-iterable to stream (the `toolHandler` wrapper
+ * serializes each chunk as SSE and the last as the result). `args` is the flat
+ * request body (the `{body}` envelope is already unwrapped by the route).
+ */
+export type ToolHandler = (args: Record<string, unknown>, ctx: ToolContext) => Promise<unknown> | AsyncIterable<unknown>;
+/**
+ * A failure a tool handler can throw to choose its own HTTP status. The route
+ * maps any thrown value with a numeric `status` to that code — covering this
+ * and `AgentAskService`'s `AgentAskError`.
+ */
+export declare class ToolError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function hasHttpStatus(err: unknown): err is {
+    status: number;
+    message: string;
+};
+//# sourceMappingURL=tool.contract.d.ts.map

package/dist/modules/tool-helpers/tool.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAIxB,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,eAAe,EAAE,gBAAgB,CAAC;IAClC,MAAM,EAAE,gBAAgB,CAAC;IACzB,wHAAwH;IACxH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACzD;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;AAE/C;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAGhC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;CAK1B;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAUtF"}

package/dist/modules/tool-helpers/tool.contract.js

@@ -0,0 +1,24 @@
+/**
+ * A failure a tool handler can throw to choose its own HTTP status. The route
+ * maps any thrown value with a numeric `status` to that code — covering this
+ * and `AgentAskService`'s `AgentAskError`.
+ */
+export class ToolError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'ToolError';
+    }
+}
+export function hasHttpStatus(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const status = err.status;
+    return (typeof status === 'number' &&
+        Number.isInteger(status) &&
+        status >= 100 &&
+        status <= 599 &&
+        typeof err.message === 'string');
+}
+//# sourceMappingURL=tool.contract.js.map

package/dist/modules/tool-helpers/tool.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.contract.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool.contract.ts"],"names":[],"mappings":"AA2DA;;;;GAIG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGvB;IAFX,YACE,OAAe,EACN,MAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,MAAM,GAAI,GAA4B,CAAC,MAAM,CAAC;IACpD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;QACxB,MAAM,IAAI,GAAG;QACb,MAAM,IAAI,GAAG;QACb,OAAQ,GAA6B,CAAC,OAAO,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC"}

package/dist/modules/tool-helpers/validate-token.d.ts

@@ -0,0 +1,31 @@
+import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import { InternalTokenService } from '../tool-auth/internal-token.service.js';
+import { type ToolContextDeps } from './tool-context.js';
+import { type ToolContext } from './tool.contract.js';
+export interface ToolValidatorDeps extends ToolContextDeps {
+    externalApiKeyService: IExternalApiKeyService;
+    internalTokenService: InternalTokenService;
+}
+/**
+ * The tool-author SDK entry point — framework-agnostic, no Express. Given a
+ * bearer token (the value AFTER `Bearer `), it verifies the token and returns the
+ * per-call `ToolContext` (user, scope, and lazy `getWorkspace()`/`getFilesystem()`
+ * accessors). It does NOT take a branch: a tool that targets a specific branch
+ * declares a `branch` input the model fills and passes it to
+ * `getWorkspace(branch)` / `getFilesystem(branch)` — so a branchless tool never
+ * deals with workspaces at all. Throws a `ToolError` (carrying an HTTP status) on
+ * a bad/expired token or an auth-backend failure, so any framework can map it.
+ *
+ * A tool — ours hosted in-process, or a third-party marketplace plugin hosting
+ * its own endpoint — calls exactly this:
+ *
+ *   const ctx = await validateToken(bearer);
+ *   const fs = await ctx.getFilesystem(branch);   // branch only if the tool declares one
+ *
+ * It shares `createTokenVerifier` with the Express `toolAuth` middleware, so the
+ * auth path is identical whether a request arrives through our router or a
+ * plugin's own server.
+ */
+export type ValidateToken = (token: string | undefined, signal?: AbortSignal) => Promise<ToolContext>;
+export declare function createToolValidator(deps: ToolValidatorDeps): ValidateToken;
+//# sourceMappingURL=validate-token.d.ts.map

package/dist/modules/tool-helpers/validate-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-token.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/validate-token.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAE9E,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjE,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,qBAAqB,EAAE,sBAAsB,CAAC;IAC9C,oBAAoB,EAAE,oBAAoB,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,WAAW,CAAC,CAAC;AAE1B,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAa1E"}

package/dist/modules/tool-helpers/validate-token.js

@@ -0,0 +1,20 @@
+import { createTokenVerifier } from '../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver } from './tool-context.js';
+import { ToolError } from './tool.contract.js';
+export function createToolValidator(deps) {
+    const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService);
+    const resolve = createToolContextResolver(deps);
+    return async (token, signal) => {
+        let result;
+        try {
+            result = await verify(token);
+        }
+        catch {
+            throw new ToolError('Authentication backend unavailable', 500);
+        }
+        if (!result.ok)
+            throw new ToolError(result.message, result.status);
+        return resolve(result.auth, signal ?? new AbortController().signal);
+    };
+}
+//# sourceMappingURL=validate-token.js.map

package/dist/modules/tool-helpers/validate-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-token.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/validate-token.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,EAAE,yBAAyB,EAAwB,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,SAAS,EAAoB,MAAM,oBAAoB,CAAC;AAgCjE,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,qBAAqB,EAAE,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAC1F,MAAM,OAAO,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAC7B,IAAI,MAAM,CAAC;QACX,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,SAAS,CAAC,oCAAoC,EAAE,GAAG,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACnE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM,CAAC,CAAC;IACtE,CAAC,CAAC;AACJ,CAAC"}

package/dist/modules/tool-manuals/index.d.ts

@@ -0,0 +1,5 @@
+export { ToolManualService } from './tool-manuals.service.js';
+export { registerToolManualsTools } from './tool-manuals.tools.js';
+export { createToolManualsAgentRoutes, createToolManualsBrowserRoutes, } from './tool-manuals.routes.js';
+export { EXTERNAL_KB_MANUAL_NAME, type IToolManualService, type ToolManualSummary, type ToolManualType, } from './tool-manuals.contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/tool-manuals/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,uBAAuB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,4BAA4B,CAAC"}

package/dist/modules/tool-manuals/index.js

@@ -0,0 +1,5 @@
+export { ToolManualService } from './tool-manuals.service.js';
+export { registerToolManualsTools } from './tool-manuals.tools.js';
+export { createToolManualsAgentRoutes, createToolManualsBrowserRoutes, } from './tool-manuals.routes.js';
+export { EXTERNAL_KB_MANUAL_NAME, } from './tool-manuals.contract.js';
+//# sourceMappingURL=index.js.map

package/dist/modules/tool-manuals/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/tool-manuals/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,uBAAuB,GAIxB,MAAM,4BAA4B,CAAC"}