qlogicagent 2.13.3 → 2.13.5

package/dist/runtime/pet/petdex-forge-service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/pet/petdex-forge-service.test.js

@@ -0,0 +1,142 @@
+import { createCanvas } from "@napi-rs/canvas";
+import { describe, expect, it } from "vitest";
+import { PETDEX_ANIMATION_IDS, PETDEX_ATLAS_CONTRACT } from "./petdex-asset.js";
+import { isHatchPetAvailable } from "./hatch-pet-runner.js";
+import { forgePetdexAsset } from "./petdex-forge-service.js";
+// running-left is derived from running-right by the vendored mirror script, so it
+// is the one row the forge never asks the generator to produce.
+const GENERATED_ROWS = PETDEX_ANIMATION_IDS.filter((id) => id !== "running-left");
+describe("forgePetdexAsset (Hatch-Pet pipeline)", () => {
+    it("drives the vendored Python pipeline into a contract-valid atlas, deriving running-left", async () => {
+        if (!(await isHatchPetAvailable())) {
+            // No Pillow-capable python in this environment: the forge must refuse
+            // up front with an actionable error rather than burn generation budget.
+            await expect(forgePetdexAsset({ name: "Degrade", description: "no python here", prompt: "x" }, async (request) => ({ mediaUrls: [`data:image/png;base64,${(await fakeStrip(request)).toString("base64")}`], model: "test" }))).rejects.toThrow(/Python with Pillow/i);
+            return;
+        }
+        const requests = [];
+        const result = await forgePetdexAsset({ name: "Pika", description: "A compact yellow electric desktop pet", prompt: "Pika" }, async (request) => {
+            requests.push(request);
+            return {
+                mediaUrls: [`data:image/png;base64,${(await fakeStrip(request)).toString("base64")}`],
+                model: "test-image-model",
+                size: request.size,
+                provider: "test",
+                billingUnit: "per_call",
+                billingQuantity: 1,
+            };
+        });
+        // One base reference + one generation per non-derived row.
+        expect(requests).toHaveLength(1 + GENERATED_ROWS.length);
+        expect(requests[0]).toMatchObject({ purpose: "petdex-reference", n: 1 });
+        const rowRequests = requests.slice(1);
+        expect(rowRequests.map((request) => request.animationId)).toEqual([...GENERATED_ROWS]);
+        expect(rowRequests.every((request) => request.purpose === "petdex-row-strip")).toBe(true);
+        // The layout guide is never sent to the model (providers copy its slot
+        // boxes); rows ground on the canonical-base identity reference instead.
+        expect(rowRequests.every((request) => !request.referenceImages?.some((image) => image.role === "layout-guide"))).toBe(true);
+        expect(rowRequests.every((request) => request.imageUrl === request.referenceImages?.find((image) => image.role === "canonical-reference")?.imageUrl)).toBe(true);
+        // Prompts come from the Python prompt files, not a TS builder.
+        expect(requests[0].prompt).toContain("Codex pet");
+        expect(rowRequests[0].prompt).toContain("horizontal animation strip");
+        // The composed atlas honours the Codex contract and passes manifest validation.
+        expect(result.asset.atlas).toMatchObject(PETDEX_ATLAS_CONTRACT);
+        expect(result.validation.valid).toBe(true);
+        expect(result.spritesheet.length).toBeGreaterThan(0);
+        // Provenance covers the base + every row (including the derived running-left).
+        expect(result.productionRun).toMatchObject({ status: "complete", sourceMode: "text" });
+        expect(result.productionRun.jobs).toHaveLength(1 + PETDEX_ANIMATION_IDS.length);
+        expect(result.productionRun.jobs[0]).toMatchObject({ id: "base-reference", kind: "reference" });
+        const derived = result.productionRun.jobs.find((job) => job.animationId === "running-left");
+        expect(derived?.prompt).toMatch(/derived: framewise-horizontal-mirror/);
+        expect(result.mediaUsage).toMatchObject({ provider: "test" });
+    }, 240_000);
+    it("repairs only the row that fails QA, using its retry prompt, then validates", async () => {
+        if (!(await isHatchPetAvailable()))
+            return;
+        const wavingPrompts = [];
+        let wavingCalls = 0;
+        const result = await forgePetdexAsset({ name: "Healer", description: "A pet whose waving row needs one repair", prompt: "Healer" }, async (request) => {
+            const failing = request.animationId === "waving";
+            if (failing) {
+                wavingCalls++;
+                wavingPrompts.push(request.prompt);
+            }
+            // The waving row's FIRST attempt is too sparse to pass inspect; the
+            // retry (and every other row) is a normal extractable strip.
+            const strip = failing && wavingCalls === 1 ? await fakeSparseStrip(request) : await fakeStrip(request);
+            return { mediaUrls: [`data:image/png;base64,${strip.toString("base64")}`], model: "test", provider: "test", billingUnit: "per_call", billingQuantity: 1 };
+        });
+        // waving was generated twice: the initial attempt + exactly one repair.
+        expect(wavingCalls).toBe(2);
+        expect(wavingPrompts[0]).toContain("horizontal animation strip"); // initial prompt
+        expect(wavingPrompts[1]).toContain("Create Codex pet row"); // retry prompt
+        expect(result.validation.valid).toBe(true);
+    }, 240_000);
+    it("regenerates a vision-QA-rejected candidate (multi-candidate), then validates", async () => {
+        if (!(await isHatchPetAvailable()))
+            return;
+        const genCount = new Map();
+        let inspectN = 0;
+        const result = await forgePetdexAsset({ name: "Vision", description: "A pet whose first candidate is vision-rejected", prompt: "Vision" }, async (request) => {
+            const key = request.purpose === "petdex-reference" ? "base" : (request.animationId ?? "?");
+            genCount.set(key, (genCount.get(key) ?? 0) + 1);
+            return { mediaUrls: [`data:image/png;base64,${(await fakeStrip(request)).toString("base64")}`], model: "test", provider: "test", billingUnit: "per_call", billingQuantity: 1 };
+        }, {
+            candidates: 2,
+            inspectImage: async ({ prompt }) => {
+                // Final contact-sheet QA always passes; reject only the very first
+                // per-image candidate to exercise the multi-candidate retry.
+                if (/contact sheet|9 animation rows/i.test(prompt))
+                    return "verdict=PASS\nrepair_rows=none";
+                inspectN++;
+                return inspectN === 1 ? "FAIL: first candidate rejected for test" : "PASS";
+            },
+        });
+        expect(result.validation.valid).toBe(true);
+        // The base's first candidate was vision-rejected, so a second base candidate
+        // was generated and accepted; rows pass on their first candidate.
+        expect(genCount.get("base")).toBe(2);
+        // With vision QA on, running-left is generated (not mirrored).
+        expect(genCount.get("running-left")).toBe(1);
+    }, 240_000);
+});
+// Per-state frame counts (Codex contract); the row strip is generated at the
+// provider-accepted wide size, not the frame count, so the fake must look this
+// up by animation id rather than infer it from request.size.
+const FRAME_COUNTS = {
+    idle: 6, "running-right": 8, "running-left": 8, waving: 4, jumping: 5, failed: 8, waiting: 6, running: 6, review: 6,
+};
+/**
+ * Synthesise a chroma-key image the vendored pipeline can extract: a flat
+ * magenta (#FF00FF, the no-reference fallback key) background with one clearly
+ * separated dark shape per frame slot (rows) or one centred shape (base).
+ */
+async function fakeStrip(request) {
+    if (request.purpose !== "petdex-row-strip")
+        return paintMagenta(2048, 2048, 1);
+    return paintMagenta(4096, 1024, FRAME_COUNTS[request.animationId ?? ""] ?? 6);
+}
+/** A strip whose per-slot shapes are far too small to pass inspect_frames (< min-used-pixels). */
+async function fakeSparseStrip(request) {
+    return paintMagenta(4096, 1024, FRAME_COUNTS[request.animationId ?? ""] ?? 6, 4);
+}
+function paintMagenta(width, height, frames, radius) {
+    const canvas = createCanvas(width, height);
+    const ctx = canvas.getContext("2d");
+    ctx.fillStyle = "#ff00ff";
+    ctx.fillRect(0, 0, width, height);
+    const slot = width / frames;
+    for (let frame = 0; frame < frames; frame++) {
+        const cx = frame * slot + slot / 2;
+        const cy = height / 2;
+        ctx.fillStyle = "#4aa3ff";
+        ctx.beginPath();
+        if (radius)
+            ctx.arc(cx, cy, radius, 0, Math.PI * 2); // sparse: ~50px << 400
+        else
+            ctx.ellipse(cx, cy, slot * 0.3, height * 0.32, 0, 0, Math.PI * 2);
+        ctx.fill();
+    }
+    return Buffer.from(canvas.toBuffer("image/png"));
+}

