@vibe-hero/server 0.1.0

package/dist/observation/offers.js

@@ -0,0 +1,327 @@
+/**
+ * @file Offer engine (T035) — cadence + anti-fatigue decision logic.
+ *
+ * This is the brain behind the observation → offer pipeline. It does two
+ * trigger-only jobs (it NEVER scores — FR-005 / SC-003):
+ *
+ *  1. **Match** derived activity signals to candidate topic keys by scanning the
+ *     loaded topics' {@link TriggerSignal}s ({@link matchCandidates}).
+ *  2. **Decide** whether an offer may surface at an end-of-work breakpoint, and
+ *     for which key, honoring the configured cadence and the full anti-fatigue
+ *     stack ({@link resolveOffer}) — within-session decline suppression
+ *     (FR-020), configurable cadence off / per_session / per_topic (FR-020a),
+ *     and cross-session decline backoff + global mute (FR-020b).
+ *
+ * Design: the decision core is **pure**. {@link resolveOffer},
+ * {@link matchCandidates}, {@link applyDecline}, and {@link applyAccept} take
+ * plain state + a `now` timestamp and return plain results — no IO, no clock, no
+ * randomness — so they are trivially testable and deterministic. The tool layer
+ * (`tools/offers.ts`, `tools/recordObservation.ts`) is the thin wrapper that
+ * reads the clock, loads the catalog, and persists via `updateProfile`.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/spec.md (FR-005, FR-015..017,
+ * FR-019/020/020a/020b, SC-003), specs/001-vibe-hero-mvp/data-model.md
+ * (§ OfferLedger), specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`record_observation` / `get_offer` / `record_offer_response`),
+ * src/config.ts (ASSESSMENT_CONFIG.declineMuteThreshold / backoff*).
+ */
+import { ASSESSMENT_CONFIG } from "../config.js";
+import { abilityKey } from "../schemas/common.js";
+/**
+ * Does a single {@link TriggerSignal} match a single {@link ObservedSignal} for
+ * the given tool? A match requires the tool to agree and at least one of the
+ * signal's selectors to hit:
+ *  - `match.toolName` — exact (case-sensitive) equality against `signal.toolName`.
+ *  - `match.toolNamePattern` — regex tested against `signal.toolName`.
+ *  - `match.mcpToolPattern` — regex tested against `signal.mcpTool`.
+ *
+ * A malformed regex pattern fails closed (no match) rather than throwing — a bad
+ * trigger declaration must never crash the observation intake path.
+ */
+const triggerMatchesSignal = (trigger, signal) => {
+    const { match } = trigger;
+    if (match.toolName !== undefined &&
+        signal.toolName !== undefined &&
+        match.toolName === signal.toolName) {
+        return true;
+    }
+    if (match.toolNamePattern !== undefined && signal.toolName !== undefined) {
+        if (safeRegexTest(match.toolNamePattern, signal.toolName))
+            return true;
+    }
+    if (match.mcpToolPattern !== undefined && signal.mcpTool !== undefined) {
+        if (safeRegexTest(match.mcpToolPattern, signal.mcpTool))
+            return true;
+    }
+    return false;
+};
+/** Test `pattern` against `value`, failing closed on an invalid regex. */
+const safeRegexTest = (pattern, value) => {
+    try {
+        return new RegExp(pattern).test(value);
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Match derived signals against the loaded topics' trigger declarations and
+ * return the distinct candidate topics (deduped by {@link AbilityKey}, in
+ * topic-iteration order). Trigger-only (FR-015): this selects *which topic to
+ * offer* and never scores.
+ *
+ * Only triggers whose `tool` equals the observation's `tool` are considered, so
+ * a Claude Code Bash signal never trips a Codex topic. A topic with no matching
+ * trigger is omitted.
+ *
+ * @param topics - The loaded catalog topics (each carrying `triggerSignals`).
+ * @param tool - The host tool the activity belongs to.
+ * @param signals - The derived signals observed this turn.
+ * @returns The distinct offer candidates `{ key, title, reason }`.
+ */
+export const matchCandidates = (topics, tool, signals) => {
+    const candidates = [];
+    const seen = new Set();
+    for (const topic of topics) {
+        const key = abilityKey(topic.class, topic.id);
+        if (seen.has(key))
+            continue;
+        // Find a trigger for THIS tool that some observed signal satisfies.
+        const hit = topic.triggerSignals.find((trigger) => trigger.tool === tool &&
+            signals.some((signal) => triggerMatchesSignal(trigger, signal)));
+        if (hit === undefined)
+            continue;
+        seen.add(key);
+        candidates.push({
+            key,
+            title: topic.title,
+            reason: describeMatch(hit),
+        });
+    }
+    return candidates;
+};
+/** A short, privacy-safe human reason for why a topic became a candidate. */
+const describeMatch = (trigger) => {
+    const { match } = trigger;
+    if (match.toolName !== undefined) {
+        return `Observed ${match.toolName} activity, which exercises this topic.`;
+    }
+    if (match.toolNamePattern !== undefined) {
+        return `Observed tool activity matching this topic's trigger.`;
+    }
+    return `Observed MCP tool activity matching this topic's trigger.`;
+};
+/**
+ * Decide whether an end-of-work offer may surface, and for which key (FR-019
+ * non-interrupting timing is the caller's concern; this is the *whether/which*).
+ *
+ * Gates, in order (first failure wins):
+ *  1. `offerCadence === "off"` ⇒ `offers_off` (FR-020a).
+ *  2. `proactiveOffers === false` ⇒ `offers_off` (master switch, FR-031).
+ *  3. `mutedUntil` in the future ⇒ `cadence` (global mute, FR-020b).
+ *  4. `declinedThisSession` ⇒ `declined` (within-session suppression, FR-020).
+ *  5. `per_session` and an offer already surfaced this session ⇒ `cadence`
+ *     (≤1 offer/session, FR-020a).
+ *  6. No candidate keys at all ⇒ `no_candidate`.
+ *  7. Otherwise pick the first candidate that is BOTH not already offered this
+ *     session under `per_topic` (≤1 per distinct key/session, FR-020a) AND not
+ *     within its cross-session `perTopicNextEligibleAt` backoff window
+ *     (FR-020b). If none survives ⇒ `cadence`.
+ *
+ * Pure: no clock, no IO. `now` is supplied by the caller.
+ *
+ * @param state - The bundled offer state (config flags, ledger, backoff, candidates).
+ * @param now - The current instant, for muted/backoff comparisons.
+ * @returns An {@link OfferDecision}.
+ */
+export const resolveOffer = (state, now) => {
+    const { proactiveOffers, offerCadence, ledger, backoff, candidates } = state;
+    // 1 + 2: offers disabled entirely.
+    if (offerCadence === "off" || !proactiveOffers) {
+        return { kind: "suppressed", reason: "offers_off" };
+    }
+    // 3: global cross-session mute (FR-020b) — N consecutive declines reached.
+    if (isMuted(backoff, now)) {
+        return { kind: "suppressed", reason: "cadence" };
+    }
+    // 4: a decline this session suppresses the rest of the session (FR-020).
+    if (ledger.declinedThisSession) {
+        return { kind: "suppressed", reason: "declined" };
+    }
+    // 5: per_session cap — at most one offer for the whole session (FR-020a).
+    if (offerCadence === "per_session" && ledger.offersThisSession >= 1) {
+        return { kind: "suppressed", reason: "cadence" };
+    }
+    // 6: nothing to offer.
+    if (candidates.length === 0) {
+        return { kind: "suppressed", reason: "no_candidate" };
+    }
+    // 7: pick the first candidate clearing the per-topic + backoff gates.
+    const alreadyOffered = new Set(ledger.offeredTopicKeys);
+    for (const key of candidates) {
+        if (offerCadence === "per_topic" && alreadyOffered.has(key)) {
+            // ≤1 offer per distinct key this session (FR-020a).
+            continue;
+        }
+        if (isBackedOff(backoff, key, now)) {
+            // Within the cross-session re-offer window for this topic (FR-020b).
+            continue;
+        }
+        return { kind: "offer", key };
+    }
+    // Every candidate was per-topic-exhausted or backed off.
+    return { kind: "suppressed", reason: "cadence" };
+};
+/** Is `mutedUntil` set and still in the future at `now`? (Global mute, FR-020b.) */
+const isMuted = (backoff, now) => backoff.mutedUntil !== undefined &&
+    Date.parse(backoff.mutedUntil) > now.getTime();
+/**
+ * Is `key` within its cross-session re-offer backoff window at `now`? A key with
+ * no recorded `perTopicNextEligibleAt` entry is always eligible (FR-020b).
+ */
+const isBackedOff = (backoff, key, now) => {
+    const nextAt = backoff.perTopicNextEligibleAt[key];
+    return nextAt !== undefined && Date.parse(nextAt) > now.getTime();
+};
+/**
+ * The per-session ledger reset to a fresh `sessionId`. The cross-session backoff
+ * is intentionally NOT reset here — it persists across sessions until an accept
+ * resets it (FR-020b). Used by the tool layer when a new session begins.
+ */
+export const freshLedger = (sessionId) => ({
+    sessionId,
+    offersThisSession: 0,
+    declinedThisSession: false,
+    offeredTopicKeys: [],
+    candidateKeys: [],
+});
+/**
+ * Reconcile the persisted ledger with the session being observed/queried. If the
+ * ledger's `sessionId` differs (or is the empty-string sentinel), the previous
+ * session's per-session accounting is stale, so return a {@link freshLedger}.
+ * Otherwise return the ledger unchanged. Pure.
+ *
+ * @param ledger - The persisted per-session ledger.
+ * @param sessionId - The session id of the current request.
+ */
+export const ledgerForSession = (ledger, sessionId) => ledger.sessionId === sessionId ? ledger : freshLedger(sessionId);
+/**
+ * Record that an offer for `key` surfaced this session: bump the per-session
+ * count and add the key to `offeredTopicKeys` (deduped). Pure; the tool layer
+ * persists the result. Called when `get_offer` actually returns an offer so the
+ * cadence caps are enforced on the *next* `get_offer`.
+ */
+export const markOffered = (ledger, key) => ({
+    ...ledger,
+    offersThisSession: ledger.offersThisSession + 1,
+    offeredTopicKeys: ledger.offeredTopicKeys.includes(key)
+        ? ledger.offeredTopicKeys
+        : [...ledger.offeredTopicKeys, key],
+});
+/**
+ * Merge freshly-matched candidate keys into the per-session ledger's candidate
+ * pool (`candidateKeys`) without counting them as offered. `record_observation`
+ * uses this to accumulate candidates across the session as signals arrive;
+ * `get_offer` (which receives no signals) later resolves from this pool. New
+ * candidates are appended in match order, deduped, after the existing pool so
+ * the most-relevant-first ordering of a given turn is preserved. Does NOT touch
+ * `offeredTopicKeys` or `offersThisSession` — a candidate is not an offer until
+ * {@link markOffered}. Pure.
+ *
+ * @param ledger - The per-session ledger (already reconciled to this session).
+ * @param keys - The candidate keys matched this turn (most-relevant first).
+ */
+export const noteCandidates = (ledger, keys) => {
+    const pool = [...ledger.candidateKeys];
+    const seen = new Set(pool);
+    for (const key of keys) {
+        if (!seen.has(key)) {
+            seen.add(key);
+            pool.push(key);
+        }
+    }
+    return { ...ledger, candidateKeys: pool };
+};
+/**
+ * Apply a decline for `key` (FR-020 within-session + FR-020b cross-session).
+ *
+ * Within-session (FR-020): set `declinedThisSession = true` so no further offer
+ * surfaces for the rest of the session.
+ *
+ * Cross-session (FR-020b):
+ *  - increment `consecutiveDeclines`;
+ *  - push `perTopicNextEligibleAt[key]` out by an exponential backoff:
+ *    `backoffBaseHours * backoffFactor^(consecutiveDeclines - 1)` hours from
+ *    `now`, so each successive decline lengthens the re-offer interval;
+ *  - once `consecutiveDeclines >= declineMuteThreshold`, set a global
+ *    `mutedUntil` far in the future (offers globally muted until the user
+ *    re-enables — modeled as a long horizon derived from the backoff).
+ *
+ * Pure: `now` and config are inputs; the tool layer persists the result.
+ *
+ * @param ledger - The current per-session ledger (for this session).
+ * @param backoff - The current cross-session backoff.
+ * @param key - The declined topic key.
+ * @param now - The decline instant.
+ * @param config - Tunables (decline mute threshold + backoff base/factor).
+ * @returns The updated ledger + backoff.
+ */
+export const applyDecline = (ledger, backoff, key, now, config = ASSESSMENT_CONFIG) => {
+    const consecutiveDeclines = backoff.consecutiveDeclines + 1;
+    // Exponential per-topic backoff: base * factor^(n-1) hours from now.
+    const backoffHours = config.backoffBaseHours *
+        Math.pow(config.backoffFactor, consecutiveDeclines - 1);
+    const nextEligibleAt = addHours(now, backoffHours).toISOString();
+    const perTopicNextEligibleAt = {
+        ...backoff.perTopicNextEligibleAt,
+        [key]: nextEligibleAt,
+    };
+    // Global mute once the threshold is hit (FR-020b). Horizon: a generously long
+    // multiple of the current backoff so offers stay muted until the user
+    // re-enables / requests one.
+    const muted = consecutiveDeclines >= config.declineMuteThreshold;
+    const mutedUntil = muted
+        ? addHours(now, backoffHours * MUTE_HORIZON_MULTIPLIER).toISOString()
+        : backoff.mutedUntil;
+    const nextBackoff = {
+        consecutiveDeclines,
+        perTopicNextEligibleAt,
+        ...(mutedUntil !== undefined ? { mutedUntil } : {}),
+    };
+    const nextLedger = {
+        ...ledger,
+        declinedThisSession: true,
+    };
+    return { ledger: nextLedger, backoff: nextBackoff };
+};
+/**
+ * Multiplier applied to the current per-topic backoff to derive the global mute
+ * horizon when the decline threshold is reached. A large multiple models
+ * "muted until the user re-enables" without an unbounded/never-parses date.
+ */
+const MUTE_HORIZON_MULTIPLIER = 1000;
+/**
+ * Apply an accept (FR-020b): reset `consecutiveDeclines` to 0 and clear the
+ * global `mutedUntil`. Per-topic backoff entries are left as-is (an accept on
+ * one topic does not retroactively un-back-off unrelated topics, but the global
+ * counter/mute reset means the user is engaged again). The per-session ledger is
+ * unchanged by an accept. Pure.
+ *
+ * @param backoff - The current cross-session backoff.
+ * @returns The reset backoff.
+ */
+export const applyAccept = (backoff) => ({
+    consecutiveDeclines: 0,
+    perTopicNextEligibleAt: backoff.perTopicNextEligibleAt,
+    // mutedUntil intentionally dropped (cleared).
+});
+/**
+ * Apply a defer (FR-020): a defer is treated as "ask me later" — it does NOT
+ * count as a decline (no backoff increment, no within-session decline flag) and
+ * does NOT reset the consecutive-decline counter. The state is returned
+ * unchanged so the next end-of-work breakpoint may re-offer normally. Pure.
+ */
+export const applyDefer = (ledger, backoff) => ({ ledger, backoff });
+/** Add `hours` to a `Date`, returning a new `Date`. */
+const addHours = (base, hours) => new Date(base.getTime() + hours * 3_600_000);
+//# sourceMappingURL=offers.js.map

package/dist/observation/offers.js.map

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

package/dist/observation/source.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @file Observation source abstraction (FR-015/016).
+ *
+ * Observation is **trigger-only**: a source yields derived, privacy-safe
+ * {@link ObservationEvent}s that say *a topic was exercised*, used solely to
+ * populate offer candidates. Observation NEVER scores (FR-005, SC-003) and
+ * NEVER persists raw prompts, tool inputs, or tool outputs (FR-018, SC-008).
+ *
+ * The {@link ObservationSource} interface is the seam (FR-016) behind which any
+ * provenance can live — a real-time Claude Code hook
+ * ({@link ./hookEvents.js#HookSource}), a future transcript-backfill source, or
+ * the always-available {@link SelfReportSource} manual path. The rest of the
+ * system depends only on this interface, so adding a source needs no redesign.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/spec.md (FR-015..018),
+ * specs/001-vibe-hero-mvp/data-model.md (§ ObservationEvent),
+ * specs/001-vibe-hero-mvp/research.md (§ Observation & hook correlation).
+ */
+import { type ObservationEvent } from "../schemas/profile.js";
+import { type AbilityKey, type ToolId } from "../schemas/common.js";
+/**
+ * A provenance of derived observation signals (FR-016).
+ *
+ * Two complementary entry points so every concrete source fits, regardless of
+ * how its raw signal arrives:
+ *
+ * - {@link poll} — for sources that accumulate signals out-of-band (e.g. a hook
+ *   writing to a buffer, or a transcript reader) and are *drained* on demand.
+ *   Returns and clears whatever has been observed since the last poll.
+ * - {@link record} — for sources handed a single raw payload synchronously
+ *   (e.g. one hook invocation, or an explicit self-report) and asked to derive
+ *   events from it immediately.
+ *
+ * A concrete source MAY implement only the entry point natural to it; the other
+ * defaults to yielding nothing. Both return only privacy-safe
+ * {@link ObservationEvent}s — never raw payload fields (FR-018).
+ */
+export interface ObservationSource {
+    /**
+     * Stable identifier for the source kind, for diagnostics/telemetry routing.
+     * Examples: `"self-report"`, `"claude-code-hook"`, `"transcript-backfill"`.
+     */
+    readonly kind: string;
+    /**
+     * Drain accumulated derived events. Implementations that push via
+     * {@link record} (or have no buffer) return an empty array.
+     *
+     * @returns the privacy-safe events observed since the previous poll.
+     */
+    poll(): Promise<readonly ObservationEvent[]>;
+    /**
+     * Derive zero or more privacy-safe events from a single raw payload.
+     *
+     * Implementations MUST treat `raw` as untrusted `unknown`, validate
+     * defensively, and copy ONLY derived signals — never `tool_input`,
+     * `tool_output`, or any nested raw content (FR-018).
+     *
+     * @param raw - an untrusted, source-specific payload.
+     * @returns the privacy-safe events derived from `raw` (possibly empty).
+     */
+    record(raw: unknown): readonly ObservationEvent[];
+}
+/**
+ * Explicit input for the manual self-report path. The user (or the host agent
+ * on their behalf) states outright that one or more topics were exercised; no
+ * telemetry is involved, so this path ALWAYS works (FR-016, SC-011).
+ */
+export interface SelfReport {
+    /** The host tool the activity belongs to. */
+    readonly tool: ToolId;
+    /**
+     * The topic ability keys the user reports exercising (e.g. produced from
+     * {@link abilityKey}). At least one is expected; an empty list yields no
+     * event.
+     */
+    readonly topicKeys: readonly AbilityKey[];
+    /**
+     * Whether the reported activity succeeded. Self-report defaults to `true`
+     * (the user is asserting they did the thing); pass `false` to report a
+     * failed/abandoned attempt. Note: success is trigger metadata only and never
+     * affects scoring (FR-005).
+     */
+    readonly success?: boolean;
+    /**
+     * Optional correlation id for this report. Defaults to a generated
+     * `self-report:<timestamp>` token; self-report has no upstream id to align
+     * with (FR-017 correlation applies to hook↔transcript, not this path).
+     */
+    readonly correlationId?: string;
+}
+/**
+ * Manual, always-available observation source (FR-016, SC-011).
+ *
+ * Produces an {@link ObservationEvent} from an explicit {@link SelfReport} with
+ * no telemetry whatsoever — the canonical fallback when no hook/transcript
+ * source is present (Edge: "No telemetry available"). Because the input is
+ * already a set of derived `topicKeys`, there is nothing raw to leak; the event
+ * is still re-validated against {@link ObservationEventSchema} before it leaves.
+ *
+ * @example
+ * const src = new SelfReportSource();
+ * const events = src.record({
+ *   tool: "claude-code",
+ *   topicKeys: [abilityKey({ kind: "tool", tool: "claude-code" }, "subagents")],
+ * });
+ */
+export declare class SelfReportSource implements ObservationSource {
+    private readonly now;
+    readonly kind = "self-report";
+    /**
+     * @param now - clock for the event timestamp / default correlation id,
+     *   injectable for deterministic tests. Defaults to `Date.now`-backed
+     *   {@link Date}.
+     */
+    constructor(now?: () => Date);
+    /**
+     * Self-report is push-only via {@link record}; there is no buffer to drain.
+     */
+    poll(): Promise<readonly ObservationEvent[]>;
+    /**
+     * Derive a single {@link ObservationEvent} from an explicit {@link SelfReport}.
+     *
+     * Returns an empty array when the report names no topics. The returned event
+     * carries only derived fields and is schema-validated before return.
+     *
+     * @param raw - expected to satisfy {@link SelfReport}; validated defensively.
+     * @throws {Error} if `raw` is not a well-formed self-report.
+     */
+    record(raw: unknown): readonly ObservationEvent[];
+    /** Defensive structural validation of an untrusted self-report payload. */
+    private parseReport;
+}
+//# sourceMappingURL=source.d.ts.map

package/dist/observation/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/observation/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,MAAM,EAAc,MAAM,sBAAsB,CAAC;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,IAAI,IAAI,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAC;IAE7C;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,gBAAgB,EAAE,CAAC;CACnD;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,UAAU,EAAE,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IAQrC,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPvC,SAAgB,IAAI,iBAAiB;IAErC;;;;OAIG;gBACiC,GAAG,GAAE,MAAM,IAAuB;IAEtE;;OAEG;IACI,IAAI,IAAI,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC;IAInD;;;;;;;;OAQG;IACI,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,gBAAgB,EAAE;IAkBxD,2EAA2E;IAC3E,OAAO,CAAC,WAAW;CA0BpB"}

package/dist/observation/source.js

@@ -0,0 +1,105 @@
+/**
+ * @file Observation source abstraction (FR-015/016).
+ *
+ * Observation is **trigger-only**: a source yields derived, privacy-safe
+ * {@link ObservationEvent}s that say *a topic was exercised*, used solely to
+ * populate offer candidates. Observation NEVER scores (FR-005, SC-003) and
+ * NEVER persists raw prompts, tool inputs, or tool outputs (FR-018, SC-008).
+ *
+ * The {@link ObservationSource} interface is the seam (FR-016) behind which any
+ * provenance can live — a real-time Claude Code hook
+ * ({@link ./hookEvents.js#HookSource}), a future transcript-backfill source, or
+ * the always-available {@link SelfReportSource} manual path. The rest of the
+ * system depends only on this interface, so adding a source needs no redesign.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/spec.md (FR-015..018),
+ * specs/001-vibe-hero-mvp/data-model.md (§ ObservationEvent),
+ * specs/001-vibe-hero-mvp/research.md (§ Observation & hook correlation).
+ */
+import { ObservationEventSchema, } from "../schemas/profile.js";
+/**
+ * Manual, always-available observation source (FR-016, SC-011).
+ *
+ * Produces an {@link ObservationEvent} from an explicit {@link SelfReport} with
+ * no telemetry whatsoever — the canonical fallback when no hook/transcript
+ * source is present (Edge: "No telemetry available"). Because the input is
+ * already a set of derived `topicKeys`, there is nothing raw to leak; the event
+ * is still re-validated against {@link ObservationEventSchema} before it leaves.
+ *
+ * @example
+ * const src = new SelfReportSource();
+ * const events = src.record({
+ *   tool: "claude-code",
+ *   topicKeys: [abilityKey({ kind: "tool", tool: "claude-code" }, "subagents")],
+ * });
+ */
+export class SelfReportSource {
+    now;
+    kind = "self-report";
+    /**
+     * @param now - clock for the event timestamp / default correlation id,
+     *   injectable for deterministic tests. Defaults to `Date.now`-backed
+     *   {@link Date}.
+     */
+    constructor(now = () => new Date()) {
+        this.now = now;
+    }
+    /**
+     * Self-report is push-only via {@link record}; there is no buffer to drain.
+     */
+    poll() {
+        return Promise.resolve([]);
+    }
+    /**
+     * Derive a single {@link ObservationEvent} from an explicit {@link SelfReport}.
+     *
+     * Returns an empty array when the report names no topics. The returned event
+     * carries only derived fields and is schema-validated before return.
+     *
+     * @param raw - expected to satisfy {@link SelfReport}; validated defensively.
+     * @throws {Error} if `raw` is not a well-formed self-report.
+     */
+    record(raw) {
+        const report = this.parseReport(raw);
+        if (report.topicKeys.length === 0) {
+            return [];
+        }
+        const timestamp = this.now().toISOString();
+        const event = {
+            tool: report.tool,
+            topicKeys: [...report.topicKeys],
+            success: report.success ?? true,
+            timestamp,
+            correlationId: report.correlationId ?? `self-report:${timestamp}`,
+        };
+        // Re-validate the derived event; this is the privacy boundary's final
+        // checkpoint (the schema has no fields for raw payload content).
+        return [ObservationEventSchema.parse(event)];
+    }
+    /** Defensive structural validation of an untrusted self-report payload. */
+    parseReport(raw) {
+        if (typeof raw !== "object" || raw === null) {
+            throw new Error("SelfReportSource.record: expected a SelfReport object");
+        }
+        const obj = raw;
+        const tool = obj["tool"];
+        const topicKeys = obj["topicKeys"];
+        if (typeof tool !== "string") {
+            throw new Error("SelfReportSource.record: 'tool' must be a ToolId string");
+        }
+        if (!Array.isArray(topicKeys)) {
+            throw new Error("SelfReportSource.record: 'topicKeys' must be an array of AbilityKey");
+        }
+        const success = obj["success"];
+        const correlationId = obj["correlationId"];
+        return {
+            tool: tool,
+            topicKeys: topicKeys,
+            ...(typeof success === "boolean" ? { success } : {}),
+            ...(typeof correlationId === "string" && correlationId.length > 0
+                ? { correlationId }
+                : {}),
+        };
+    }
+}
+//# sourceMappingURL=source.js.map

package/dist/observation/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/observation/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAEL,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AA6E/B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,gBAAgB;IAQS;IAPpB,IAAI,GAAG,aAAa,CAAC;IAErC;;;;OAIG;IACH,YAAoC,MAAkB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;QAAlC,QAAG,GAAH,GAAG,CAA+B;IAAG,CAAC;IAE1E;;OAEG;IACI,IAAI;QACT,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM,CAAC,GAAY;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAqB;YAC9B,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,SAAS,EAAE,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC;YAChC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;YAC/B,SAAS;YACT,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,eAAe,SAAS,EAAE;SAClE,CAAC;QACF,sEAAsE;QACtE,iEAAiE;QACjE,OAAO,CAAC,sBAAsB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,2EAA2E;IACnE,WAAW,CAAC,GAAY;QAC9B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,GAAG,GAAG,GAA8B,CAAC;QAC3C,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;QACzB,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC;QACnC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC7E,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,qEAAqE,CACtE,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;QAC/B,MAAM,aAAa,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC;QAC3C,OAAO;YACL,IAAI,EAAE,IAAc;YACpB,SAAS,EAAE,SAAyB;YACpC,GAAG,CAAC,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,GAAG,CAAC,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC;gBAC/D,CAAC,CAAC,EAAE,aAAa,EAAE;gBACnB,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;IACJ,CAAC;CACF"}