qlogicagent 2.16.6 → 2.16.8

package/dist/types/runtime/infra/feedback-event-store.d.ts

@@ -0,0 +1,179 @@
+export type FeedbackRating = "up" | "down";
+export type FeedbackState = "active" | "retracted" | "replaced";
+export type TelemetryStatus = "complete" | "partial" | "missing";
+export type FeedbackReason = "missed_requirement" | "incomplete" | "broken_file_link_or_panel" | "code_or_test_failed" | "factually_wrong" | "too_verbose" | "too_short" | "wrong_style" | "other";
+export interface FeedbackUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+export interface FeedbackToolSummary {
+    calledTools: string[];
+    failedTools: string[];
+    blockedTools: string[];
+}
+export interface FeedbackFileContext {
+    changedFileCount?: number;
+    changedPathsPreview?: string[];
+    hasTurnFileChanges?: boolean;
+    diffOpenState?: "not_applicable" | "opened" | "failed" | "unknown";
+}
+export interface FeedbackBrowserContext {
+    url?: string;
+    hadToastError?: boolean;
+    visiblePanel?: "chat" | "artifact" | "diff" | "unknown";
+}
+export interface FeedbackEvent {
+    feedbackId: string;
+    rating: FeedbackRating;
+    reason?: FeedbackReason;
+    comment?: string;
+    state: FeedbackState;
+    projectId?: string;
+    sessionId: string;
+    turnId: string;
+    assistantMessageId: string;
+    userId?: string;
+    telemetryStatus: TelemetryStatus;
+    messageRole: "assistant";
+    messagePreview: string;
+    messageHash: string;
+    model?: string;
+    provider?: string;
+    agentMode?: "chat" | "solo" | "product" | "workflow" | "unknown";
+    sourceChannel?: string;
+    usage?: FeedbackUsage;
+    toolSummary?: FeedbackToolSummary;
+    fileContext?: FeedbackFileContext;
+    browserContext?: FeedbackBrowserContext;
+    upload?: {
+        eligible: boolean;
+        uploadedAt?: string;
+        uploadBatchId?: string;
+        redactionVersion?: string;
+    };
+    /**
+     * Local distillation bookkeeping (mini-design §6): records that this event was folded into a
+     * memory proposal, and under which cluster + idempotency key. Observability only — the crash-safe
+     * dedup guard is the store-level idempotency key on the proposal, not this field.
+     */
+    distill?: {
+        proposedAt: string;
+        clusterKey: string;
+        idempotencyKey: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+/** Telemetry-joined + click-time context the handler assembles before persisting. */
+export interface FeedbackContext {
+    telemetryStatus: TelemetryStatus;
+    messagePreview: string;
+    messageHash: string;
+    userId?: string;
+    model?: string;
+    provider?: string;
+    agentMode?: FeedbackEvent["agentMode"];
+    sourceChannel?: string;
+    usage?: FeedbackUsage;
+    toolSummary?: FeedbackToolSummary;
+    fileContext?: FeedbackFileContext;
+    browserContext?: FeedbackBrowserContext;
+}
+export interface FeedbackSubmitInput {
+    rating: FeedbackRating;
+    reason?: FeedbackReason;
+    comment?: string;
+    projectId: string;
+    sessionId: string;
+    turnId: string;
+    assistantMessageId: string;
+    context: FeedbackContext;
+}
+export interface FeedbackStateEntry {
+    turnId: string;
+    assistantMessageId: string;
+    feedbackId: string;
+    rating: FeedbackRating;
+    reason?: FeedbackReason;
+    state: FeedbackState;
+    updatedAt: string;
+}
+export interface FeedbackSummary {
+    total: number;
+    active: number;
+    retracted: number;
+    replaced: number;
+    upCount: number;
+    downCount: number;
+    byReason: Record<string, number>;
+    byModel: Record<string, number>;
+    byAgentMode: Record<string, number>;
+    telemetryStatusCounts: Record<TelemetryStatus, number>;
+}
+export declare function hashMessageContent(content: string): string;
+/**
+ * Create / switch / re-activate the feedback for a turn. Returns the stable feedbackId and the
+ * resulting state. Submitting the SAME rating while already active is a no-op (idempotent retry).
+ */
+export declare function submitFeedback(input: FeedbackSubmitInput): Promise<{
+    feedbackId: string;
+    state: FeedbackState;
+}>;
+/**
+ * Retract the active feedback for a turn (the frontend calls this when the user re-clicks the
+ * already-selected button). Idempotent: retracting when there is nothing active is a no-op.
+ */
+export declare function retractFeedback(input: {
+    projectId: string;
+    turnId: string;
+    feedbackId?: string;
+}): Promise<{
+    ok: boolean;
+    feedbackId?: string;
+    state: FeedbackState | null;
+}>;
+/**
+ * Hydrate feedback state for a session's messages (initial render / refresh). Returns only ACTIVE
+ * feedback (absent = not rated) — the fixed contract per design §8.3, so the UI never has to
+ * interpret retracted/replaced records.
+ */
+export declare function getFeedbackState(input: {
+    projectId: string;
+    sessionId: string;
+    turnIds?: string[];
+    assistantMessageIds?: string[];
+}): Promise<{
+    states: FeedbackStateEntry[];
+}>;
+/** Local single-instance aggregate used by messageFeedback.summary. Raw message text is not returned. */
+export declare function summarizeFeedback(input: {
+    projectId: string;
+    sessionId?: string;
+    since?: string;
+    until?: string;
+}): Promise<FeedbackSummary>;
+/**
+ * Events eligible for cloud upload that have not yet been assigned to a batch (design §10). The
+ * worker redacts + ships these; once assigned a batchId (delivered or queued for retry) they are
+ * skipped until a state change resets the upload marks.
+ */
+export declare function listUploadableFeedback(projectId: string): Promise<FeedbackEvent[]>;
+/** Mark an event as assigned to an in-flight upload batch (queued for retry, not yet delivered). */
+export declare function assignFeedbackBatch(projectId: string, turnId: string, uploadBatchId: string): Promise<void>;
+/** Mark an event as successfully uploaded (stamps uploadedAt + batch + redactionVersion). */
+export declare function markFeedbackUploaded(projectId: string, turnId: string, uploadBatchId: string, redactionVersion: string): Promise<void>;
+/**
+ * Active feedback eligible for memory distillation (mini-design §3.1). Distillation re-clusters the
+ * full active set every sweep; the store-level idempotency key (not a per-event flag) prevents
+ * duplicate proposals, so this intentionally returns ALL active events — already distilled or not.
+ * A newly added active event simply changes a cluster's id set and yields a fresh proposal.
+ */
+export declare function listDistillableFeedback(projectId: string): Promise<FeedbackEvent[]>;
+/** Stamp local distillation bookkeeping on an event (which cluster + idempotency key folded it in). */
+export declare function markFeedbackDistilled(projectId: string, turnId: string, info: {
+    clusterKey: string;
+    idempotencyKey: string;
+}): Promise<void>;
+/** Test helper: read the raw stored event for a turn (including retracted), or null. */
+export declare function __getFeedbackEventForTest(projectId: string, turnId: string): Promise<FeedbackEvent | null>;

package/dist/types/runtime/infra/feedback-outbox.d.ts

@@ -0,0 +1,26 @@
+export type OutboxOp = "uploadBatch";
+export interface OutboxEntry {
+    entryId: string;
+    /** Dedup key — re-enqueuing the same logical op is a no-op (no double upload). */
+    idempotencyKey: string;
+    op: OutboxOp;
+    payload: unknown;
+    attempts: number;
+    createdAt: string;
+    nextAttemptAt: string;
+    lastError?: string;
+}
+/** Enqueue a failed op for retry. Idempotent: an existing entry with the same key is kept as-is. */
+export declare function enqueueOutbox(projectId: string, input: {
+    idempotencyKey: string;
+    op: OutboxOp;
+    payload: unknown;
+}, now?: Date): Promise<OutboxEntry>;
+/** Entries whose backoff window has elapsed and that have not exhausted their retry budget. */
+export declare function listDueOutbox(projectId: string, now?: Date): Promise<OutboxEntry[]>;
+/** Drop a successfully-delivered entry. */
+export declare function removeOutbox(projectId: string, entryId: string): Promise<void>;
+/** Record a failed attempt: bump attempts + schedule the next retry with exponential backoff. */
+export declare function markOutboxFailure(projectId: string, entryId: string, error: string, now?: Date): Promise<void>;
+/** Entries that have exhausted their retry budget — kept for local audit, never re-sent. */
+export declare function listExhaustedOutbox(projectId: string): Promise<OutboxEntry[]>;

package/dist/types/runtime/infra/feedback-redaction.d.ts

@@ -0,0 +1,71 @@
+import type { FeedbackEvent, FeedbackRating, FeedbackReason, FeedbackState, FeedbackToolSummary, FeedbackUsage, TelemetryStatus } from "./feedback-event-store.js";
+/** Bump when the redaction rules change so uploaded samples stay traceable (§8.6/§13). */
+export declare const REDACTION_VERSION = "feedback-redaction-v1";
+export interface RedactedFeedbackEvent {
+    feedbackId: string;
+    rating: FeedbackRating;
+    reason?: FeedbackReason;
+    state: FeedbackState;
+    /** Hashed identity — correlate without exposing local ids (§8.6). */
+    messageHash: string;
+    sessionIdHash: string;
+    projectIdHash?: string;
+    turnIdHash: string;
+    /** ≤500 chars, secrets/emails/absolute-paths scrubbed (§13). */
+    messagePreview: string;
+    model?: string;
+    provider?: string;
+    agentMode?: FeedbackEvent["agentMode"];
+    sourceChannel?: string;
+    usage?: FeedbackUsage;
+    /** Tool names only (never args). */
+    toolSummary?: FeedbackToolSummary;
+    fileContext?: {
+        changedFileCount?: number;
+        hasTurnFileChanges?: boolean;
+        diffOpenState?: "not_applicable" | "opened" | "failed" | "unknown";
+    };
+    browserContext?: {
+        hadToastError?: boolean;
+        visiblePanel?: "chat" | "artifact" | "diff" | "unknown";
+    };
+    telemetryStatus: TelemetryStatus;
+    redactionVersion: string;
+    createdAt: string;
+}
+export interface FeedbackRollup {
+    rollupId: string;
+    periodStart: string;
+    periodEnd: string;
+    total: number;
+    upCount: number;
+    downCount: number;
+    /** Down-vote reason → count. */
+    byReason: Record<string, number>;
+    byModel: Record<string, {
+        up: number;
+        down: number;
+    }>;
+    byAgentMode: Record<string, {
+        up: number;
+        down: number;
+    }>;
+    telemetryStatusCounts: {
+        complete: number;
+        partial: number;
+        missing: number;
+    };
+    redactionVersion: string;
+    createdAt: string;
+}
+/** Truncate to the preview limit and scrub api keys / emails / absolute paths (§13). */
+export declare function sanitizePreview(text: string): string;
+/** Map a local feedback event to its upload-safe redacted form (§8.6/§13). */
+export declare function redactFeedbackEvent(event: FeedbackEvent, redactionVersion?: string): RedactedFeedbackEvent;
+/** Pre-aggregate a batch of local events into a rollup for low-cost trend upload (§10). */
+export declare function aggregateFeedbackRollup(events: FeedbackEvent[], input: {
+    rollupId: string;
+    periodStart: string;
+    periodEnd: string;
+    redactionVersion?: string;
+}): FeedbackRollup;

package/dist/types/runtime/infra/feedback-upload-client.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Feedback upload client — the single HTTP exit that ships redacted feedback to the llmrouter
+ * feedback backend (design §8.6, §9.1 rule 4). The redaction worker calls this directly; the
+ * messageFeedback.uploadBatch RPC wraps it for manual/test triggers.
+ *
+ * Transport mirrors the usage client: append the route to the llmrouter base already injected into
+ * the agent (QLOGIC_LLMROUTER_BASE_URL, e.g. https://www.qlogicagent.com/api) and authenticate with
+ * the injected Bearer QLOGIC_LLMROUTER_ACCESS_TOKEN. Feedback lands at <base>/client/feedback, so a
+ * batch POSTs to <base>/client/feedback/uploadBatch — the contract the llmrouter ingest endpoint
+ * (Phase 3b) implements. No dedicated feedback env: one llmrouter base, like /client/usage.
+ */
+import type { FeedbackRollup, RedactedFeedbackEvent } from "./feedback-redaction.js";
+export interface UploadBatchInput {
+    batchId: string;
+    events: RedactedFeedbackEvent[];
+    rollups: FeedbackRollup[];
+    redactionVersion: string;
+    clientBuild?: string;
+    runtimeVersion?: string;
+    qlogicagentVersion?: string;
+}
+export interface UploadBatchResult {
+    ok: boolean;
+    accepted?: number;
+    status?: number;
+    error?: string;
+    refreshedToken?: boolean;
+}
+/**
+ * Resolve the feedback ingest base, derived from the llmrouter base already injected into the agent
+ * (QLOGIC_LLMROUTER_BASE_URL), mirroring how the usage client reaches /client/usage. Returns
+ * undefined when llmrouter is not configured.
+ */
+export declare function resolveFeedbackUploadBaseUrl(): string | undefined;
+/**
+ * Ship one redacted batch to llmrouter. Fail-soft: an unconfigured base or a transport/HTTP error
+ * returns { ok: false }, so the caller (worker) keeps the events eligible and queues a retry rather
+ * than dropping feedback. Idempotent at the server by batchId + event id (§9.1 rule 5).
+ */
+export declare function uploadFeedbackBatch(input: UploadBatchInput, signal?: AbortSignal): Promise<UploadBatchResult>;

package/dist/types/runtime/infra/feedback-upload-worker.d.ts

@@ -0,0 +1,11 @@
+export interface FeedbackSweepResult {
+    uploaded: number;
+    queued: number;
+    retried: number;
+}
+/**
+ * One feedback upload sweep for a project. Retries due outbox batches, then redacts + ships any
+ * newly uploadable events. Fail-soft: a failed upload is queued in the outbox (its events assigned
+ * the batchId so they are not re-picked) and retried on a later sweep with backoff.
+ */
+export declare function runFeedbackUploadSweep(projectId: string, now?: Date): Promise<FeedbackSweepResult>;

package/dist/types/runtime/infra/project-data-paths.d.ts

@@ -12,11 +12,11 @@
  * central-registry dependency for the storage key. Deleting a project = `rm` projectData/<id>/.
  */
 export { getProjectDataDirById, getProjectDataRoot } from "./agent-paths.js";
-/** `~/.qlogicagent/profiles/<owner>/projectData/<projectId>/` (key = projectId or workspaceDir). */
-export declare function getProjectDataDir(key: string): string;
+/** `~/.qlogicagent/profiles/<owner>/projectData/<projectId>/` for a projectId or workspaceDir. */
+export declare function getProjectDataDir(projectIdOrWorkspaceDir: string): string;
 /** `projectData/<id>/sessions/` */
-export declare function getProjectDataSessionsRoot(key: string): string;
+export declare function getProjectDataSessionsRoot(projectIdOrWorkspaceDir: string): string;
 /** `projectData/<id>/checkpoints/` or `.../checkpoints/<sessionId>` */
-export declare function getProjectDataCheckpointsDir(key: string, sessionId?: string): string;
+export declare function getProjectDataCheckpointsDir(projectIdOrWorkspaceDir: string, sessionId?: string): string;
 /** `projectData/<id>/uploads/` or `.../uploads/<sessionId>` */
-export declare function getProjectDataUploadsDir(key: string, sessionId?: string): string;
+export declare function getProjectDataUploadsDir(projectIdOrWorkspaceDir: string, sessionId?: string): string;

package/dist/types/runtime/infra/turn-baseline-store.d.ts

@@ -0,0 +1,102 @@
+export type TurnBaselineState = "running" | "completed" | "failed" | "cancelled";
+export type FileChangeStatus = "added" | "modified" | "deleted" | "renamed" | "moved" | "copied" | "unchanged";
+export type SnapshotKind = "missing" | "text" | "binary" | "directory" | "too-large";
+export interface FileSnapshot {
+    exists: boolean;
+    kind: SnapshotKind;
+    sizeBytes?: number;
+    sha256?: string;
+    inlineContent?: string;
+    contentRef?: string;
+}
+export interface TurnFileChange {
+    path: string;
+    previousPath?: string;
+    status: FileChangeStatus;
+    additions?: number;
+    deletions?: number;
+    before?: FileSnapshot;
+    after?: FileSnapshot;
+}
+export interface TurnChangeSummary {
+    turnId: string;
+    sessionId: string;
+    projectId: string;
+    state: TurnBaselineState;
+    startedAt: string;
+    completedAt?: string;
+    filesChanged: number;
+    files: TurnFileChange[];
+    truncated?: boolean;
+}
+export declare function resolveProjectRelativePath(projectRoot: string, input: string): string | null;
+export declare function startTurnBaseline(input: {
+    turnId: string;
+    sessionId: string;
+    projectId?: string;
+    workspaceDir?: string;
+    seedPaths?: unknown;
+}): Promise<void>;
+export declare function captureFileBefore(input: {
+    turnId?: string;
+    projectId?: string;
+    workspaceDir?: string;
+    path: string;
+    entryPath?: string;
+    previousPath?: string;
+}): Promise<void>;
+export declare function captureFileAfter(input: {
+    turnId?: string;
+    projectId?: string;
+    workspaceDir?: string;
+    path: string;
+    entryPath?: string;
+    previousPath?: string;
+    status?: FileChangeStatus;
+}): Promise<void>;
+export declare function captureAbsoluteBefore(input: {
+    turnId?: string;
+    workspaceDir: string;
+    absolutePath: string;
+}): Promise<void>;
+export declare function captureAbsoluteAfter(input: {
+    turnId?: string;
+    workspaceDir: string;
+    absolutePath: string;
+    status?: FileChangeStatus;
+}): Promise<void>;
+export declare function finalizeTurnBaseline(input: {
+    turnId: string;
+    state: TurnBaselineState;
+}): Promise<TurnChangeSummary | null>;
+export declare function getTurnBaselineSummary(projectId: string, turnId: string): Promise<TurnChangeSummary | null>;
+export declare function listRecentTurnBaselines(input: {
+    projectId: string;
+    sessionId?: string;
+    limit?: number;
+}): Promise<{
+    summaries: TurnChangeSummary[];
+}>;
+export declare function getTurnBaselineFileBaseline(input: {
+    projectId: string;
+    turnId: string;
+    path: string;
+}): Promise<{
+    path: string;
+    content: string | null;
+    snapshot: FileSnapshot | null;
+}>;
+export declare function getTurnBaselineFileDiff(input: {
+    projectId: string;
+    turnId: string;
+    path: string;
+}): Promise<{
+    path: string;
+    previousPath?: string;
+    status: FileChangeStatus;
+    original: string;
+    modified: string;
+    language?: string;
+    additions?: number;
+    deletions?: number;
+}>;

package/dist/types/runtime/infra/turn-telemetry-store.d.ts

@@ -0,0 +1,59 @@
+export type AgentMode = "chat" | "solo" | "product" | "workflow" | "unknown";
+export interface TurnTelemetryUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+export interface TurnTelemetryToolSummary {
+    calledTools: string[];
+    failedTools: string[];
+    blockedTools: string[];
+}
+export interface TurnTelemetryFileContext {
+    changedFileCount?: number;
+    changedPathsPreview?: string[];
+    hasTurnFileChanges?: boolean;
+}
+export interface TurnTelemetrySnapshot {
+    turnId: string;
+    sessionId: string;
+    projectId?: string;
+    /** Gateway-stamped alias; v1 MUST equal turnId (design §7.3). Set at finalize. */
+    assistantMessageId?: string;
+    model?: string;
+    provider?: string;
+    agentMode?: AgentMode;
+    sourceChannel?: string;
+    usage?: TurnTelemetryUsage;
+    toolSummary?: TurnTelemetryToolSummary;
+    fileContext?: TurnTelemetryFileContext;
+    createdAt: string;
+    finalizedAt?: string;
+}
+/** Fields that can be merged into a turn's telemetry record as the turn progresses. */
+export type TurnTelemetryPatch = Partial<Omit<TurnTelemetrySnapshot, "turnId" | "createdAt" | "finalizedAt" | "assistantMessageId">>;
+/**
+ * Merge a telemetry fragment into the in-memory record for a turn. Pieces (tool summary,
+ * usage/model, file context) arrive at different points in the pipeline and upsert into the
+ * same turnId record. Safe to call before the projectId is known; the first call seeds it.
+ */
+export declare function recordTurnTelemetry(turnId: string, patch: TurnTelemetryPatch): void;
+/**
+ * Flush the accumulated telemetry for a turn to disk and drop it from memory. Returns null
+ * (after dropping the in-memory record) when no projectId resolved — telemetry, like the turn
+ * baseline, is only persisted for turns that belong to a registered project.
+ */
+export declare function finalizeTurnTelemetry(input: {
+    turnId: string;
+    projectId?: string;
+}): Promise<TurnTelemetrySnapshot | null>;
+export declare function getTurnTelemetryRecord(projectId: string, turnId: string): Promise<TurnTelemetrySnapshot | null>;
+export declare function listTurnTelemetryBySession(input: {
+    projectId: string;
+    sessionId?: string;
+    limit?: number;
+}): Promise<{
+    records: TurnTelemetrySnapshot[];
+}>;
+/** Test/maintenance helper: drop any in-memory telemetry not yet finalized. */
+export declare function __resetActiveTurnTelemetryForTest(): void;

package/dist/types/runtime/infra/working-materials-store.d.ts

@@ -0,0 +1,35 @@
+export type WorkingMaterialKind = "workspace" | "instructions" | "generated" | "url";
+export interface WorkingMaterialItem {
+    id: string;
+    projectId: string;
+    sessionId: string;
+    sourceKind: WorkingMaterialKind;
+    path?: string;
+    title: string;
+    viewerHint?: string;
+    pinned: boolean;
+    order: number;
+    addedAt: string;
+    updatedAt: string;
+    missing?: boolean;
+}
+export declare function getWorkingMaterials(projectId: string, sessionId: string): Promise<{
+    items: WorkingMaterialItem[];
+    missing: WorkingMaterialItem[];
+}>;
+export declare function replaceWorkingMaterials(projectId: string, sessionId: string, items: unknown[]): Promise<{
+    ok: true;
+    items: WorkingMaterialItem[];
+}>;
+export declare function upsertWorkingMaterial(projectId: string, sessionId: string, item: unknown): Promise<{
+    ok: true;
+    items: WorkingMaterialItem[];
+}>;
+export declare function removeWorkingMaterial(projectId: string, sessionId: string, id: string): Promise<{
+    ok: true;
+    items: WorkingMaterialItem[];
+}>;
+export declare function reorderWorkingMaterials(projectId: string, sessionId: string, ids: string[]): Promise<{
+    ok: true;
+    items: WorkingMaterialItem[];
+}>;

package/dist/types/runtime/pet/daily-journey-summarizer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Daily journey summarizer — orchestrates the day's local-work summary:
+ *   aggregate → deterministic stats → pet-voice prompt → LLM narrative → JourneySnapshot.
+ *
+ * IO (aggregation, soul, LLM) is injected so this stays unit-testable. The LLM call
+ * signature is declared locally (not imported from cli/pet-runtime) to keep the
+ * runtime layer free of a cli dependency; the caller passes petRuntime.createSmallLLMCall().
+ * If the LLM is unavailable or fails, a deterministic templated narrative is used so the
+ * journey always renders.
+ */
+import type { PetSoul } from "./pet-types.js";
+import type { DayDigest } from "./journey-day-aggregator.js";
+import type { JourneySnapshot } from "./pet-profile-service.js";
+export type JourneyLlmCall = (prompt: string, maxTokens: number) => Promise<string | null>;
+export interface SummarizeDayOptions {
+    date: string;
+    petName: string;
+    aggregate: () => Promise<DayDigest>;
+    resolveSoul: () => PetSoul | null;
+    llmCall: JourneyLlmCall | undefined;
+    generator?: "auto" | "manual";
+    /** Injectable clock (ISO) for deterministic tests. */
+    now?: () => string;
+}
+export declare function summarizeDay(opts: SummarizeDayOptions): Promise<JourneySnapshot | null>;

package/dist/types/runtime/pet/index.d.ts

@@ -12,7 +12,8 @@ export type { PetdexAnimationId, PetdexValidationReport } from "@xiaozhiclaw/pet
 export type { ReactionPool, LLMReactionContext, ReactionStyle } from "@xiaozhiclaw/pet-core";
 export { PetSoulService } from "./pet-soul-service.js";
 export { petReactionEngine } from "./pet-reaction-engine.js";
-export { PetProfileService, type PetProfile, type PetPreferences, type PetdexPetAsset, type PetdexPetAssetSummary, type JourneySnapshot } from "./pet-profile-service.js";
+export { PetProfileService, type PetProfile, type PetPreferences, type PetdexPetAsset, type PetdexPetAssetSummary, type JourneySnapshot, type JourneyStats } from "./pet-profile-service.js";
+export { catchUpJourney, readTurnTelemetryDir, type CatchUpJourneyOptions } from "./journey-catchup.js";
 export { createPetdexAssetFromSpritesheet, listBuiltinPetdexAssetIds, listBuiltinPetdexAssets, writePetdexAssetPackage } from "./petdex-asset.js";
 export { forgePetdexAsset, forgePetdexAssetPackage, readGeneratedPetdexImage } from "./petdex-forge-service.js";
 export { loadPetFile, validatePetManifest, type PetManifest, type PetFileBundle } from "./pet-file-loader.js";

package/dist/types/runtime/pet/journey-catchup.d.ts

@@ -0,0 +1,14 @@
+import type { TurnTelemetrySnapshot } from "../infra/turn-telemetry-store.js";
+import { type JourneyLlmCall } from "./daily-journey-summarizer.js";
+/** All persisted turn-telemetry records for one project (best-effort; missing/corrupt → skip). */
+export declare function readTurnTelemetryDir(projectId: string): TurnTelemetrySnapshot[];
+export interface CatchUpJourneyOptions {
+    /** Look-back window of completed days (default 7, capped at retention). */
+    maxDays?: number;
+    generator?: "auto" | "manual";
+    llmCall: JourneyLlmCall | undefined;
+    listProjectIds: () => string[];
+    log?: (message: string) => void;
+}
+/** Backfill missing completed-day journey snapshots. Returns the dates generated this run. */
+export declare function catchUpJourney(ownerUserId: string, opts: CatchUpJourneyOptions): Promise<string[]>;

package/dist/types/runtime/pet/journey-day-aggregator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Journey day aggregator — collapses a day's turn telemetry (across all of an owner's
+ * projects) into a deterministic DayDigest. IO is injected (project list + per-project
+ * telemetry reader) so this stays pure and unit-testable; the caller wires the real
+ * project store + filesystem reader.
+ *
+ * Stats are computed here deterministically (never by an LLM) so the journey never
+ * shows invented numbers — the LLM only writes the narrative prose from these facts.
+ */
+import type { TurnTelemetrySnapshot } from "../infra/turn-telemetry-store.js";
+export interface DayDigest {
+    date: string;
+    turns: number;
+    filesChanged: number;
+    toolsUsed: string[];
+    projects: string[];
+    models: string[];
+    modes: Record<string, number>;
+    topChangedPaths: string[];
+}
+export interface JourneyDayDeps {
+    /** All registered project ids for the owner. */
+    listProjectIds(): string[];
+    /** All persisted turn-telemetry records for one project (any date). */
+    readProjectTurns(projectId: string): Promise<TurnTelemetrySnapshot[]>;
+}
+export declare function aggregateOwnerDay(date: string, deps: JourneyDayDeps): Promise<DayDigest>;

package/dist/types/runtime/pet/journey-narrative-prompt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Journey narrative prompt — composes the pet-voice prompt from the pet's soul + the
+ * day's deterministic digest. Pure/testable. The LLM only writes prose from these facts;
+ * it is explicitly told not to invent numbers, file names, or events.
+ */
+import type { PetSoul } from "./pet-types.js";
+import type { DayDigest } from "./journey-day-aggregator.js";
+export declare function buildNarrativePrompt(soul: PetSoul | null, digest: DayDigest): string;

package/dist/types/runtime/pet/pet-profile-service.d.ts

@@ -46,12 +46,25 @@ export interface PetdexPetAsset extends Omit<PetdexPetAssetSummary, "atlas"> {
         frame: number;
     };
 }
+export interface JourneyStats {
+    turns: number;
+    filesChanged: number;
+    toolsUsed: string[];
+    projects: string[];
+}
 export interface JourneySnapshot {
     date: string;
     day: number;
     petName: string;
     stateLabel: string;
-    entries: Array<Record<string, unknown>>;
+    /** Pet-voice narrative of the day's local work (LLM-written from deterministic facts). */
+    narrative?: string;
+    /** Deterministic day stats (computed, never LLM-invented). */
+    stats?: JourneyStats;
+    generatedAt?: string;
+    generator?: "auto" | "manual";
+    /** Legacy mock entries — optional, superseded by narrative/stats. */
+    entries?: Array<Record<string, unknown>>;
 }
 export interface PetProfile {
     version: 1;