@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/dist/modules/agent-instructions/compose.js

@@ -0,0 +1,234 @@
+/**
+ * What a connected agent is told at the start of an MCP session, composed
+ * from two layers: a platform header the code owns, and the deployment
+ * preamble an admin writes in `mcp-description.md` at the repository root.
+ *
+ * Two channels carry the result. The full text goes out as `instructions` on
+ * the initialize handshake, which Claude Code, Claude Desktop and Cursor place
+ * in the model's system prompt. claude.ai on the web, the Agent SDK and Cline
+ * drop that field, so a short prefix is also prepended to the descriptions of
+ * the four knowledge-base tools (the one pre-call channel every client shows
+ * the model). Both are capped, because both land in every conversation.
+ *
+ * Pure: no IO, no clock. The reader beside it (`read-preamble.ts`) does the
+ * file access; the hosted proxy, the agent-facing route and the local bridge
+ * all read this one composer's output.
+ */
+// The file, the caps and the comment rule are shared with the frontend
+// editor: it shows what these strip and writes back what they allow, so a
+// hand-mirrored copy would let the admin's view and the agent's text drift
+// apart. Re-exported here because this module is where the backend reads them
+// from.
+import { PREAMBLE_CAP, PREAMBLE_FILE, TOOL_PREFIX_CAP, stripHtmlComments, } from '@bevel-software/platform-shared';
+export { PREAMBLE_CAP, PREAMBLE_FILE, TOOL_PREFIX_CAP };
+/** The tools whose descriptions carry the prefix. Every other tool is untouched. */
+export const PREFIXED_TOOLS = new Set(['start_session', 'grep', 'list_files', 'read_file']);
+/**
+ * The platform header, owned by the code. What Hexis is, that its content is
+ * not in the model's training data, the order in which to search it, and that
+ * skills are reachable as prompts and through the two skill tools.
+ */
+export const PLATFORM_HEADER = "Hexis is this organisation's knowledge base, together with the skills and tools its teams have approved. " +
+    'Its content is specific to the organisation and is not in your training data. ' +
+    'Before answering a question about the organisation, its people, customers, products, processes, projects or internal terms, ' +
+    'search the knowledge base: call `start_session` once, then `grep` for the key terms, `list_files` to orient, and `read_file` what matches. ' +
+    'Prefer what you find there over memory or the web, and say so when the knowledge base is silent on something the organisation should have documented. ' +
+    'Skills are available as prompts and through `list_skills` and `get_skill`.';
+/**
+ * The fixed first line of the tool prefix. It always leads, so an admin's
+ * first edit never removes the instruction from the clients that only see
+ * tool descriptions, and a preamble that opens with a heading still yields a
+ * sensible purpose line.
+ */
+export const TOOL_PREFIX_LINE = "This organisation's knowledge base. Search it before answering from memory.";
+/** The one-line marker that replaces everything past the preamble cap. */
+export const PREAMBLE_TRUNCATION_MARKER = `[preamble truncated at ${PREAMBLE_CAP.toLocaleString('en-US')} characters; shorten ${PREAMBLE_FILE}]`;
+/**
+ * Compose the two texts from the raw file content (`null` when the file is
+ * absent). HTML comments are private notes and never leave the file; an
+ * unterminated `<!--` strips everything after it, so the most likely editing
+ * slip withholds text rather than leaking it.
+ */
+export function composeAgentInstructions(preamble) {
+    const { text, unterminated } = stripHtmlComments(preamble ?? '');
+    const normalized = text.replace(/\r\n?/g, '\n');
+    const stripped = normalized.trim();
+    const preambleChars = stripped.length;
+    const truncated = preambleChars > PREAMBLE_CAP;
+    const body = truncated ? `${cutAtCodePoint(stripped, PREAMBLE_CAP)}\n${PREAMBLE_TRUNCATION_MARKER}` : stripped;
+    const instructions = body ? `${PLATFORM_HEADER}\n\n${body}` : PLATFORM_HEADER;
+    // Classified UNTRIMMED: the leading indentation of a first line is what
+    // makes it an indented code block, and the trim above would turn that
+    // code into prose. The paragraph itself comes back trimmed.
+    const paragraph = firstNonHeadingParagraph(normalized);
+    const fullPrefix = paragraph ? `${TOOL_PREFIX_LINE} ${paragraph}` : TOOL_PREFIX_LINE;
+    const toolPrefixChars = fullPrefix.length;
+    const toolPrefixTruncated = toolPrefixChars > TOOL_PREFIX_CAP;
+    const toolPrefix = toolPrefixTruncated ? cutAtCodePoint(fullPrefix, TOOL_PREFIX_CAP) : fullPrefix;
+    return {
+        instructions,
+        header: PLATFORM_HEADER,
+        preamble: body,
+        toolPrefix,
+        toolPrefixLine: TOOL_PREFIX_LINE,
+        truncated,
+        preambleChars,
+        toolPrefixTruncated,
+        toolPrefixChars,
+        unterminatedComment: unterminated,
+    };
+}
+/**
+ * A tool description with the prefix ahead of it: the prefix, a blank line,
+ * then the original. Purpose line first, because claude.ai cuts descriptions
+ * near 500 characters.
+ */
+export function prefixToolDescription(toolPrefix, description) {
+    return description ? `${toolPrefix}\n\n${description}` : toolPrefix;
+}
+/** An ATX heading line: `#` to `######`, then a space or the end. */
+const ATX_HEADING = /^#{1,6}(\s|$)/;
+/** The underline of a setext heading: a run of `=` or `-` on its own line. */
+const SETEXT_UNDERLINE = /^(=+|-+)$/;
+/** A thematic break: three or more `-`, `*` or `_`, optionally spaced. */
+const THEMATIC_BREAK = /^([-*_])(\s*\1){2,}$/;
+/** The opener of a fenced code block: three or more backticks or tildes, then an optional info string. */
+const CODE_FENCE = /^(`{3,}|~{3,})/;
+/** A list item or a blockquote line: a setext underline cannot be a lazy continuation of either. */
+const LIST_ITEM_OR_QUOTE = /^([-*+]|\d{1,9}[.)])(\s|$)|^>/;
+/**
+ * The first paragraph that is not a markdown heading, collapsed to one line.
+ * Blocks are separated by blank lines and by code, fenced or indented; code
+ * is never a paragraph, so a fence and everything inside it (blank lines
+ * and rules included) are skipped, a fence that never closes runs to the
+ * end of the text, and an indented block is skipped line by line — all as
+ * in CommonMark (see `paragraphBlocks`). Inside a block, ATX heading lines and
+ * rules (a thematic break, or a bare `===` or `---` line) are never content,
+ * and a setext heading (paragraph text with a `===` or `---` underline
+ * directly beneath it) is dropped together with its underline, so
+ * `Title\n===\nText` and `## Title\nText` both yield `Text`. A rule beneath
+ * a list item or a blockquote, or beneath the lines that continue one, is
+ * not an underline (it cannot lazily continue either), so `- Item\n---`
+ * keeps the item and drops the rule. Empty when the text has no such
+ * paragraph (absent, empty, code-only or heading-only preamble).
+ */
+function firstNonHeadingParagraph(text) {
+    for (const block of paragraphBlocks(text)) {
+        const kinds = block.map((l) => l.kind);
+        // A list item or blockquote owns every line beneath it until the block
+        // ends (a lazy continuation is trimmed to look like paragraph text), so
+        // once one opens, no rule further down the block is an underline.
+        let container = false;
+        let underline = -1;
+        kinds.forEach((kind, i) => {
+            if (kind === 'container')
+                container = true;
+            else if (kind === 'rule' && i > 0 && !container && kinds[i - 1] === 'text' && SETEXT_UNDERLINE.test(block[i].text))
+                underline = i;
+        });
+        const content = block.filter((l, i) => i > underline && (l.kind === 'text' || l.kind === 'container'));
+        if (content.length > 0)
+            return content.map((l) => l.text).join(' ').replace(/\s+/g, ' ');
+    }
+    return '';
+}
+/**
+ * What a line is on its own, in CommonMark's order of precedence: a rule is
+ * tested before a list item because `- - -` and `* * *` are breaks, not
+ * items. Whether a rule underlines the text above it depends on its
+ * neighbours and is decided by the caller.
+ */
+function lineKind(line) {
+    if (ATX_HEADING.test(line))
+        return 'heading';
+    if (THEMATIC_BREAK.test(line) || SETEXT_UNDERLINE.test(line))
+        return 'rule';
+    if (LIST_ITEM_OR_QUOTE.test(line))
+        return 'container';
+    return 'text';
+}
+/**
+ * The text's blocks outside code, each a list of trimmed non-blank lines.
+ *
+ * Indentation decides what is code, as in CommonMark: a fence opens or
+ * closes only when indented at most three columns, and a line indented
+ * four or more where no paragraph is open — at the start of a block, or
+ * right after a heading or a rule, which end whatever came before them —
+ * is an indented code block: literal text, so a ``` in it is content, not
+ * a fence that would swallow the rest of the file. Under paragraph text
+ * (a list item or blockquote included) the same indentation is a
+ * continuation, since indented code cannot interrupt a paragraph — and a
+ * continuation is paragraph TEXT whatever it says once trimmed: `    # x`
+ * under a line of prose is not a heading and `    ---` is not a rule, so
+ * each line's kind is decided here, with its indentation in hand, and
+ * carried with it.
+ */
+function paragraphBlocks(text) {
+    const blocks = [];
+    let block = [];
+    let fence = null; // the opener of the fenced code block being skipped
+    const flush = () => {
+        if (block.length > 0)
+            blocks.push(block);
+        block = [];
+    };
+    const paragraphOpen = () => {
+        const last = block[block.length - 1];
+        return last !== undefined && (last.kind === 'text' || last.kind === 'container');
+    };
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        const indent = indentColumns(raw);
+        if (fence !== null) {
+            // The closer: the opener's character only, at least as many of it, nothing else.
+            if (indent <= 3 && line.startsWith(fence) && /^(`+|~+)$/.test(line))
+                fence = null;
+            continue;
+        }
+        const opener = indent <= 3 ? CODE_FENCE.exec(line) : null;
+        if (opener) {
+            flush();
+            fence = opener[1];
+        }
+        else if (line.length === 0) {
+            flush();
+        }
+        else if (indent >= 4) {
+            // Indented code, skipped line by line (blank lines between flush
+            // nothing) — or, under an open paragraph, a continuation of it.
+            if (paragraphOpen())
+                block.push({ text: line, kind: 'text' });
+        }
+        else {
+            block.push({ text: line, kind: lineKind(line) });
+        }
+    }
+    flush();
+    return blocks;
+}
+/** Leading indentation in columns, a tab reaching the next multiple of four. */
+function indentColumns(raw) {
+    let columns = 0;
+    for (const ch of raw) {
+        if (ch === ' ')
+            columns += 1;
+        else if (ch === '\t')
+            columns += 4 - (columns % 4);
+        else
+            break;
+    }
+    return columns;
+}
+/**
+ * `text` cut to at most `max` UTF-16 units, never inside a surrogate pair: a
+ * high surrogate at the cut moves the cut before it, so no broken character
+ * is ever sent and the count in the card matches what the server sends.
+ */
+function cutAtCodePoint(text, max) {
+    if (text.length <= max)
+        return text;
+    const last = text.charCodeAt(max - 1);
+    const end = last >= 0xd800 && last <= 0xdbff ? max - 1 : max;
+    return text.slice(0, end);
+}
+//# sourceMappingURL=compose.js.map

package/dist/modules/agent-instructions/compose.js.map

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

package/dist/modules/agent-instructions/index.d.ts

@@ -0,0 +1,4 @@
+export { composeAgentInstructions, prefixToolDescription, PLATFORM_HEADER, TOOL_PREFIX_LINE, PREAMBLE_CAP, TOOL_PREFIX_CAP, PREAMBLE_FILE, PREFIXED_TOOLS, PREAMBLE_TRUNCATION_MARKER, type ComposedAgentInstructions, } from './compose.js';
+export { readAgentPreamble, type AgentPreambleReader, type PreambleWorkspace } from './read-preamble.js';
+export { createAgentInstructionsRoutes } from './agent-instructions.routes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/agent-instructions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,EACd,0BAA0B,EAC1B,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/modules/agent-instructions/index.js

@@ -0,0 +1,4 @@
+export { composeAgentInstructions, prefixToolDescription, PLATFORM_HEADER, TOOL_PREFIX_LINE, PREAMBLE_CAP, TOOL_PREFIX_CAP, PREAMBLE_FILE, PREFIXED_TOOLS, PREAMBLE_TRUNCATION_MARKER, } from './compose.js';
+export { readAgentPreamble } from './read-preamble.js';
+export { createAgentInstructionsRoutes } from './agent-instructions.routes.js';
+//# sourceMappingURL=index.js.map

package/dist/modules/agent-instructions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/agent-instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,EACd,0BAA0B,GAE3B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAoD,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/modules/agent-instructions/read-preamble.d.ts

@@ -0,0 +1,37 @@
+import { type IFsProbe } from '../../shared/fs.contract.js';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+/** The one reader both the hosted proxy and the agent-facing route call. */
+export type AgentPreambleReader = () => Promise<string | null>;
+/** The two workspace operations the reader needs, so a test can stand in for the service. */
+export type PreambleWorkspace = Pick<WorkspaceService, 'getOrCreateForBranch' | 'getWorkspacePath'>;
+/**
+ * The raw content of `mcp-description.md` on the default branch, read with
+ * PLATFORM privileges: the root is default-deny for reads, and the preamble is
+ * a broadcast the admin writes for every connected agent, so it is never read
+ * as the caller. `null` only for an ABSENT file (the disk's own definition of
+ * absence); any other failure throws, so a disk fault never masquerades as
+ * "no preamble". The workspace is
+ * created first when it does not exist yet, exactly as the plugin archive
+ * route does.
+ *
+ * SYMLINKS ARE REFUSED, the same rule the plugin archive applies. This file is
+ * read as the platform and sent to every agent, so a link at this name (they
+ * only arrive by direct git push; the platform's own write paths never create
+ * one) would broadcast whatever the server process can read. `lstat` rejects a
+ * link or any non-regular entry before the open, and the open itself uses
+ * `O_NOFOLLOW` and reads through the handle it checked, so the bytes sent come
+ * from the inode the check passed rather than from a path swapped in between.
+ * The rule covers the WHOLE path below the workspace, not only the final
+ * component: the repository folder resolved through a link would put a
+ * regular file at the name with the link a level up, so the path's realpath
+ * must equal the spelled path under the workspace's own — identity, as the
+ * archive demands it, not mere containment. (The workspace root may itself
+ * sit behind a link — a mounted volume — which is the operator's, not the
+ * repository's, and is allowed.)
+ *
+ * Inside the workspace the repository is the `<kbDirName>/` folder, so the
+ * path is `<kbDirName>/mcp-description.md`, the same shape `SkillService` and
+ * the archive route use.
+ */
+export declare function readAgentPreamble(workspace: PreambleWorkspace, kbDirName: string, disk: IFsProbe): Promise<string | null>;
+//# sourceMappingURL=read-preamble.d.ts.map

package/dist/modules/agent-instructions/read-preamble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-preamble.d.ts","sourceRoot":"","sources":["../../../src/modules/agent-instructions/read-preamble.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAG1E,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE/D,6FAA6F;AAC7F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,sBAAsB,GAAG,kBAAkB,CAAC,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB"}

package/dist/modules/agent-instructions/read-preamble.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { isAbsence } from '../../shared/fs.contract.js';
+import { PREAMBLE_FILE } from './compose.js';
+/**
+ * The raw content of `mcp-description.md` on the default branch, read with
+ * PLATFORM privileges: the root is default-deny for reads, and the preamble is
+ * a broadcast the admin writes for every connected agent, so it is never read
+ * as the caller. `null` only for an ABSENT file (the disk's own definition of
+ * absence); any other failure throws, so a disk fault never masquerades as
+ * "no preamble". The workspace is
+ * created first when it does not exist yet, exactly as the plugin archive
+ * route does.
+ *
+ * SYMLINKS ARE REFUSED, the same rule the plugin archive applies. This file is
+ * read as the platform and sent to every agent, so a link at this name (they
+ * only arrive by direct git push; the platform's own write paths never create
+ * one) would broadcast whatever the server process can read. `lstat` rejects a
+ * link or any non-regular entry before the open, and the open itself uses
+ * `O_NOFOLLOW` and reads through the handle it checked, so the bytes sent come
+ * from the inode the check passed rather than from a path swapped in between.
+ * The rule covers the WHOLE path below the workspace, not only the final
+ * component: the repository folder resolved through a link would put a
+ * regular file at the name with the link a level up, so the path's realpath
+ * must equal the spelled path under the workspace's own — identity, as the
+ * archive demands it, not mere containment. (The workspace root may itself
+ * sit behind a link — a mounted volume — which is the operator's, not the
+ * repository's, and is allowed.)
+ *
+ * Inside the workspace the repository is the `<kbDirName>/` folder, so the
+ * path is `<kbDirName>/mcp-description.md`, the same shape `SkillService` and
+ * the archive route use.
+ */
+export async function readAgentPreamble(workspace, kbDirName, disk) {
+    await workspace.getOrCreateForBranch(DEFAULT_BRANCH);
+    const wsDir = await workspace.getWorkspacePath(workspaceIdForBranch(DEFAULT_BRANCH));
+    const abs = path.join(wsDir, kbDirName, PREAMBLE_FILE);
+    const found = await disk.lstatOrNull(abs);
+    if (found === null)
+        return null;
+    if (!found.isFile())
+        throw notRegular(found.isSymbolicLink() ? 'symlink' : found.isDirectory() ? 'directory' : 'special file');
+    const [realWorkspace, realFile] = await Promise.all([
+        fs.realpath(wsDir),
+        fs.realpath(abs).catch((err) => {
+            if (isAbsence(err))
+                return null; // deleted since the lstat: an absence, not a failure
+            throw err;
+        }),
+    ]);
+    if (realFile === null)
+        return null;
+    if (realFile !== path.join(realWorkspace, kbDirName, PREAMBLE_FILE))
+        throw notRegular('path through a symlink');
+    const handle = await fs
+        .open(abs, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0))
+        .catch((err) => {
+        if (isAbsence(err))
+            return null; // deleted since the lstat: an absence, not a failure
+        if (err.code === 'ELOOP')
+            throw notRegular('symlink'); // O_NOFOLLOW's spelling of "the final component is a link"
+        throw err;
+    });
+    if (handle === null)
+        return null;
+    try {
+        if (!(await handle.stat()).isFile())
+            throw notRegular('special file');
+        return await handle.readFile('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+function notRegular(kind) {
+    return new Error(`${PREAMBLE_FILE} on branch "${DEFAULT_BRANCH}" is a ${kind}, not a regular file at its own place; ` +
+        'refusing to read it. Replace it with a plain markdown file in the repository folder.');
+}
+//# sourceMappingURL=read-preamble.js.map

package/dist/modules/agent-instructions/read-preamble.js.map

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

package/dist/modules/audit/agent-audit.service.d.ts

@@ -0,0 +1,54 @@
+import type { Database } from '../database/connection.js';
+import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import { type AgentEventInput, type AgentEventPage, type AuditPrincipal, type AuditPrincipalRef, type AuditScope, type IAgentAuditService, type IAgentEventRecorder } from './audit.contract.js';
+/** The most events one page may carry; the routes clamp to it. */
+export declare const MAX_EVENT_PAGE = 200;
+/**
+ * The Audit log: the write half the MCP proxy records through, and the read
+ * and revoke half its page is built on.
+ *
+ * Writes are fire-and-forget by contract — a tool result must never wait on,
+ * or fail over, its own bookkeeping. Retention is enforced opportunistically
+ * on the write path (one sweep per process per hour, piggybacked on an
+ * insert), the same way the OAuth tables prune themselves on mint: no
+ * scheduler, and a deployment that records nothing has nothing to sweep.
+ *
+ * Connection keys are read through the key service rather than joined here,
+ * so their summary shape (kind, revoked-by, …) has exactly one definition.
+ */
+export declare class AgentAuditService implements IAgentAuditService, IAgentEventRecorder {
+    private readonly db;
+    private readonly keys;
+    /** Read per sweep, so a changed setting applies without a restart; null = keep forever. */
+    private readonly retentionDays;
+    private readonly now;
+    private lastPruneAt;
+    constructor(db: Database, keys: Pick<IExternalApiKeyService, 'listForUser' | 'listForDeployment' | 'ownerOf'>, 
+    /** Read per sweep, so a changed setting applies without a restart; null = keep forever. */
+    retentionDays: () => number | null, now?: () => number);
+    record(event: AgentEventInput): void;
+    /**
+     * Sweep events older than the retention window — at most once per hour per
+     * process, best-effort, never awaited by a caller. A deployment that keeps
+     * events forever sweeps nothing.
+     */
+    private maybePrune;
+    listPrincipals(scope: AuditScope): Promise<AuditPrincipal[]>;
+    /** One person's keys, with the owner attached the way the deployment listing attaches it. */
+    private keysForUser;
+    ownerOf(principal: AuditPrincipalRef): Promise<string | null>;
+    listEvents(principal: AuditPrincipalRef, page: {
+        before?: string;
+        limit: number;
+    }): Promise<AgentEventPage>;
+    revokeConnection(id: string, by: 'owner' | 'admin', ownerUserId?: string): Promise<void>;
+}
+/**
+ * The retention window the service runs on, in days — or null to keep
+ * events forever, which is what a blank, zero or negative setting means. A
+ * value that is not a window at all is kept-forever too, said out loud once:
+ * the Deployment page shows an environment value as the one in effect and
+ * would otherwise be the only place claiming a window nobody is keeping.
+ */
+export declare function retentionDaysFrom(raw: string): number | null;
+//# sourceMappingURL=agent-audit.service.d.ts.map

package/dist/modules/audit/agent-audit.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-audit.service.d.ts","sourceRoot":"","sources":["../../../src/modules/audit/agent-audit.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AACzF,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,cAAc,EAEnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAI7B,kEAAkE;AAClE,eAAO,MAAM,cAAc,MAAM,CAAC;AAKlC;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB,EAAE,mBAAmB;IAI7E,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,WAAW,CAAK;gBAGL,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,GAAG,mBAAmB,GAAG,SAAS,CAAC;IACpG,2FAA2F;IAC1E,aAAa,EAAE,MAAM,MAAM,GAAG,IAAI,EAClC,GAAG,GAAE,MAAM,MAAiB;IAG/C,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAoBpC;;;;OAIG;YACW,UAAU;IAclB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAmElE,6FAA6F;YAC/E,WAAW;IAanB,OAAO,CAAC,SAAS,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa7D,UAAU,CACd,SAAS,EAAE,iBAAiB,EAC5B,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GACvC,OAAO,CAAC,cAAc,CAAC;IAsDpB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA8B/F;AAyBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW5D"}