package/dist/runtime/ports/agent-execution-contracts.d.ts

@@ -0,0 +1,182 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { ChatMessage as WireChatMessage, ToolDefinition as WireToolDefinition, WireTokenUsage } from "../../protocol/wire/index.js";
+export type ChatMessage = WireChatMessage;
+export type TokenUsage = WireTokenUsage;
+export interface ToolDefinition extends WireToolDefinition {
+    backfillObservableInput?: (input: Record<string, unknown>) => void;
+}
+export type TurnEvent = {
+    type: "start";
+    turnId: string;
+} | {
+    type: "delta";
+    turnId: string;
+    text: string;
+} | {
+    type: "tool_call";
+    turnId: string;
+    callId: string;
+    name: string;
+    arguments: string;
+    inputSummary?: string;
+} | {
+    type: "end";
+    turnId: string;
+    content: string;
+    usage?: TokenUsage;
+    model?: string;
+    provider?: string;
+} | {
+    type: "error";
+    turnId: string;
+    error: string;
+    code?: string;
+    usage?: TokenUsage;
+} | {
+    type: "skill_instruction";
+    turnId: string;
+    instruction: unknown;
+} | {
+    type: "tool_result";
+    turnId: string;
+    callId: string;
+    name: string;
+    ok: boolean;
+    error?: string;
+    outputPreview?: string;
+    durationMs?: number;
+    exitCode?: number;
+    stdout?: string;
+    stderr?: string;
+    details?: Record<string, unknown>;
+} | {
+    type: "tool_blocked";
+    turnId: string;
+    callId: string;
+    name: string;
+    reason: string;
+} | {
+    type: "recovery";
+    turnId: string;
+    action: string;
+    detail?: string;
+} | {
+    type: "plan_update";
+    turnId: string;
+    slug: string;
+    content: string;
+} | {
+    type: "heartbeat";
+    turnId: string;
+    message: string;
+} | {
+    type: "tool_use_summary";
+    turnId: string;
+    summary: string;
+} | {
+    type: "reasoning_delta";
+    turnId: string;
+    text: string;
+} | {
+    type: "suggestions";
+    turnId: string;
+    items: Array<{
+        text: string;
+        icon?: string;
+        action?: string;
+    }>;
+} | {
+    type: "media_result";
+    turnId: string;
+    mediaType: "image" | "tts" | "video" | "music" | "3d";
+    url: string;
+    model?: string;
+    provider?: string;
+    durationSeconds?: number;
+    width?: number;
+    height?: number;
+    mimeType?: string;
+    billingUnit?: string;
+    billingQuantity?: number;
+    taskId?: string;
+} | {
+    type: "artifact";
+    turnId: string;
+    artifactId: string;
+    artifactType: "code" | "file" | "image" | "document" | "diagram" | "table";
+    title: string;
+    filePath?: string;
+    language?: string;
+    content?: string;
+    mimeType?: string;
+} | {
+    type: "annotations";
+    turnId: string;
+    annotations: Array<{
+        type: string;
+        url?: string;
+        title?: string;
+        [key: string]: unknown;
+    }>;
+} | {
+    type: "subagent_started";
+    turnId: string;
+    subagentId: string;
+    agentType: string;
+    prompt?: string;
+} | {
+    type: "subagent_ended";
+    turnId: string;
+    subagentId: string;
+    agentType: string;
+    ok: boolean;
+    outputPreview?: string;
+    error?: string;
+};
+export interface ToolInvoker {
+    invoke(turnId: string, name: string, args: string, signal?: AbortSignal): Promise<{
+        result: string;
+        error?: string;
+        toolReferences?: string[];
+        imageUrls?: string[];
+        details?: Record<string, unknown>;
+    }>;
+}
+export interface AgentRunRequest {
+    turnId: string;
+    sessionId: string;
+    messages: ChatMessage[];
+    tools: ToolDefinition[];
+    systemPrompt?: string;
+    config?: {
+        model?: string;
+        apiKey?: string;
+        temperature?: number;
+        maxOutputTokens?: number;
+        parentDepth?: number;
+    };
+}
+export interface ForkedAgentRunner {
+    run(request: AgentRunRequest, signal?: AbortSignal): AsyncIterable<TurnEvent>;
+}
+export interface ForkedAgentRunnerFactory {
+    (params: {
+        transport: unknown;
+        apiKey: string;
+        toolInvoker: ToolInvoker;
+        log: AgentLogger;
+        hooks?: HookRegistry;
+        maxRounds?: number;
+    }): ForkedAgentRunner;
+}
+export interface AgentLogger {
+    info(message: string): void;
+    info(obj: Record<string, unknown>, message: string): void;
+    warn(message: string): void;
+    warn(obj: Record<string, unknown>, message: string): void;
+    error(message: string): void;
+    error(obj: Record<string, unknown>, message: string): void;
+    debug(message: string): void;
+    debug(obj: Record<string, unknown>, message: string): void;
+}
+export type { HookRegistry };

