@helmetfire-labs/cartridge-common 0.1.0

package/LICENSE

@@ -0,0 +1,130 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all your
+licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software
+to do everything you might do with the software that would
+otherwise infringe the licensor's copyright in it for any
+permitted purpose. However, you may only distribute the
+software according to [Distribution License](#distribution-license) and make
+changes or new works based on the software according to
+[Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software. Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright Kevin Kruusi (https://github.com/k-kruusi)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software
+that covers patent claims the licensor can license, or
+becomes able to license, that you would infringe by using
+the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a **permitted purpose**.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the
+benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization, or
+government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any
+of your licenses to anyone else, or prevent the licensor
+from granting licenses to anyone else. These terms do not
+imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms, and
+take practical steps to correct past violations, within 32 days
+of receiving notice. Otherwise, all your licenses end
+immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship, or
+other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/dist/actions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonical action verbs for infrastructure cartridge log events.
+ * Using these consistently makes logs pattern-matchable across cartridges.
+ */
+export declare const ACTIONS: {
+    readonly recv: "recv";
+    readonly forward: "forward";
+    readonly startup: "startup";
+    readonly shutdown: "shutdown";
+    readonly disconnect: "disconnect";
+    readonly acquire: "acquire";
+    readonly release: "release";
+    readonly queued: "queued";
+    readonly ok: "ok";
+    readonly error: "error";
+    readonly timeout: "timeout";
+    readonly blocked: "blocked";
+    readonly hit: "hit";
+    readonly miss: "miss";
+    readonly evict: "evict";
+    readonly OPEN: "OPEN";
+    readonly CLOSED: "CLOSED";
+    readonly HALF_OPEN: "HALF_OPEN";
+    readonly retry: "retry";
+    readonly exhausted: "exhausted";
+    readonly inject: "inject";
+    readonly refresh: "refresh";
+    readonly rewrite: "rewrite";
+    readonly redact: "redact";
+    readonly pending: "pending";
+    readonly approved: "approved";
+    readonly rejected: "rejected";
+};
+export type ActionKey = keyof typeof ACTIONS;
+export type ActionValue = (typeof ACTIONS)[ActionKey];

package/dist/actions.js

@@ -0,0 +1,43 @@
+/**
+ * Canonical action verbs for infrastructure cartridge log events.
+ * Using these consistently makes logs pattern-matchable across cartridges.
+ */
+export const ACTIONS = {
+    // Lifecycle
+    recv: 'recv',
+    forward: 'forward',
+    startup: 'startup',
+    shutdown: 'shutdown',
+    disconnect: 'disconnect',
+    // Locking
+    acquire: 'acquire',
+    release: 'release',
+    queued: 'queued',
+    // Outcomes
+    ok: 'ok',
+    error: 'error',
+    timeout: 'timeout',
+    blocked: 'blocked',
+    // Cache
+    hit: 'hit',
+    miss: 'miss',
+    evict: 'evict',
+    // Circuit breaker
+    OPEN: 'OPEN',
+    CLOSED: 'CLOSED',
+    HALF_OPEN: 'HALF_OPEN',
+    // Retry
+    retry: 'retry',
+    exhausted: 'exhausted',
+    // Auth
+    inject: 'inject',
+    refresh: 'refresh',
+    // Transform
+    rewrite: 'rewrite',
+    redact: 'redact',
+    // Approval
+    pending: 'pending',
+    approved: 'approved',
+    rejected: 'rejected',
+};
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,YAAY;IACZ,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,YAAY;IAExB,UAAU;IACV,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAEhB,WAAW;IACX,EAAE,EAAE,IAAI;IACR,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAElB,QAAQ;IACR,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IAEd,kBAAkB;IAClB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IAEtB,QAAQ;IACR,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,WAAW;IAEtB,OAAO;IACP,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAElB,YAAY;IACZ,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAEhB,WAAW;IACX,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;CACZ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Error boundary wrapper and classification for infrastructure cartridges.
+ *
+ * Catches errors from upstream MCP calls, classifies them into a standard
+ * shape, logs them in terse format, and re-throws so callers can handle.
+ */
+/**
+ * Standard error shapes for common failure modes.
+ * Used as log shapes — values are [placeholders] for pattern matching.
+ */
+export declare const ERROR_SHAPES: {
+    readonly connectionRefused: "error: upstream [cartridge] unreachable";
+    readonly timeout: "timeout: [tool] exceeded [N]ms";
+    readonly toolNotFound: "error: tool [tool] not found on [cartridge]";
+    readonly authFailed: "error: authentication failed on [cartridge]";
+    readonly malformedResponse: "error: malformed response from [cartridge]";
+    readonly queueFull: "error: queue full on [tool]";
+    readonly lockTimeout: "timeout: acquire TTL expired on [tool]";
+};
+export type ErrorShapeKey = keyof typeof ERROR_SHAPES;
+/**
+ * Classify an error into a standard shape.
+ * Falls back to a generic extracted shape if no pattern matches.
+ */
+export declare function classifyError(err: Error | string): string;
+/**
+ * Wrap a function call with an error boundary that:
+ * 1. Catches any thrown error
+ * 2. Classifies it into a standard shape
+ * 3. Logs in terse format using logEvent()
+ * 4. Re-throws the original error
+ */
+export declare function withErrorBoundary<T>(opts: {
+    trace: string;
+    tag: string;
+    tool: string;
+    fn: () => Promise<T>;
+}): Promise<T>;

package/dist/errors.js

@@ -0,0 +1,79 @@
+/**
+ * Error boundary wrapper and classification for infrastructure cartridges.
+ *
+ * Catches errors from upstream MCP calls, classifies them into a standard
+ * shape, logs them in terse format, and re-throws so callers can handle.
+ */
+import { logEvent } from './logger.js';
+import { extractShape } from './shape.js';
+/**
+ * Standard error shapes for common failure modes.
+ * Used as log shapes — values are [placeholders] for pattern matching.
+ */
+export const ERROR_SHAPES = {
+    connectionRefused: 'error: upstream [cartridge] unreachable',
+    timeout: 'timeout: [tool] exceeded [N]ms',
+    toolNotFound: 'error: tool [tool] not found on [cartridge]',
+    authFailed: 'error: authentication failed on [cartridge]',
+    malformedResponse: 'error: malformed response from [cartridge]',
+    queueFull: 'error: queue full on [tool]',
+    lockTimeout: 'timeout: acquire TTL expired on [tool]',
+};
+/**
+ * Classify an error into a standard shape.
+ * Falls back to a generic extracted shape if no pattern matches.
+ */
+export function classifyError(err) {
+    const msg = err instanceof Error ? err.message : err;
+    const lower = msg.toLowerCase();
+    if (lower.includes('econnrefused') || lower.includes('unreachable') || lower.includes('connect')) {
+        return ERROR_SHAPES.connectionRefused;
+    }
+    if (lower.includes('timed out') || lower.includes('timeout') || lower.includes('ttl expired')) {
+        if (lower.includes('ttl') || lower.includes('acquire')) {
+            return ERROR_SHAPES.lockTimeout;
+        }
+        return ERROR_SHAPES.timeout;
+    }
+    if (lower.includes('tool') && (lower.includes('not found') || lower.includes('unknown'))) {
+        return ERROR_SHAPES.toolNotFound;
+    }
+    if (lower.includes('auth') || lower.includes('unauthorized') || lower.includes('forbidden')) {
+        return ERROR_SHAPES.authFailed;
+    }
+    if (lower.includes('malformed') || lower.includes('invalid response') || lower.includes('parse')) {
+        return ERROR_SHAPES.malformedResponse;
+    }
+    if (lower.includes('queue') && (lower.includes('full') || lower.includes('depth'))) {
+        return ERROR_SHAPES.queueFull;
+    }
+    // Fall back to heuristic shape extraction from the raw message
+    return extractShape(msg);
+}
+/**
+ * Wrap a function call with an error boundary that:
+ * 1. Catches any thrown error
+ * 2. Classifies it into a standard shape
+ * 3. Logs in terse format using logEvent()
+ * 4. Re-throws the original error
+ */
+export async function withErrorBoundary(opts) {
+    const { trace, tag, tool, fn } = opts;
+    try {
+        return await fn();
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const shape = classifyError(error);
+        const cleanMessage = error.message.replace(/[\n\r]/g, ' ').slice(0, 120);
+        logEvent({
+            trace,
+            tag,
+            action: 'error',
+            shape,
+            details: { tool, message: cleanMessage },
+        });
+        throw err;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @agentruntime/cartridge-common
+ *
+ * Shared logging, error boundaries, and trace helpers for infrastructure cartridges.
+ *
+ * Philosophy: infrastructure cartridges NEVER expose their own MCP tools.
+ * They log to stdout in terse, scannable format. The operator agent reads logs.
+ * No dashboards. No admin APIs. Just logs and conversation.
+ */
+export { logEvent } from './logger.js';
+export type { LogEventOpts } from './logger.js';
+export { TAGS, isValidTag } from './tags.js';
+export type { TagKey, TagValue } from './tags.js';
+export { ACTIONS } from './actions.js';
+export type { ActionKey, ActionValue } from './actions.js';
+export { generateTraceId, extractTraceId, traceMetadata, extractHop, NO_TRACE, } from './trace.js';
+export { extractShape } from './shape.js';
+export { withErrorBoundary, classifyError, ERROR_SHAPES, } from './errors.js';
+export type { ErrorShapeKey } from './errors.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @agentruntime/cartridge-common
+ *
+ * Shared logging, error boundaries, and trace helpers for infrastructure cartridges.
+ *
+ * Philosophy: infrastructure cartridges NEVER expose their own MCP tools.
+ * They log to stdout in terse, scannable format. The operator agent reads logs.
+ * No dashboards. No admin APIs. Just logs and conversation.
+ */
+export { logEvent } from './logger.js';
+export { TAGS, isValidTag } from './tags.js';
+export { ACTIONS } from './actions.js';
+export { generateTraceId, extractTraceId, traceMetadata, extractHop, NO_TRACE, } from './trace.js';
+export { extractShape } from './shape.js';
+export { withErrorBoundary, classifyError, ERROR_SHAPES, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG7C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Core logging function for infrastructure cartridges.
+ *
+ * Format: [trace] tag action: shape, key: value, key: value
+ * Example: [abc123] mtx acquire: handle_pr, caller: worker-1, waited: 0ms
+ *
+ * Rules:
+ * - One line per event. Never multi-line. Never JSON. Never stack traces.
+ * - Shape (before first comma) is the generalizable pattern for grep.
+ * - Details (after) are instance-specific key: value pairs.
+ * - This is the ONLY way infrastructure cartridges should log.
+ */
+export interface LogEventOpts {
+    /** 6-char correlation ID */
+    trace: string;
+    /** 3-char source tag (e.g. 'mtx', 'brk') */
+    tag: string;
+    /** Action verb (e.g. 'acquire', 'error', 'OPEN') */
+    action: string;
+    /** Generalizable pattern — replaces specifics with [placeholders] */
+    shape: string;
+    /** Instance-specific key-value pairs appended after the shape */
+    details?: Record<string, string | number>;
+}
+export declare function logEvent(opts: LogEventOpts): void;

package/dist/logger.js

@@ -0,0 +1,24 @@
+/**
+ * Core logging function for infrastructure cartridges.
+ *
+ * Format: [trace] tag action: shape, key: value, key: value
+ * Example: [abc123] mtx acquire: handle_pr, caller: worker-1, waited: 0ms
+ *
+ * Rules:
+ * - One line per event. Never multi-line. Never JSON. Never stack traces.
+ * - Shape (before first comma) is the generalizable pattern for grep.
+ * - Details (after) are instance-specific key: value pairs.
+ * - This is the ONLY way infrastructure cartridges should log.
+ */
+export function logEvent(opts) {
+    const { trace, tag, action, shape, details } = opts;
+    let line = `[${trace}] ${tag} ${action}: ${shape}`;
+    if (details && Object.keys(details).length > 0) {
+        const pairs = Object.entries(details)
+            .map(([k, v]) => `${k}: ${v}`)
+            .join(', ');
+        line += `, ${pairs}`;
+    }
+    process.stdout.write(line + '\n');
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,MAAM,UAAU,QAAQ,CAAC,IAAkB;IACzC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACpD,IAAI,IAAI,GAAG,IAAI,KAAK,KAAK,GAAG,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;IACnD,IAAI,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;aAClC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;aAC7B,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;IACvB,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AACpC,CAAC"}

package/dist/shape.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shape extraction — replaces specific values with [placeholders].
+ *
+ * Shapes are the generalizable part of a log message, used for pattern matching
+ * across many instances. The detail values are logged separately.
+ *
+ * Example:
+ *   extractShape("acquire: edit_file, caller: worker-3, waited: 340ms")
+ *   → "acquire: [tool], caller: [caller], waited: [duration]"
+ */
+/**
+ * Extract the generalizable shape from a log message.
+ *
+ * @param message  Raw message string (e.g. from an error or log call)
+ * @param knownTools    List of known tool names to replace with [tool]
+ * @param knownCallers  List of known caller names to replace with [caller]
+ */
+export declare function extractShape(message: string, knownTools?: string[], knownCallers?: string[]): string;

package/dist/shape.js

@@ -0,0 +1,46 @@
+/**
+ * Shape extraction — replaces specific values with [placeholders].
+ *
+ * Shapes are the generalizable part of a log message, used for pattern matching
+ * across many instances. The detail values are logged separately.
+ *
+ * Example:
+ *   extractShape("acquire: edit_file, caller: worker-3, waited: 340ms")
+ *   → "acquire: [tool], caller: [caller], waited: [duration]"
+ */
+// Matches durations: 340ms, 1.2s, 5m, 30m10s, etc.
+const DURATION_RE = /\b\d+(\.\d+)?(ms|s|m|h)\b/g;
+// Matches plain integers or decimals used as counts/sizes
+const NUMBER_RE = /\b\d{2,}\b/g;
+// Matches absolute file paths (Unix and Windows)
+const FILE_PATH_RE = /(?:[A-Za-z]:[\\\/][\w.\-\\\/]+|\b(?:\/[\w.\-/]+)+)/g;
+// Matches URLs
+const URL_RE = /https?:\/\/[^\s,]+/g;
+/**
+ * Extract the generalizable shape from a log message.
+ *
+ * @param message  Raw message string (e.g. from an error or log call)
+ * @param knownTools    List of known tool names to replace with [tool]
+ * @param knownCallers  List of known caller names to replace with [caller]
+ */
+export function extractShape(message, knownTools = [], knownCallers = []) {
+    let s = message;
+    // Replace known tool names first (most specific)
+    for (const tool of knownTools) {
+        s = s.split(tool).join('[tool]');
+    }
+    // Replace known caller names
+    for (const caller of knownCallers) {
+        s = s.split(caller).join('[caller]');
+    }
+    // Replace URLs before paths (URLs contain slashes)
+    s = s.replace(URL_RE, '[url]');
+    // Replace file paths
+    s = s.replace(FILE_PATH_RE, '[path]');
+    // Replace durations before generic numbers
+    s = s.replace(DURATION_RE, '[duration]');
+    // Replace remaining multi-digit numbers (leave single digits — often semantic)
+    s = s.replace(NUMBER_RE, '[N]');
+    return s;
+}
+//# sourceMappingURL=shape.js.map

package/dist/shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../src/shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,mDAAmD;AACnD,MAAM,WAAW,GAAG,4BAA4B,CAAC;AAEjD,0DAA0D;AAC1D,MAAM,SAAS,GAAG,aAAa,CAAC;AAEhC,iDAAiD;AACjD,MAAM,YAAY,GAAG,qDAAqD,CAAC;AAE3E,eAAe;AACf,MAAM,MAAM,GAAG,qBAAqB,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAe,EACf,aAAuB,EAAE,EACzB,eAAyB,EAAE;IAE3B,IAAI,CAAC,GAAG,OAAO,CAAC;IAEhB,iDAAiD;IACjD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,6BAA6B;IAC7B,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;QAClC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,mDAAmD;IACnD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/B,qBAAqB;IACrB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IAEtC,2CAA2C;IAC3C,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAEzC,+EAA+E;IAC/E,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAEhC,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/tags.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Canonical 3-char source tags for infrastructure cartridges.
+ * These appear in every log line: [trace] tag action: shape
+ */
+export declare const TAGS: {
+    readonly mutex: "mtx";
+    readonly semaphore: "sem";
+    readonly readonly: "rdo";
+    readonly retry: "rty";
+    readonly timeout: "tmo";
+    readonly circuitBreaker: "brk";
+    readonly router: "rtr";
+    readonly cache: "cch";
+    readonly auth: "aut";
+    readonly transform: "tfm";
+    readonly sanitize: "san";
+    readonly webhook: "whk";
+    readonly cron: "crn";
+    readonly audit: "aud";
+    readonly relay: "rly";
+    readonly mock: "mck";
+    readonly shadow: "shd";
+    readonly bridge: "brg";
+    readonly tee: "tee";
+    readonly approval: "apv";
+};
+export type TagKey = keyof typeof TAGS;
+export type TagValue = (typeof TAGS)[TagKey];
+export declare function isValidTag(s: string): s is TagValue;

package/dist/tags.js

@@ -0,0 +1,31 @@
+/**
+ * Canonical 3-char source tags for infrastructure cartridges.
+ * These appear in every log line: [trace] tag action: shape
+ */
+export const TAGS = {
+    mutex: 'mtx',
+    semaphore: 'sem',
+    readonly: 'rdo',
+    retry: 'rty',
+    timeout: 'tmo',
+    circuitBreaker: 'brk',
+    router: 'rtr',
+    cache: 'cch',
+    auth: 'aut',
+    transform: 'tfm',
+    sanitize: 'san',
+    webhook: 'whk',
+    cron: 'crn',
+    audit: 'aud',
+    relay: 'rly',
+    mock: 'mck',
+    shadow: 'shd',
+    bridge: 'brg',
+    tee: 'tee',
+    approval: 'apv',
+};
+const TAG_VALUES = new Set(Object.values(TAGS));
+export function isValidTag(s) {
+    return TAG_VALUES.has(s);
+}
+//# sourceMappingURL=tags.js.map

package/dist/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,KAAK,EAAE,KAAK;IACZ,SAAS,EAAE,KAAK;IAChB,QAAQ,EAAE,KAAK;IACf,KAAK,EAAE,KAAK;IACZ,OAAO,EAAE,KAAK;IACd,cAAc,EAAE,KAAK;IACrB,MAAM,EAAE,KAAK;IACb,KAAK,EAAE,KAAK;IACZ,IAAI,EAAE,KAAK;IACX,SAAS,EAAE,KAAK;IAChB,QAAQ,EAAE,KAAK;IACf,OAAO,EAAE,KAAK;IACd,IAAI,EAAE,KAAK;IACX,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,KAAK;IACZ,IAAI,EAAE,KAAK;IACX,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,KAAK;CACP,CAAC;AAKX,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AAExD,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC"}

package/dist/trace.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Correlation ID generation and propagation helpers.
+ * Every log line begins with [traceId] to correlate events across cartridges.
+ */
+/**
+ * Sentinel value for calls that arrive without any trace context.
+ */
+export declare const NO_TRACE = "------";
+/**
+ * Generate a 6-char alphanumeric correlation ID.
+ * Used by entry points (webhook, cron, direct calls) to start a new trace.
+ */
+export declare function generateTraceId(): string;
+/**
+ * Extract trace ID from MCP tool call metadata.
+ * Returns the trace ID if present, or NO_TRACE sentinel if absent.
+ */
+export declare function extractTraceId(meta?: Record<string, unknown>): string;
+/**
+ * Create metadata object with trace ID for forwarding.
+ * Attach this to MCP tool calls when proxying upstream.
+ */
+export declare function traceMetadata(traceId: string, hop: number): Record<string, unknown>;
+/**
+ * Extract hop count from metadata (defaults to 0 if not present).
+ */
+export declare function extractHop(meta?: Record<string, unknown>): number;

package/dist/trace.js

@@ -0,0 +1,56 @@
+/**
+ * Correlation ID generation and propagation helpers.
+ * Every log line begins with [traceId] to correlate events across cartridges.
+ */
+const TRACE_ID_CHARS = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const TRACE_ID_LENGTH = 6;
+/**
+ * Sentinel value for calls that arrive without any trace context.
+ */
+export const NO_TRACE = '------';
+/**
+ * Generate a 6-char alphanumeric correlation ID.
+ * Used by entry points (webhook, cron, direct calls) to start a new trace.
+ */
+export function generateTraceId() {
+    let id = '';
+    for (let i = 0; i < TRACE_ID_LENGTH; i++) {
+        id += TRACE_ID_CHARS[Math.floor(Math.random() * TRACE_ID_CHARS.length)];
+    }
+    return id;
+}
+const TRACE_META_KEY = '_agentruntime_trace';
+const TRACE_HOP_KEY = '_agentruntime_hop';
+/**
+ * Extract trace ID from MCP tool call metadata.
+ * Returns the trace ID if present, or NO_TRACE sentinel if absent.
+ */
+export function extractTraceId(meta) {
+    if (!meta)
+        return NO_TRACE;
+    const traceId = meta[TRACE_META_KEY];
+    if (typeof traceId === 'string' && traceId.length === TRACE_ID_LENGTH) {
+        return traceId;
+    }
+    return NO_TRACE;
+}
+/**
+ * Create metadata object with trace ID for forwarding.
+ * Attach this to MCP tool calls when proxying upstream.
+ */
+export function traceMetadata(traceId, hop) {
+    return {
+        [TRACE_META_KEY]: traceId,
+        [TRACE_HOP_KEY]: hop,
+    };
+}
+/**
+ * Extract hop count from metadata (defaults to 0 if not present).
+ */
+export function extractHop(meta) {
+    if (!meta)
+        return 0;
+    const hop = meta[TRACE_HOP_KEY];
+    return typeof hop === 'number' ? hop : 0;
+}
+//# sourceMappingURL=trace.js.map

package/dist/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,cAAc,GAAG,sCAAsC,CAAC;AAC9D,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,QAAQ,CAAC;AAEjC;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAC7C,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAE1C;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAA8B;IAC3D,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;IACrC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,eAAe,EAAE,CAAC;QACtE,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,GAAW;IACxD,OAAO;QACL,CAAC,cAAc,CAAC,EAAE,OAAO;QACzB,CAAC,aAAa,CAAC,EAAE,GAAG;KACrB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,IAA8B;IACvD,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IAChC,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@helmetfire-labs/cartridge-common",
+  "version": "0.1.0",
+  "description": "Shared logging, error boundaries, and trace helpers for infrastructure cartridges",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/k-kruusi/claude-supervisor.git",
+    "directory": "packages/cartridge-common"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "typescript": "^5.0.0"
+  }
+}