@vibe-hero/server 0.1.0

package/dist/index.js

@@ -0,0 +1,91 @@
+/**
+ * @file vibe-hero MCP server entry point (T020).
+ *
+ * Bootstraps a stdio MCP server (`@modelcontextprotocol/sdk`) named `vibe-hero`
+ * with a `tools` capability, then registers all 10 tools from
+ * {@link TOOL_REGISTRY}. Each tool's handler is wrapped with the first-run setup
+ * gate (T021, {@link withSetupGate}) and adapted from its plain-JSON result into
+ * the SDK's `CallToolResult` shape ({@link toCallToolResult}).
+ *
+ * The SDK idiom (sdk 1.29.0): construct {@link McpServer}, then call
+ * `registerTool(name, { description, inputSchema }, cb)`. `registerTool` expects
+ * `inputSchema` as a *raw Zod shape* (`Record<string, ZodType>`), so we pass the
+ * registry's `inputSchema.shape` and the SDK hands the callback the parsed,
+ * validated args. Transport is {@link StdioServerTransport}.
+ *
+ * Importing this module never starts the server; only running it as the process
+ * entrypoint does (see the `import.meta.url` guard at the bottom), so tests can
+ * import {@link createServer} freely.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md, plan.md.
+ */
+import { fileURLToPath } from "node:url";
+import { argv } from "node:process";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TOOL_REGISTRY } from "./tools/placeholders.js";
+import { withSetupGate } from "./tools/gate.js";
+import { toCallToolResult } from "./tools/types.js";
+/** Server name advertised to MCP hosts. Matches the product/skill namespace. */
+export const SERVER_NAME = "vibe-hero";
+/** Server version advertised to MCP hosts. */
+export const SERVER_VERSION = "0.1.0";
+/**
+ * Register one tool module on an {@link McpServer}, gating its handler and
+ * adapting the JSON result to a `CallToolResult`. Pulled out so both production
+ * and tests register tools the same way; `dirOverride` flows to the gate's
+ * profile lookup as a test seam.
+ *
+ * @param server - The MCP server to register onto.
+ * @param tool - The tool module from {@link TOOL_REGISTRY}.
+ * @param dirOverride - Profile-directory override (test seam) for the gate.
+ */
+export const registerToolModule = (server, tool, dirOverride) => {
+    const gated = withSetupGate(tool.name, tool.handler, dirOverride);
+    server.registerTool(tool.name, {
+        description: tool.description,
+        // `registerTool` wants a raw Zod shape, not a wrapped object schema.
+        inputSchema: tool.inputSchema.shape,
+    }, async (args) => toCallToolResult(await gated(args)));
+};
+/**
+ * Construct the vibe-hero MCP server with all tools registered (gated). Does not
+ * connect a transport — call {@link main} (or wire your own transport) to start.
+ *
+ * @param dirOverride - Profile-directory override (test seam) for the gate.
+ * @returns A configured, not-yet-connected {@link McpServer}.
+ */
+export const createServer = (dirOverride) => {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    for (const tool of TOOL_REGISTRY) {
+        registerToolModule(server, tool, dirOverride);
+    }
+    return server;
+};
+/**
+ * Start the server over stdio. Connects a {@link StdioServerTransport} and
+ * resolves once connected; the process then stays alive serving tool calls.
+ */
+export const main = async () => {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+};
+/**
+ * Entrypoint guard: only auto-start when this module is the process entrypoint
+ * (`node .../index.js`), not when imported by tests. Compares the resolved
+ * module path to `argv[1]`.
+ */
+const isEntrypoint = () => {
+    const entry = argv[1];
+    if (entry === undefined)
+        return false;
+    return fileURLToPath(import.meta.url) === entry;
+};
+if (isEntrypoint()) {
+    main().catch((err) => {
+        process.stderr.write(`vibe-hero: fatal error starting MCP server: ${String(err)}\n`);
+        process.exitCode = 1;
+    });
+}
+//# 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;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEpC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAsB,MAAM,kBAAkB,CAAC;AAExE,gFAAgF;AAChF,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC;AAEvC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,MAAiB,EACjB,IAAmB,EACnB,WAAoB,EACd,EAAE;IACR,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAClE,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;QACE,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,qEAAqE;QACrE,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK;KACpC,EACD,KAAK,EAAE,IAAa,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAC7D,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,WAAoB,EAAa,EAAE;IAC9D,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,EAC9C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,kBAAkB,CAAC,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;IAC5C,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,YAAY,GAAG,GAAY,EAAE;IACjC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC;AAClD,CAAC,CAAC;AAEF,IAAI,YAAY,EAAE,EAAE,CAAC;IACnB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+CAA+C,MAAM,CAAC,GAAG,CAAC,IAAI,CAC/D,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/observation/hookEvents.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @file Hook-payload → derived-signal extraction (FR-018, SC-008).
+ *
+ * Privacy boundary. A Claude Code `PostToolUse` hook payload carries
+ * `session_id`, `transcript_path`, `cwd`, `tool_name`, `tool_input`,
+ * `tool_output` (a.k.a. `tool_response`), and `tool_use_id` (research.md
+ * § Observation). The user's raw prompts, command lines, file contents, and
+ * tool outputs live inside `tool_input` / `tool_output`.
+ *
+ * {@link extractSignals} reads ONLY the privacy-safe fields — `tool_name`,
+ * derived `success`, a `timestamp`, and `tool_use_id` — and MUST NEVER copy,
+ * return, or persist `tool_input` or `tool_output` (or any nested raw content).
+ * `success` is *derived* from the shape of the output (exit code / error
+ * presence) WITHOUT retaining the output itself. The payload is untrusted
+ * `unknown` and is validated defensively.
+ *
+ * This module does NOT do topic matching: a {@link DerivedSignal} carries no
+ * `topicKeys`. Mapping signals → topics against `TriggerSignal` declarations
+ * happens later in `record_observation`. Keeping extraction topic-free makes
+ * the privacy contract — "no raw field ever leaves this function" — auditable
+ * in one place (see test/unit/privacy.test.ts).
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/spec.md (FR-015..018, E4),
+ * specs/001-vibe-hero-mvp/research.md (§ Observation & hook correlation).
+ */
+import { type ObservationEvent } from "../schemas/profile.js";
+import { type ToolId } from "../schemas/common.js";
+import { type ObservationSource } from "./source.js";
+/**
+ * The privacy-safe projection of a single hook event. Deliberately NARROW:
+ * exactly the four fields the offer engine needs, and nothing derived from the
+ * raw input/output content.
+ *
+ * Note there is no `topicKeys` here — topic attribution is a later step
+ * (`record_observation`) and is intentionally out of scope for extraction.
+ */
+export interface DerivedSignal {
+    /** The host tool name reported by the hook (e.g. `"Bash"`, `"Edit"`). */
+    readonly toolName: string;
+    /**
+     * Whether the tool call succeeded, *derived* from the output shape (exit
+     * code / error presence) without retaining the output. Trigger metadata
+     * only — never a scoring signal (FR-005).
+     */
+    readonly success: boolean;
+    /** ISO-8601 extraction timestamp. */
+    readonly timestamp: string;
+    /**
+     * The hook's `tool_use_id`, the shared id that aligns a hook event with the
+     * transcript's `tool_use`/`tool_result` blocks for deterministic correlation
+     * (FR-017). `undefined` when the payload omits it.
+     */
+    readonly toolUseId: string | undefined;
+}
+/**
+ * Extract privacy-safe {@link DerivedSignal}s from an untrusted hook payload.
+ *
+ * Reads ONLY `tool_name`, a derived `success`, a `timestamp`, and
+ * `tool_use_id`. NEVER reads, copies, returns, or persists `tool_input` or
+ * `tool_output`/`tool_response` (FR-018, SC-008). A payload missing `tool_name`
+ * yields no signal (nothing actionable to attribute).
+ *
+ * @param hookPayload - an untrusted `PostToolUse` hook payload.
+ * @param now - clock for the extraction timestamp, injectable for tests.
+ *   Defaults to `Date.now`-backed {@link Date}.
+ * @returns zero or one derived signal (array for forward-compatibility with
+ *   batched payloads).
+ */
+export declare const extractSignals: (hookPayload: unknown, now?: () => Date) => DerivedSignal[];
+/**
+ * {@link ObservationSource} wrapper over the Claude Code hook (FR-016).
+ *
+ * Buffers derived events as hook payloads arrive (via {@link record}) and
+ * drains them on {@link poll}. Topic attribution is NOT done here: because a
+ * {@link DerivedSignal} has no topics, this wrapper produces a *minimal*
+ * {@link ObservationEvent} with an empty `topicKeys` array — the downstream
+ * `record_observation` step matches signals to topics against `TriggerSignal`
+ * declarations and fills in the real keys. Keeping that out of the privacy
+ * boundary preserves the single-responsibility extraction contract.
+ *
+ * The buffer holds only already-derived, privacy-safe events; no raw payload is
+ * ever retained.
+ */
+export declare class HookSource implements ObservationSource {
+    private readonly tool;
+    private readonly now;
+    readonly kind = "claude-code-hook";
+    private readonly buffer;
+    /**
+     * @param tool - the host tool these hook events belong to (Claude Code in
+     *   v1). Stamped onto each derived {@link ObservationEvent}.
+     * @param now - clock for timestamps, injectable for deterministic tests.
+     */
+    constructor(tool?: ToolId, now?: () => Date);
+    /** Drain and clear the buffered derived events. */
+    poll(): Promise<readonly ObservationEvent[]>;
+    /**
+     * Derive privacy-safe events from one hook payload, buffer them, and return
+     * them. The returned events carry an empty `topicKeys` (filled downstream).
+     *
+     * @param raw - an untrusted `PostToolUse` hook payload.
+     */
+    record(raw: unknown): readonly ObservationEvent[];
+    /**
+     * Project a {@link DerivedSignal} into a minimal {@link ObservationEvent}.
+     * `topicKeys` is intentionally empty here (attribution is downstream). The
+     * `tool_use_id` becomes the correlation id when present, else a synthetic
+     * `hook:<timestamp>` token (FR-017 correlation needs the real id; absence is
+     * tolerated). Re-validated against the schema, which has no raw-content field.
+     */
+    private toEvent;
+}
+//# sourceMappingURL=hookEvents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hookEvents.d.ts","sourceRoot":"","sources":["../../src/observation/hookEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AA2DD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GACzB,aAAa,OAAO,EACpB,MAAK,MAAM,IAAuB,KACjC,aAAa,EAyBf,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAW,YAAW,iBAAiB;IAWhD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAXtB,SAAgB,IAAI,sBAAsB;IAE1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IAEjD;;;;OAIG;gBAEgB,IAAI,GAAE,MAAsB,EAC5B,GAAG,GAAE,MAAM,IAAuB;IAGrD,mDAAmD;IAC5C,IAAI,IAAI,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC;IAKnD;;;;;OAKG;IACI,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,gBAAgB,EAAE;IAQxD;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;CAWhB"}