package/dist/runtime/ports/agent-execution-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/ports/agent-runtime-ports.d.ts

@@ -0,0 +1,76 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { OpenAiToolCall } from "./tool-call-contracts.js";
+import type { AgentLogger, ToolDefinition, ToolInvoker } from "./agent-execution-contracts.js";
+export interface RecallCategoryHint {
+    preferred: string[];
+    deprioritized: string[];
+}
+export interface RuntimeCompressibleMessage {
+    role: string;
+    content?: string | unknown;
+}
+export interface RuntimeCompressionResult {
+    messages: RuntimeCompressibleMessage[];
+    droppedCount: number;
+    tokensFreed?: number;
+    strategy: string;
+}
+export interface ToolExecutionResultPort {
+    callId: string;
+    toolName: string;
+    ok: boolean;
+    error?: string;
+    blocked?: boolean;
+    blockReason?: string;
+    durationMs?: number;
+    details?: Record<string, unknown>;
+    message: unknown;
+}
+export interface StreamingToolExecutorPort {
+    addTool(toolCall: OpenAiToolCall): void;
+    getRemainingResults(): AsyncIterable<ToolExecutionResultPort>;
+}
+export interface StreamingToolExecutorPortConfig {
+    toolInvoker: ToolInvoker;
+    hooks?: HookRegistry;
+    sessionId: string;
+    turnId: string;
+    log: AgentLogger;
+    signal?: AbortSignal;
+    maxConcurrentTools?: number;
+}
+export interface ContextCompressionEnginePort {
+    compressAsync(messages: RuntimeCompressibleMessage[], budget: number, context: {
+        model: string;
+        sessionId: string;
+    }): Promise<RuntimeCompressionResult>;
+}
+export interface ToolLoopRuntimePorts {
+    createContentReplacementState(): unknown;
+    enforceToolResultBudget(messages: Array<{
+        role: string;
+        content?: string | unknown;
+        tool_call_id?: string;
+    }>, state: unknown, sessionId: string): Promise<{
+        messages: unknown[];
+        newlyReplacedCount: number;
+    }>;
+    getActiveContextCompressionEngine(): ContextCompressionEnginePort | null;
+    compressMessages(messages: RuntimeCompressibleMessage[], options: {
+        budget: number;
+        model: string;
+    }): RuntimeCompressionResult;
+    getBudgetContinuationMessage(usagePct: number, totalUsed: number, tokenBudget: number): string;
+    createStreamingToolExecutor(config: StreamingToolExecutorPortConfig): StreamingToolExecutorPort;
+    resolveToolEligibility(tools: ToolDefinition[], context: unknown): {
+        eligibleTools: ToolDefinition[];
+        blockedTools: Array<{
+            toolName: string;
+        }>;
+    };
+}
+export interface AgentRuntimePorts {
+    toolLoop: ToolLoopRuntimePorts;
+    detectRecallCategories(query: string): RecallCategoryHint;
+    resolveModelForPurpose(purpose: "smallModel" | string): string | null;
+}

