crewly 1.6.4 → 1.7.0

package/dist/backend/backend/src/services/observability/agent-behavior-log.service.js

@@ -0,0 +1,284 @@
+/**
+ * Agent Behavior Log — write/read service.
+ *
+ * Translates strongly-typed `BehaviorLogEvent` values into rows of the
+ * `agent_behavior_log` table and reads them back as typed records.
+ *
+ * Design choices:
+ * - One service instance owns one DB handle; tests pass `:memory:`.
+ * - All writes are append-only inserts; no updates, no deletes.
+ * - Best-effort logging — `record()` swallows DB errors after logging
+ *   them, so observability never takes the request path down.
+ * - Read APIs are minimal: this PR ships the schema + write surface.
+ *   Digest/aggregation queries land in a follow-up.
+ *
+ * Wiring of producers (Slack-failure listener, prompt-size sampler,
+ * orchestrator action logger) is intentionally out of scope for this
+ * PR — see P0-5 / prompt-generator follow-ups.
+ *
+ * @module services/observability/agent-behavior-log.service
+ */
+import { openObservabilityDatabase, } from './observability-db.js';
+import { BEHAVIOR_LOG_EVENT_TYPES, } from './agent-behavior-log.types.js';
+import { LoggerService } from '../core/logger.service.js';
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * Append-only writer + minimal reader for the `agent_behavior_log`
+ * table.
+ *
+ * @example
+ * ```ts
+ * const svc = new AgentBehaviorLogService();
+ * svc.record({
+ *   type: 'agent.action',
+ *   agent: 'crewly-orc',
+ *   actionType: 'delegate',
+ *   taskId: 'req-123',
+ *   details: { recipient: 'sam' },
+ * });
+ * ```
+ */
+export class AgentBehaviorLogService {
+    db;
+    ownsDb;
+    now;
+    logger;
+    insertStmt = null;
+    constructor(options = {}) {
+        this.logger =
+            options.logger ??
+                LoggerService.getInstance().createComponentLogger('AgentBehaviorLog');
+        this.now = options.now ?? Date.now;
+        if (options.db) {
+            this.db = options.db;
+            this.ownsDb = false;
+        }
+        else {
+            this.db = openObservabilityDatabase(options.openOptions);
+            this.ownsDb = true;
+        }
+    }
+    /**
+     * Lazily prepare and cache the insert statement. Avoids paying the
+     * prepare cost for callers that only ever read.
+     */
+    getInsertStmt() {
+        if (!this.insertStmt) {
+            this.insertStmt = this.db.prepare(`INSERT INTO agent_behavior_log
+           (ts, event_type, agent, subject, task_id, reason, amount, details_json)
+         VALUES
+           (@ts, @event_type, @agent, @subject, @task_id, @reason, @amount, @details_json)`);
+        }
+        return this.insertStmt;
+    }
+    /**
+     * Record one behavior event.
+     *
+     * Translates the discriminated `BehaviorLogEvent` into a
+     * `BehaviorLogRow`-compatible parameter object and inserts. Errors
+     * are caught and logged — observability writes must NEVER throw into
+     * the calling code path.
+     *
+     * @param event - The strongly-typed event to record
+     * @returns The newly inserted row id, or `null` if the write failed
+     */
+    record(event) {
+        const params = this.toRowParams(event);
+        try {
+            const result = this.getInsertStmt().run(params);
+            return Number(result.lastInsertRowid);
+        }
+        catch (err) {
+            this.logger.warn('Failed to record behavior log event', {
+                event_type: event.type,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+    }
+    /**
+     * Translate a `BehaviorLogEvent` into the parameter object expected
+     * by the prepared insert statement.
+     *
+     * The discriminator branch is exhaustive — adding a new event type
+     * forces a TypeScript error here until the new branch is added.
+     */
+    toRowParams(event) {
+        const ts = this.now();
+        switch (event.type) {
+            case BEHAVIOR_LOG_EVENT_TYPES.AGENT_ACTION:
+                return this.buildAgentActionParams(event, ts);
+            case BEHAVIOR_LOG_EVENT_TYPES.AGENT_ESCALATION:
+                return this.buildEscalationParams(event, ts);
+            case BEHAVIOR_LOG_EVENT_TYPES.SLACK_DELIVERY_FAILED:
+                return this.buildSlackFailureParams(event, ts);
+            case BEHAVIOR_LOG_EVENT_TYPES.PROMPT_SIZE_BYTES:
+                return this.buildPromptSizeParams(event, ts);
+            default: {
+                // Exhaustiveness guard — `_never` is `never` if the union is
+                // covered; if a new variant lands and isn't handled above, this
+                // line becomes a TypeScript error.
+                const _never = event;
+                throw new Error(`Unhandled behavior log event variant: ${JSON.stringify(_never)}`);
+            }
+        }
+    }
+    /** Build params for an `agent.action` event. */
+    buildAgentActionParams(event, ts) {
+        return {
+            ts,
+            event_type: BEHAVIOR_LOG_EVENT_TYPES.AGENT_ACTION,
+            agent: event.agent,
+            subject: '',
+            task_id: event.taskId ?? '',
+            reason: event.actionType,
+            amount: 0,
+            details_json: stringifyDetails(event.details),
+        };
+    }
+    /** Build params for an `agent.escalation` event. */
+    buildEscalationParams(event, ts) {
+        return {
+            ts,
+            event_type: BEHAVIOR_LOG_EVENT_TYPES.AGENT_ESCALATION,
+            agent: event.escalatingAgent,
+            subject: event.escalatedTo,
+            task_id: event.taskId ?? '',
+            reason: event.reason,
+            amount: 0,
+            details_json: stringifyDetails(event.details),
+        };
+    }
+    /** Build params for a `slack.delivery.failed` event. */
+    buildSlackFailureParams(event, ts) {
+        return {
+            ts,
+            event_type: BEHAVIOR_LOG_EVENT_TYPES.SLACK_DELIVERY_FAILED,
+            agent: event.agent,
+            subject: event.thread,
+            task_id: '',
+            reason: event.reason,
+            amount: 0,
+            details_json: stringifyDetails(event.details),
+        };
+    }
+    /** Build params for a `prompt.size.bytes` event. */
+    buildPromptSizeParams(event, ts) {
+        return {
+            ts,
+            event_type: BEHAVIOR_LOG_EVENT_TYPES.PROMPT_SIZE_BYTES,
+            agent: event.agent,
+            subject: event.sessionId ?? '',
+            task_id: '',
+            reason: '',
+            amount: Math.max(0, Math.floor(event.bytes)),
+            details_json: stringifyDetails(event.details),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Read API (minimal — digest queries arrive in follow-up)
+    // -------------------------------------------------------------------------
+    /**
+     * Return the most recent N rows, newest first. Optionally filter by
+     * event type. Intended for diagnostics and tests; production digest
+     * code should use a dedicated aggregation query.
+     *
+     * @param limit - Max rows to return (capped at 1000)
+     * @param eventType - Optional event-type filter
+     */
+    listRecent(limit = 100, eventType) {
+        const cappedLimit = Math.max(1, Math.min(1000, Math.floor(limit)));
+        const stmt = eventType
+            ? this.db.prepare(`SELECT * FROM agent_behavior_log
+             WHERE event_type = ?
+             ORDER BY id DESC
+             LIMIT ?`)
+            : this.db.prepare(`SELECT * FROM agent_behavior_log
+             ORDER BY id DESC
+             LIMIT ?`);
+        const rows = (eventType ? stmt.all(eventType, cappedLimit) : stmt.all(cappedLimit));
+        return rows.map(rowToRecord);
+    }
+    /**
+     * Count rows by event type since a given timestamp. Useful for the
+     * weekly digest's per-event totals.
+     *
+     * @param sinceTs - Inclusive ms-since-epoch lower bound (default 0 = all time)
+     */
+    countByEvent(sinceTs = 0) {
+        const rows = this.db
+            .prepare(`SELECT event_type AS et, COUNT(*) AS n
+           FROM agent_behavior_log
+           WHERE ts >= ?
+           GROUP BY event_type`)
+            .all(sinceTs);
+        const out = {};
+        for (const r of rows) {
+            out[r.et] = Number(r.n);
+        }
+        return out;
+    }
+    /**
+     * Close the underlying DB handle if this service opened it. Safe to
+     * call multiple times.
+     */
+    close() {
+        if (this.ownsDb) {
+            try {
+                this.db.close();
+            }
+            catch (err) {
+                this.logger.warn('Error closing observability DB', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Stringify a details payload to JSON, defaulting to '{}' when no
+ * payload is supplied or the value is not serialisable. Never throws.
+ */
+function stringifyDetails(details) {
+    if (!details)
+        return '{}';
+    try {
+        return JSON.stringify(details);
+    }
+    catch {
+        return '{}';
+    }
+}
+/**
+ * Decode a raw `BehaviorLogRow` (as returned by SQLite) into a
+ * domain-friendly `BehaviorLogRecord` with `details_json` parsed.
+ */
+function rowToRecord(row) {
+    let details = {};
+    try {
+        const parsed = JSON.parse(row.details_json || '{}');
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            details = parsed;
+        }
+    }
+    catch {
+        /* fall through to empty object */
+    }
+    return {
+        id: row.id,
+        ts: row.ts,
+        eventType: row.event_type,
+        agent: row.agent,
+        subject: row.subject,
+        taskId: row.task_id,
+        reason: row.reason,
+        amount: row.amount,
+        details,
+    };
+}
+//# sourceMappingURL=agent-behavior-log.service.js.map

package/dist/backend/backend/src/services/observability/agent-behavior-log.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-behavior-log.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/observability/agent-behavior-log.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/observability/agent-behavior-log.singleton.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Lazy singleton accessor for the {@link AgentBehaviorLogService}.
+ *
+ * Why a separate file: F14 wires callsites across the codebase (prompt
+ * builder, slack adapter, deliver endpoint, escalation router) and they
+ * all need a shared, lazily-opened DB handle. The service itself is kept
+ * pure — `agent-behavior-log.service.ts` is intentionally NOT modified
+ * (its constructor surface is the public contract), so this thin wrapper
+ * owns lifecycle (open-on-first-use) and provides a `reset` hook for
+ * tests.
+ *
+ * Best-effort by design: `getAgentBehaviorLogService()` swallows any
+ * construction failure and returns `null`. Callers MUST treat a `null`
+ * result the same way they treat a logged-but-failed `record()` call —
+ * silently continue. Observability writes never break the request path.
+ *
+ * @module services/observability/agent-behavior-log.singleton
+ */
+import { AgentBehaviorLogService, type AgentBehaviorLogServiceOptions } from './agent-behavior-log.service.js';
+/**
+ * Lazily obtain the shared {@link AgentBehaviorLogService} instance.
+ *
+ * The first caller triggers DB open via the service constructor's
+ * default opener options. Subsequent callers receive the same handle.
+ *
+ * Returns `null` if the underlying open failed — callers MUST be
+ * resilient to this and skip the record() call when null.
+ *
+ * @returns The shared service instance or `null` if open failed
+ *
+ * @example
+ * ```ts
+ * const log = getAgentBehaviorLogService();
+ * log?.record({
+ *   type: 'agent.action',
+ *   agent: 'crewly-orc',
+ *   actionType: 'delegate',
+ * });
+ * ```
+ */
+export declare function getAgentBehaviorLogService(): AgentBehaviorLogService | null;
+/**
+ * Override the singleton with a caller-provided service. Used by tests
+ * that need an in-memory DB or a custom time source.
+ *
+ * Calling this with a fresh service replaces the previous one without
+ * closing it — the test owner is responsible for lifecycle. Passing
+ * `null` simulates a DB-unavailable scenario; subsequent `get` calls
+ * return null without attempting to construct a real on-disk service.
+ *
+ * @param svc - Pre-constructed service to install (or `null`)
+ */
+export declare function setAgentBehaviorLogServiceForTesting(svc: AgentBehaviorLogService | null): void;
+/**
+ * Construct a fresh in-memory service and install it as the singleton.
+ * Convenience for tests that just want a working logger without caring
+ * about disk persistence.
+ *
+ * @param options - Forwarded to the service constructor; defaults to
+ *   `{ openOptions: { dbPath: ':memory:' } }`
+ * @returns The newly installed service instance
+ */
+export declare function createInMemoryAgentBehaviorLogServiceForTesting(options?: AgentBehaviorLogServiceOptions): AgentBehaviorLogService;
+/**
+ * Reset the singleton — closes the current handle (if any) and clears
+ * the cache so the next `getAgentBehaviorLogService()` call constructs
+ * a fresh instance.
+ */
+export declare function resetAgentBehaviorLogServiceForTesting(): void;
+//# sourceMappingURL=agent-behavior-log.singleton.d.ts.map

package/dist/backend/backend/src/services/observability/agent-behavior-log.singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-behavior-log.singleton.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/observability/agent-behavior-log.singleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EACL,uBAAuB,EACvB,KAAK,8BAA8B,EACpC,MAAM,iCAAiC,CAAC;AAWzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,IAAI,uBAAuB,GAAG,IAAI,CAmB3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,uBAAuB,GAAG,IAAI,GAClC,IAAI,CAGN;AAED;;;;;;;;GAQG;AACH,wBAAgB,+CAA+C,CAC7D,OAAO,GAAE,8BAAmC,GAC3C,uBAAuB,CASzB;AAED;;;;GAIG;AACH,wBAAgB,sCAAsC,IAAI,IAAI,CAU7D"}

package/dist/backend/backend/src/services/observability/agent-behavior-log.singleton.js

@@ -0,0 +1,121 @@
+/**
+ * Lazy singleton accessor for the {@link AgentBehaviorLogService}.
+ *
+ * Why a separate file: F14 wires callsites across the codebase (prompt
+ * builder, slack adapter, deliver endpoint, escalation router) and they
+ * all need a shared, lazily-opened DB handle. The service itself is kept
+ * pure — `agent-behavior-log.service.ts` is intentionally NOT modified
+ * (its constructor surface is the public contract), so this thin wrapper
+ * owns lifecycle (open-on-first-use) and provides a `reset` hook for
+ * tests.
+ *
+ * Best-effort by design: `getAgentBehaviorLogService()` swallows any
+ * construction failure and returns `null`. Callers MUST treat a `null`
+ * result the same way they treat a logged-but-failed `record()` call —
+ * silently continue. Observability writes never break the request path.
+ *
+ * @module services/observability/agent-behavior-log.singleton
+ */
+import { LoggerService } from '../core/logger.service.js';
+import { AgentBehaviorLogService, } from './agent-behavior-log.service.js';
+let instance = null;
+/**
+ * Tracks whether the singleton has been initialised (either via lazy
+ * construction or a test override). Distinguishes "first call, no
+ * instance yet" from "explicitly set to null" so a test that simulates
+ * DB-unavailable does not silently re-open the real on-disk DB.
+ */
+let initialized = false;
+/**
+ * Lazily obtain the shared {@link AgentBehaviorLogService} instance.
+ *
+ * The first caller triggers DB open via the service constructor's
+ * default opener options. Subsequent callers receive the same handle.
+ *
+ * Returns `null` if the underlying open failed — callers MUST be
+ * resilient to this and skip the record() call when null.
+ *
+ * @returns The shared service instance or `null` if open failed
+ *
+ * @example
+ * ```ts
+ * const log = getAgentBehaviorLogService();
+ * log?.record({
+ *   type: 'agent.action',
+ *   agent: 'crewly-orc',
+ *   actionType: 'delegate',
+ * });
+ * ```
+ */
+export function getAgentBehaviorLogService() {
+    if (initialized)
+        return instance;
+    try {
+        instance = new AgentBehaviorLogService();
+        initialized = true;
+        return instance;
+    }
+    catch (err) {
+        // Lazily-loaded logger so unit tests that don't initialise the
+        // logger system don't crash here.
+        const logger = LoggerService.getInstance().createComponentLogger('AgentBehaviorLogSingleton');
+        logger.warn('Failed to construct AgentBehaviorLogService — telemetry disabled', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        instance = null;
+        initialized = true;
+        return null;
+    }
+}
+/**
+ * Override the singleton with a caller-provided service. Used by tests
+ * that need an in-memory DB or a custom time source.
+ *
+ * Calling this with a fresh service replaces the previous one without
+ * closing it — the test owner is responsible for lifecycle. Passing
+ * `null` simulates a DB-unavailable scenario; subsequent `get` calls
+ * return null without attempting to construct a real on-disk service.
+ *
+ * @param svc - Pre-constructed service to install (or `null`)
+ */
+export function setAgentBehaviorLogServiceForTesting(svc) {
+    instance = svc;
+    initialized = true;
+}
+/**
+ * Construct a fresh in-memory service and install it as the singleton.
+ * Convenience for tests that just want a working logger without caring
+ * about disk persistence.
+ *
+ * @param options - Forwarded to the service constructor; defaults to
+ *   `{ openOptions: { dbPath: ':memory:' } }`
+ * @returns The newly installed service instance
+ */
+export function createInMemoryAgentBehaviorLogServiceForTesting(options = {}) {
+    const merged = {
+        ...options,
+        openOptions: options.openOptions ?? { inMemory: true, skipIntegrityCheck: true },
+    };
+    const svc = new AgentBehaviorLogService(merged);
+    instance = svc;
+    initialized = true;
+    return svc;
+}
+/**
+ * Reset the singleton — closes the current handle (if any) and clears
+ * the cache so the next `getAgentBehaviorLogService()` call constructs
+ * a fresh instance.
+ */
+export function resetAgentBehaviorLogServiceForTesting() {
+    if (instance) {
+        try {
+            instance.close();
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    instance = null;
+    initialized = false;
+}
+//# sourceMappingURL=agent-behavior-log.singleton.js.map

package/dist/backend/backend/src/services/observability/agent-behavior-log.singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-behavior-log.singleton.js","sourceRoot":"","sources":["../../../../../../backend/src/services/observability/agent-behavior-log.singleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EACL,uBAAuB,GAExB,MAAM,iCAAiC,CAAC;AAEzC,IAAI,QAAQ,GAAmC,IAAI,CAAC;AACpD;;;;;GAKG;AACH,IAAI,WAAW,GAAG,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,0BAA0B;IACxC,IAAI,WAAW;QAAE,OAAO,QAAQ,CAAC;IACjC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,uBAAuB,EAAE,CAAC;QACzC,WAAW,GAAG,IAAI,CAAC;QACnB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,+DAA+D;QAC/D,kCAAkC;QAClC,MAAM,MAAM,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,qBAAqB,CAC9D,2BAA2B,CAC5B,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,kEAAkE,EAAE;YAC9E,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC;QAChB,WAAW,GAAG,IAAI,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oCAAoC,CAClD,GAAmC;IAEnC,QAAQ,GAAG,GAAG,CAAC;IACf,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,+CAA+C,CAC7D,UAA0C,EAAE;IAE5C,MAAM,MAAM,GAAmC;QAC7C,GAAG,OAAO;QACV,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE;KACjF,CAAC;IACF,MAAM,GAAG,GAAG,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChD,QAAQ,GAAG,GAAG,CAAC;IACf,WAAW,GAAG,IAAI,CAAC;IACnB,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sCAAsC;IACpD,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC;YACH,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,iBAAiB;QACnB,CAAC;IACH,CAAC;IACD,QAAQ,GAAG,IAAI,CAAC;IAChB,WAAW,GAAG,KAAK,CAAC;AACtB,CAAC"}

package/dist/backend/backend/src/services/observability/agent-behavior-log.types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Agent Behavior Log — event type definitions.
+ *
+ * The behavior log is a single-table append-only event store backing
+ * Crewly's minimal internal metrics. Each entry is a strongly-typed
+ * domain event the platform records for later analysis (delegation
+ * rates, escalation patterns, Slack delivery failures, prompt size
+ * trends).
+ *
+ * Schema lives in `observability-db.ts`. Service API in
+ * `agent-behavior-log.service.ts`.
+ *
+ * @module services/observability/agent-behavior-log.types
+ */
+/**
+ * Canonical event type strings stored in the `event_type` column of
+ * `agent_behavior_log`. Adding a new event type is additive — append a
+ * new constant here AND extend `BehaviorLogEvent` below; do not rename
+ * existing values (downstream digests rely on stable keys).
+ */
+export declare const BEHAVIOR_LOG_EVENT_TYPES: {
+    /** An agent took a top-level action (delegate, implement, ask_human, send_slack, ...). */
+    readonly AGENT_ACTION: "agent.action";
+    /** An agent escalated a decision/issue to a higher level in the chain. */
+    readonly AGENT_ESCALATION: "agent.escalation";
+    /** A Slack message could not be delivered (intended-but-not-sent or API failure). */
+    readonly SLACK_DELIVERY_FAILED: "slack.delivery.failed";
+    /** Snapshot of an agent's compiled prompt size at session/start build time. */
+    readonly PROMPT_SIZE_BYTES: "prompt.size.bytes";
+};
+/** Union of all canonical event-type strings. */
+export type BehaviorLogEventType = (typeof BEHAVIOR_LOG_EVENT_TYPES)[keyof typeof BEHAVIOR_LOG_EVENT_TYPES];
+/**
+ * Vocabulary for `AgentActionEvent.actionType`. Open-ended on purpose —
+ * extending this list is additive, but the four current values cover
+ * the P0 success-metric needs (delegate-first rate, etc.).
+ */
+export type AgentActionType = 'delegate' | 'implement' | 'ask_human' | 'send_slack' | 'review' | 'verify' | 'other';
+/**
+ * One row of `agent_behavior_log` for a top-level agent action.
+ * Fields beyond agent/actionType are optional; callers should provide
+ * `taskId` and `details` whenever known to enrich downstream digests.
+ */
+export interface AgentActionEvent {
+    type: typeof BEHAVIOR_LOG_EVENT_TYPES.AGENT_ACTION;
+    /** Session name of the agent that performed the action. */
+    agent: string;
+    /** Canonical action vocabulary entry. */
+    actionType: AgentActionType;
+    /** Optional related task id (request / work item / spec ticket). */
+    taskId?: string;
+    /** Optional free-form structured details. Stored as JSON. */
+    details?: Record<string, unknown>;
+}
+/** One row for an agent → upstream escalation. */
+export interface AgentEscalationEvent {
+    type: typeof BEHAVIOR_LOG_EVENT_TYPES.AGENT_ESCALATION;
+    /** Session name doing the escalating. */
+    escalatingAgent: string;
+    /** Where the escalation went (session name, "owner", "orchestrator", ...). */
+    escalatedTo: string;
+    /** Short reason — kept short on purpose for digest readability. */
+    reason: string;
+    /** Optional related task id. */
+    taskId?: string;
+    /** Optional structured payload for richer review later. */
+    details?: Record<string, unknown>;
+}
+/** One row for a Slack delivery that did not land. */
+export interface SlackDeliveryFailedEvent {
+    type: typeof BEHAVIOR_LOG_EVENT_TYPES.SLACK_DELIVERY_FAILED;
+    /** Session name that intended to send. */
+    agent: string;
+    /** Slack thread or channel id (free-form — `channel:thread` is fine). */
+    thread: string;
+    /** Reason: 'no_reply_called' | 'api_error' | 'timeout' | other free string. */
+    reason: string;
+    /** Optional structured payload (response body, status code, etc.). */
+    details?: Record<string, unknown>;
+}
+/** One row for a prompt-size sample. */
+export interface PromptSizeBytesEvent {
+    type: typeof BEHAVIOR_LOG_EVENT_TYPES.PROMPT_SIZE_BYTES;
+    /** Session name whose prompt was measured. */
+    agent: string;
+    /** UTF-8 byte size of the compiled prompt. */
+    bytes: number;
+    /** Optional session id discriminator (e.g. registration id). */
+    sessionId?: string;
+    /** Optional structured payload (e.g. component byte breakdown). */
+    details?: Record<string, unknown>;
+}
+/** Discriminated union of every behavior-log event the service accepts. */
+export type BehaviorLogEvent = AgentActionEvent | AgentEscalationEvent | SlackDeliveryFailedEvent | PromptSizeBytesEvent;
+/**
+ * Raw row layout for `agent_behavior_log`. The service translates a
+ * `BehaviorLogEvent` into this shape at insert time and back at read
+ * time. Direct callers should generally use the service API rather than
+ * constructing rows by hand.
+ */
+export interface BehaviorLogRow {
+    /** Auto-increment primary key, populated by SQLite. */
+    id: number;
+    /** ms-since-epoch (UTC) of the recording. */
+    ts: number;
+    /** Discriminator string — one of `BehaviorLogEventType`. */
+    event_type: BehaviorLogEventType;
+    /** Primary actor (agent session name) when applicable. May be empty. */
+    agent: string;
+    /** Optional secondary subject (escalatedTo, thread, etc.). May be empty. */
+    subject: string;
+    /** Optional related task id. May be empty. */
+    task_id: string;
+    /** Optional short reason / actionType / etc. May be empty. */
+    reason: string;
+    /** Numeric metric (e.g. prompt byte size); 0 for non-numeric events. */
+    amount: number;
+    /** JSON-encoded details payload; '{}' when no details supplied. */
+    details_json: string;
+}
+/**
+ * Return true if `value` looks like a known `BehaviorLogEventType`.
+ *
+ * Useful at deserialisation boundaries (e.g. when querying historic
+ * rows) to narrow a generic string into the discriminator union.
+ *
+ * @param value - any string to test
+ */
+export declare function isBehaviorLogEventType(value: string): value is BehaviorLogEventType;
+//# sourceMappingURL=agent-behavior-log.types.d.ts.map

package/dist/backend/backend/src/services/observability/agent-behavior-log.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-behavior-log.types.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/observability/agent-behavior-log.types.ts"],"names":[],"mappings":"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"}