package/dist/observation/hookEvents.js

@@ -0,0 +1,170 @@
+/**
+ * @file Hook-payload → derived-signal extraction (FR-018, SC-008).
+ *
+ * Privacy boundary. A Claude Code `PostToolUse` hook payload carries
+ * `session_id`, `transcript_path`, `cwd`, `tool_name`, `tool_input`,
+ * `tool_output` (a.k.a. `tool_response`), and `tool_use_id` (research.md
+ * § Observation). The user's raw prompts, command lines, file contents, and
+ * tool outputs live inside `tool_input` / `tool_output`.
+ *
+ * {@link extractSignals} reads ONLY the privacy-safe fields — `tool_name`,
+ * derived `success`, a `timestamp`, and `tool_use_id` — and MUST NEVER copy,
+ * return, or persist `tool_input` or `tool_output` (or any nested raw content).
+ * `success` is *derived* from the shape of the output (exit code / error
+ * presence) WITHOUT retaining the output itself. The payload is untrusted
+ * `unknown` and is validated defensively.
+ *
+ * This module does NOT do topic matching: a {@link DerivedSignal} carries no
+ * `topicKeys`. Mapping signals → topics against `TriggerSignal` declarations
+ * happens later in `record_observation`. Keeping extraction topic-free makes
+ * the privacy contract — "no raw field ever leaves this function" — auditable
+ * in one place (see test/unit/privacy.test.ts).
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/spec.md (FR-015..018, E4),
+ * specs/001-vibe-hero-mvp/research.md (§ Observation & hook correlation).
+ */
+import { ObservationEventSchema, } from "../schemas/profile.js";
+/** Narrow `value` to a plain object record, else `undefined`. */
+const asRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+/** Read a string field if present and non-empty, else `undefined`. */
+const readString = (obj, key) => {
+    const v = obj[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+};
+/**
+ * Derive success from the tool output WITHOUT copying it.
+ *
+ * Heuristics, in order (any matched branch decides):
+ * 1. an explicit boolean `success` flag,
+ * 2. a numeric `exit_code` / `exitCode` (`0` ⇒ success),
+ * 3. presence of an `error` / `is_error` / `isError` marker (⇒ failure),
+ * 4. otherwise assume success (absence of an error signal).
+ *
+ * Only a boolean is ever returned; no field of `rawOutput` is retained.
+ *
+ * @param rawOutput - the untrusted `tool_output` / `tool_response` value.
+ */
+const deriveSuccess = (rawOutput) => {
+    const out = asRecord(rawOutput);
+    if (out === undefined) {
+        // No structured output (or a bare scalar/array): nothing signals failure.
+        return true;
+    }
+    if (typeof out["success"] === "boolean") {
+        return out["success"];
+    }
+    const exit = out["exit_code"] ?? out["exitCode"];
+    if (typeof exit === "number") {
+        return exit === 0;
+    }
+    const isError = out["is_error"] ?? out["isError"];
+    if (typeof isError === "boolean") {
+        return !isError;
+    }
+    const err = out["error"];
+    if (err !== undefined && err !== null && err !== false && err !== "") {
+        return false;
+    }
+    return true;
+};
+/**
+ * Extract privacy-safe {@link DerivedSignal}s from an untrusted hook payload.
+ *
+ * Reads ONLY `tool_name`, a derived `success`, a `timestamp`, and
+ * `tool_use_id`. NEVER reads, copies, returns, or persists `tool_input` or
+ * `tool_output`/`tool_response` (FR-018, SC-008). A payload missing `tool_name`
+ * yields no signal (nothing actionable to attribute).
+ *
+ * @param hookPayload - an untrusted `PostToolUse` hook payload.
+ * @param now - clock for the extraction timestamp, injectable for tests.
+ *   Defaults to `Date.now`-backed {@link Date}.
+ * @returns zero or one derived signal (array for forward-compatibility with
+ *   batched payloads).
+ */
+export const extractSignals = (hookPayload, now = () => new Date()) => {
+    const payload = asRecord(hookPayload);
+    if (payload === undefined) {
+        return [];
+    }
+    const toolName = readString(payload, "tool_name");
+    if (toolName === undefined) {
+        return [];
+    }
+    // `tool_output` is the documented field; some hook versions / docs use
+    // `tool_response`. We read it ONLY to derive a boolean and immediately drop
+    // the reference — its content is never copied into the result.
+    const success = deriveSuccess(payload["tool_output"] ?? payload["tool_response"]);
+    const signal = {
+        toolName,
+        success,
+        timestamp: now().toISOString(),
+        toolUseId: readString(payload, "tool_use_id"),
+    };
+    return [signal];
+};
+/**
+ * {@link ObservationSource} wrapper over the Claude Code hook (FR-016).
+ *
+ * Buffers derived events as hook payloads arrive (via {@link record}) and
+ * drains them on {@link poll}. Topic attribution is NOT done here: because a
+ * {@link DerivedSignal} has no topics, this wrapper produces a *minimal*
+ * {@link ObservationEvent} with an empty `topicKeys` array — the downstream
+ * `record_observation` step matches signals to topics against `TriggerSignal`
+ * declarations and fills in the real keys. Keeping that out of the privacy
+ * boundary preserves the single-responsibility extraction contract.
+ *
+ * The buffer holds only already-derived, privacy-safe events; no raw payload is
+ * ever retained.
+ */
+export class HookSource {
+    tool;
+    now;
+    kind = "claude-code-hook";
+    buffer = [];
+    /**
+     * @param tool - the host tool these hook events belong to (Claude Code in
+     *   v1). Stamped onto each derived {@link ObservationEvent}.
+     * @param now - clock for timestamps, injectable for deterministic tests.
+     */
+    constructor(tool = "claude-code", now = () => new Date()) {
+        this.tool = tool;
+        this.now = now;
+    }
+    /** Drain and clear the buffered derived events. */
+    poll() {
+        const drained = this.buffer.splice(0, this.buffer.length);
+        return Promise.resolve(drained);
+    }
+    /**
+     * Derive privacy-safe events from one hook payload, buffer them, and return
+     * them. The returned events carry an empty `topicKeys` (filled downstream).
+     *
+     * @param raw - an untrusted `PostToolUse` hook payload.
+     */
+    record(raw) {
+        const events = extractSignals(raw, this.now).map((signal) => this.toEvent(signal));
+        this.buffer.push(...events);
+        return events;
+    }
+    /**
+     * Project a {@link DerivedSignal} into a minimal {@link ObservationEvent}.
+     * `topicKeys` is intentionally empty here (attribution is downstream). The
+     * `tool_use_id` becomes the correlation id when present, else a synthetic
+     * `hook:<timestamp>` token (FR-017 correlation needs the real id; absence is
+     * tolerated). Re-validated against the schema, which has no raw-content field.
+     */
+    toEvent(signal) {
+        const topicKeys = [];
+        const event = {
+            tool: this.tool,
+            topicKeys,
+            success: signal.success,
+            timestamp: signal.timestamp,
+            correlationId: signal.toolUseId ?? `hook:${signal.timestamp}`,
+        };
+        return ObservationEventSchema.parse(event);
+    }
+}
+//# sourceMappingURL=hookEvents.js.map

package/dist/observation/hookEvents.js.map

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

package/dist/observation/offers.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @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 { type AbilityKey } from "../schemas/common.js";
+import type { Config, OfferBackoff, OfferLedger } from "../schemas/profile.js";
+import type { Topic } from "../schemas/content.js";
+import type { OfferCandidate } from "../schemas/tools.js";
+/**
+ * A single derived activity signal as accepted by `record_observation`. Mirrors
+ * the privacy-safe {@link DerivedSignal} projection — `toolName` (host tool name
+ * e.g. `"Bash"`), an optional `mcpTool` (an MCP tool name e.g.
+ * `"mcp__github__create_pr"`), an optional derived `success`, and an optional
+ * `toolUseId` for correlation. Trigger-only: success/ids never affect scoring.
+ */
+export interface ObservedSignal {
+    readonly toolName?: string;
+    readonly mcpTool?: string;
+    readonly success?: boolean;
+    readonly toolUseId?: string;
+}
+/**
+ * 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 declare const matchCandidates: (topics: readonly Topic[], tool: Config["toolsLearning"][number], signals: readonly ObservedSignal[]) => OfferCandidate[];
+/**
+ * Why an offer was suppressed, mirroring the `get_offer` contract's
+ * `suppressed` enum. `cadence` covers the per_session / per_topic exhaustion and
+ * the cross-session backoff/mute cases.
+ */
+export type SuppressionReason = "offers_off" | "declined" | "cadence" | "no_candidate";
+/** A resolved offer decision: either a chosen key, or a suppression reason. */
+export type OfferDecision = {
+    readonly kind: "offer";
+    readonly key: AbilityKey;
+} | {
+    readonly kind: "suppressed";
+    readonly reason: SuppressionReason;
+};
+/**
+ * The full state the pure {@link resolveOffer} decision needs. Bundles the
+ * relevant config flags, the current per-session ledger, the cross-session
+ * backoff, and the ordered candidate keys (most-relevant first) for the session.
+ */
+export interface OfferState {
+    /** Master proactive-offers switch (FR-031); `false` ⇒ never offer. */
+    readonly proactiveOffers: boolean;
+    /** Configured cadence (FR-020a). */
+    readonly offerCadence: Config["offerCadence"];
+    /** The current per-session offer ledger (anti-fatigue, FR-020/020a). */
+    readonly ledger: OfferLedger;
+    /** Cross-session decline backoff + global mute (FR-020b). */
+    readonly backoff: OfferBackoff;
+    /**
+     * Candidate keys eligible this turn, most-relevant first. Typically the
+     * `offeredTopicKeys` accumulated by `record_observation`, or freshly matched
+     * candidates. `resolveOffer` picks the first key that survives every gate.
+     */
+    readonly candidates: readonly AbilityKey[];
+}
+/**
+ * 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 declare const resolveOffer: (state: OfferState, now: Date) => OfferDecision;
+/**
+ * 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 declare const freshLedger: (sessionId: string) => OfferLedger;
+/**
+ * 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 declare const ledgerForSession: (ledger: OfferLedger, sessionId: string) => OfferLedger;
+/**
+ * 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 declare const markOffered: (ledger: OfferLedger, key: AbilityKey) => OfferLedger;
+/**
+ * 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 declare const noteCandidates: (ledger: OfferLedger, keys: readonly AbilityKey[]) => OfferLedger;
+/**
+ * The result of applying a decline to the cross-session backoff (FR-020b): the
+ * updated per-session ledger (decline flag set, suppressing the rest of the
+ * session per FR-020) AND the updated cross-session backoff (consecutive count
+ * bumped, this topic's next-eligible time pushed out by exponential backoff,
+ * and a global mute set once `declineMuteThreshold` is reached).
+ */
+export interface DeclineResult {
+    readonly ledger: OfferLedger;
+    readonly backoff: OfferBackoff;
+}
+/**
+ * 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 declare const applyDecline: (ledger: OfferLedger, backoff: OfferBackoff, key: AbilityKey, now: Date, config?: {
+    declineMuteThreshold: number;
+    backoffBaseHours: number;
+    backoffFactor: number;
+}) => DeclineResult;
+/**
+ * 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 declare const applyAccept: (backoff: OfferBackoff) => OfferBackoff;
+/**
+ * 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 declare const applyDefer: (ledger: OfferLedger, backoff: OfferBackoff) => DeclineResult;
+//# sourceMappingURL=offers.d.ts.map

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

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