package/dist/runtime/ports/agent-runtime-ports.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/ports/checkpoint-contracts.d.ts

@@ -0,0 +1,19 @@
+export interface Checkpoint {
+    id: string;
+    message: string;
+    timestamp: string;
+    fileCount: number;
+}
+export interface CheckpointResult {
+    success: boolean;
+    checkpoint?: Checkpoint;
+    checkpoints?: Checkpoint[];
+    diff?: string;
+    error?: string;
+}
+export interface CheckpointBackend {
+    createCheckpoint(message?: string): Promise<CheckpointResult>;
+    listCheckpoints(): Promise<CheckpointResult>;
+    restoreCheckpoint(checkpointId: string, paths?: string[]): Promise<CheckpointResult>;
+    diffCheckpoint(checkpointId: string): Promise<CheckpointResult>;
+}

package/dist/runtime/ports/checkpoint-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/ports/config-port.d.ts

@@ -0,0 +1,4 @@
+export interface ConfigPort {
+    get(key: string): string | undefined;
+}
+export declare function createRecordConfigPort(values: Record<string, string | undefined>): ConfigPort;

package/dist/runtime/ports/config-port.js

@@ -0,0 +1,5 @@
+export function createRecordConfigPort(values) {
+    return {
+        get: (key) => values[key],
+    };
+}

package/dist/runtime/ports/index.d.ts

@@ -0,0 +1,19 @@
+export type { MemoryWriter, MemoryWriteMetadata } from "./memory-writer.js";
+export type { MemoryRecallSource } from "./memory-recall-source.js";
+export type { MemoryProvider, MemorySearchOptions, MemorySearchResult, MemoryIngestMessage, MemoryIngestOptions, MemoryExtractionItem, MemoryConsolidationWriteResult, MemoryLearningSink, MemoryToolLocalProvider, MemoryActivitySummary, MemoryAtlasRecord, MemoryAtlasResult, MemoryUpdatePatch, MemoryHandlerProvider, MemoryDreamProvider, MemoryDecayProvider, MemoryRuntimeHookProvider, MemoryToolProvider, MemoryDreamRuntimeProvider, } from "./memory-provider.js";
+export type { PathService } from "./path-service.js";
+export type { ConfigPort } from "./config-port.js";
+export { createRecordConfigPort } from "./config-port.js";
+export { PERMISSION_MODES, } from "./permission-contracts.js";
+export type { ApprovalRequest, ApprovalResponse, PermissionApprovalResolver, PermissionBehavior, PermissionConfig, PermissionDecisionReason, PermissionEngineConfig, PermissionMetadataResolver, PermissionMode, PermissionRiskLevel, PermissionResult, PermissionRuleEnginePort, PermissionRuleEntry, ToolPermissionCheckInput, } from "./permission-contracts.js";
+export type { ProjectMemoryFileInfo, ProjectMemoryResult, ProjectMemoryStore, ProjectMemoryStoreFactory, } from "./project-memory-store.js";
+export type { RuntimeToolContract, ToolBootstrap, ToolBootstrapConfig, ToolBootstrapProvider, ToolBootstrapProviderContext, ToolBootstrapProgress, ToolCatalog, ToolRegistrationModule, ToolRegistrationModuleKind, } from "./tool-contracts.js";
+export { defineToolRegistrationModule } from "./tool-contracts.js";
+export type { Checkpoint, CheckpointBackend, CheckpointResult } from "./checkpoint-contracts.js";
+export type { WorktreeBackend, WorktreeInfo, WorktreeResult } from "./worktree-contracts.js";
+export type { WebSearchBackend, WebSearchOutput, WebSearchResult } from "./web-search-contracts.js";
+export { buildToolResultMessage, type OpenAiToolCall, type ToolResultMessageInput } from "./tool-call-contracts.js";
+export type { AgentLogger, AgentRunRequest, ChatMessage, ForkedAgentRunner, ForkedAgentRunnerFactory, HookRegistry, TokenUsage, ToolDefinition, ToolInvoker, TurnEvent, } from "./agent-execution-contracts.js";
+export type { AccumulatedToolCall, LLMChunk, LLMRequest, LLMTransport, } from "./model-transport-contracts.js";
+export { accumulateToolCalls } from "./model-transport-contracts.js";
+export type { AgentRuntimePorts, ContextCompressionEnginePort, RecallCategoryHint, RuntimeCompressibleMessage, RuntimeCompressionResult, StreamingToolExecutorPort, StreamingToolExecutorPortConfig, ToolExecutionResultPort, ToolLoopRuntimePorts, } from "./agent-runtime-ports.js";

package/dist/runtime/ports/index.js

@@ -0,0 +1,5 @@
+export { createRecordConfigPort } from "./config-port.js";
+export { PERMISSION_MODES, } from "./permission-contracts.js";
+export { defineToolRegistrationModule } from "./tool-contracts.js";
+export { buildToolResultMessage } from "./tool-call-contracts.js";
+export { accumulateToolCalls } from "./model-transport-contracts.js";

package/dist/runtime/ports/memory-provider.d.ts

@@ -0,0 +1,181 @@
+import type { MemoryWriter } from "./memory-writer.js";
+export interface MemorySearchOptions {
+    limit?: number;
+    minScore?: number;
+    preferredCategories?: string[];
+    llmConfig?: unknown;
+}
+export interface MemorySearchResult {
+    blockId: string;
+    id?: string;
+    path?: string;
+    text: string;
+    content?: string;
+    score: number;
+    source?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface MemoryIngestMessage {
+    role: string;
+    content: string;
+    timestamp?: number;
+}
+export interface MemoryIngestOptions {
+    llmConfig?: unknown;
+    source?: string;
+    sessionId?: string;
+}
+export interface MemoryExtractionItem {
+    text: string;
+    category?: string;
+    importance?: number;
+    confidence?: number;
+    source?: string;
+    event_date?: string;
+    tags?: string[];
+    /** Ids of already-uploaded attachments to link to this memory on commit. */
+    attachmentIds?: string[];
+}
+export interface MemoryConsolidationWriteResult {
+    memoriesAdded?: number;
+    observationsAdded?: number;
+    proposalsAdded?: number;
+    claimsAdded?: number;
+    conflictsAdded?: number;
+    claimIds?: string[];
+    conflictIds?: string[];
+}
+export interface MemoryProvider {
+    readonly providerId: string;
+    search(query: string, userId: string, options?: MemorySearchOptions): Promise<MemorySearchResult[]>;
+    ingest?(messages: MemoryIngestMessage[], userId: string, options?: MemoryIngestOptions): Promise<void>;
+    addText?(text: string, userId: string, options?: MemoryIngestOptions): Promise<{
+        memoriesAdded: number;
+    }>;
+    remove?(memoryId: string): Promise<boolean>;
+}
+export interface MemoryLearningSink {
+    ingestExtracted(items: MemoryExtractionItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationWriteResult>;
+}
+export interface MemoryToolLocalProvider {
+    addText(text: string, userId: string, metadata?: MemoryIngestOptions & {
+        category?: string;
+        importance?: number;
+    }): Promise<unknown>;
+    synthesizeTimeline(userId: string, startMs: number, endMs: number): string;
+    feedback(ids: string[], signal: "useful" | "irrelevant" | "outdated" | "wrong"): Promise<{
+        affected: number;
+    }>;
+}
+export interface MemoryActivitySummary {
+    dailyCounts: Array<{
+        date: string;
+        count: number;
+    }>;
+    highlights: Array<{
+        text: string;
+        category: string;
+        importance: number;
+        date: string;
+    }>;
+}
+/** Lightweight attachment reference carried on atlas/detail records (no bytes). */
+export interface MemoryAtlasAttachmentRef {
+    id: string;
+    kind: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    url: string;
+}
+export interface MemoryAtlasRecord {
+    id: string;
+    text: string;
+    category?: string;
+    importance?: number;
+    confidence?: number;
+    source?: string;
+    sessionId?: string;
+    eventDate?: string;
+    tags?: string[];
+    createdAt?: string | number;
+    updatedAt?: string | number;
+    accessCount?: number;
+    lastAccessedAt?: string | number;
+    isArchived?: boolean;
+    attachments?: MemoryAtlasAttachmentRef[];
+}
+export interface MemoryAtlasResult {
+    totalCount?: number;
+    records?: MemoryAtlasRecord[];
+    buckets?: unknown[];
+    clusters?: unknown[];
+    windowCursor?: unknown;
+    timeRange?: unknown;
+}
+export interface MemoryUpdatePatch {
+    text?: string;
+    category?: string;
+    importance?: number;
+    source?: string;
+    eventDate?: string;
+    tags?: string[];
+}
+export interface MemoryHandlerProvider extends MemoryProvider {
+    getAtlas?(userId: string, options?: Record<string, unknown>): MemoryAtlasResult;
+    getActivitySummary?(userId: string, days: number): MemoryActivitySummary;
+    observeExtracted?(items: MemoryExtractionItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationWriteResult>;
+    proposeExtracted?(items: MemoryExtractionItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationWriteResult>;
+    ingestExtracted?(items: MemoryExtractionItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationWriteResult>;
+    update?(id: string, patch: MemoryUpdatePatch): Promise<boolean>;
+    /** Persist an uploaded attachment (orphan until linked at commit). */
+    adoptAttachment?(input: {
+        data?: Buffer;
+        sourceUrl?: string;
+        filename: string;
+        mimeType: string;
+        userId: string;
+    }): Promise<MemoryAtlasAttachmentRef>;
+    /** Resolve an attachment id to its on-disk path (for serving). */
+    locateAttachment?(id: string): Promise<{
+        absPath: string;
+        mimeType: string;
+        filename: string;
+    } | null>;
+    /** Drop uploads never saved to a memory. */
+    purgeOrphanAttachments?(): Promise<void>;
+    /** Read an attachment's bytes + mime (for multimodal understanding). */
+    readAttachmentBytes?(id: string): Promise<{
+        bytes: Buffer;
+        mimeType: string;
+    } | null>;
+    /** Persist understood/extracted text on an attachment row. */
+    setAttachmentText?(id: string, text: string): void;
+}
+export interface MemoryDreamProvider {
+    search(query: string, userId: string, options?: {
+        limit?: number;
+    }): Promise<MemorySearchResult[]>;
+    proposeExtracted?(items: MemoryExtractionItem[], userId: string, options?: {
+        sessionId?: string;
+        source?: string;
+    }): Promise<{
+        proposalsAdded?: number;
+    }>;
+    feedback?(memoryIds: string[], signal: "useful" | "irrelevant" | "outdated" | "wrong"): Promise<{
+        affected: number;
+    }>;
+    getActivitySummary?(userId: string, days?: number): MemoryActivitySummary;
+    synthesizeTimeline?(userId: string, startMs: number, endMs: number): string;
+    getProfile?(userId: string, key: string): string | null;
+    setProfile?(userId: string, key: string, value: string): void;
+    getAllProfiles?(userId: string): Record<string, string>;
+}
+export interface MemoryDecayProvider {
+    triggerDecay(userId: string, maxAgeDays?: number): Promise<{
+        decayed: number;
+    }>;
+}
+export type MemoryRuntimeHookProvider = MemoryProvider & MemoryWriter;
+export type MemoryToolProvider = MemoryProvider & MemoryToolLocalProvider;
+export type MemoryDreamRuntimeProvider = MemoryDreamProvider & MemoryDecayProvider;

package/dist/runtime/ports/memory-provider.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/ports/memory-recall-source.d.ts

@@ -0,0 +1,3 @@
+export interface MemoryRecallSource {
+    getRootPath(): string;
+}

package/dist/runtime/ports/memory-recall-source.js

@@ -0,0 +1 @@
+export {};