sessionmem 1.0.0

package/dist/core/api/contracts.js

@@ -0,0 +1,263 @@
+import { z } from "zod";
+export const memorySchema = z.object({
+    id: z.string().min(1),
+    projectId: z.string().min(1),
+    sessionId: z.string().min(1),
+    sourceAdapter: z.string().min(1),
+    kind: z.string().min(1),
+    content: z.string().min(1),
+    normalizedContent: z.string().min(1),
+    importance: z.number().int().min(1).max(10),
+    embedding: z.string().nullable(),
+    embeddingDim: z.number().int().nullable(),
+    embeddingVersion: z.string().nullable(),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+});
+export const ingestSessionEventSchema = z.object({
+    id: z.string().min(1),
+    eventIndex: z.number().int().nonnegative(),
+    eventType: z.string().min(1),
+    payloadJson: z.string().min(1),
+    createdAt: z.string().min(1).optional(),
+});
+export const ingestSessionEventsRequestSchema = z.object({
+    projectId: z.string().min(1),
+    sessionId: z.string().min(1),
+    events: z.array(ingestSessionEventSchema).min(1),
+});
+export const summarizeSessionToMemoryRequestSchema = z.object({
+    memoryId: z.string().min(1),
+    projectId: z.string().min(1),
+    sessionId: z.string().min(1),
+    sourceAdapter: z.string().min(1),
+    summary: z.string().min(1),
+    importance: z.number().int().min(1).max(10),
+});
+export const factModeSchema = z.enum([
+    "summary-only",
+    "facts-only",
+    "summary+facts",
+]);
+export const handleSessionEndConfigSchema = z.object({
+    autoSummarize: z.boolean().default(true),
+    minimumEventThreshold: z.number().int().min(1).max(100).default(3),
+    summaryTokenCap: z.number().int().min(1).default(300),
+    // No `.default()`: omission must be distinguishable from an explicit value so
+    // the service layer can fall back to the policy-config redactionEnabled
+    // setting (override > config.json > default precedence).
+    redactionEnabled: z.boolean().optional(),
+    factMode: factModeSchema.default("summary+facts"),
+    allowCloudSummarization: z.boolean().default(false),
+    anthropicApiKey: z.string().min(1).optional(),
+});
+export const handleSessionEndRequestSchema = z.object({
+    projectId: z.string().min(1),
+    sessionId: z.string().min(1),
+    sourceAdapter: z.string().min(1),
+    memoryId: z.string().min(1).optional(),
+    config: handleSessionEndConfigSchema.default(() => handleSessionEndConfigSchema.parse({})),
+});
+export const storeMemoryRequestSchema = z.object({
+    memoryId: z.string().min(1),
+    projectId: z.string().min(1),
+    sessionId: z.string().min(1),
+    sourceAdapter: z.string().min(1),
+    kind: z.string().min(1),
+    content: z.string().min(1),
+    importance: z.number().int().min(1).max(10),
+    // No `.default()`: omission must be distinguishable from an explicit value so
+    // the service layer can fall back to the policy-config redactionEnabled
+    // setting (override > config.json > default precedence).
+    redactionEnabled: z.boolean().optional(),
+});
+export const retrieveMemoriesRequestSchema = z.object({
+    projectId: z.string().min(1),
+    query: z.string().min(1),
+    limit: z.number().int().min(1).max(100).default(20),
+    mode: z.enum(["auto", "on-demand"]).default("auto"),
+    depth: z.enum(["default", "deep"]).default("default"),
+});
+export const recordMemoryUsedRequestSchema = z.object({
+    projectId: z.string().min(1),
+    memoryId: z.string().min(1),
+    feedbackType: z.enum(["auto_use", "manual"]).default("auto_use"),
+    usedAt: z.string().min(1).optional(),
+});
+export const listMemoriesRequestSchema = z.object({
+    projectId: z.string().min(1),
+});
+export const getMemoryRequestSchema = z.object({
+    projectId: z.string().min(1),
+    memoryId: z.string().min(1),
+});
+export const forgetMemoryRequestSchema = z.object({
+    projectId: z.string().min(1),
+    memoryId: z.string().min(1),
+});
+export const exportMemoriesRequestSchema = z.object({
+    projectId: z.string().min(1),
+});
+export const importMemoryRecordSchema = z.object({
+    id: z.string().min(1),
+    projectId: z.string().min(1),
+    sessionId: z.string().min(1),
+    sourceAdapter: z.string().min(1),
+    kind: z.string().min(1),
+    content: z.string().min(1),
+    importance: z.number().int().min(1).max(10),
+    // OPTIONAL for backward-compat with exports predating team provenance (A3):
+    // older exports lack author/originProjectId, so the service stamps the local
+    // username when author is absent. `.nullable()` because exportMemories emits
+    // `originProjectId: null` (and `author: ""`) for locally-authored rows — a
+    // team sync round-trips those exported snapshots verbatim, so the schema must
+    // accept the null the DTO carries rather than skip-and-warn every local row.
+    author: z.string().nullable().optional(),
+    originProjectId: z.string().nullable().optional(),
+    createdAt: z.string().min(1).optional(),
+    updatedAt: z.string().min(1).optional(),
+});
+export const importMemoriesRequestSchema = z.object({
+    projectId: z.string().min(1),
+    // No `.default()`: omission must be distinguishable from an explicit value so
+    // the service layer can fall back to the policy-config redactionEnabled
+    // setting (override > config.json > default precedence).
+    redactionEnabled: z.boolean().optional(),
+    memories: z.array(importMemoryRecordSchema),
+});
+// Team pull. Mirrors importMemoriesRequestSchema — the pull
+// path reuses importMemoryRecordSchema verbatim (carrying author/originProjectId
+// through) but the service applies MAX-importance last-write-wins, author/origin
+// stamping, and the cross-project skip. redactionEnabled is
+// omitted on real pulls so the service resolves config.json.
+export const pullMemoriesRequestSchema = z.object({
+    projectId: z.string().min(1),
+    redactionEnabled: z.boolean().optional(),
+    memories: z.array(importMemoryRecordSchema),
+});
+export const statsRequestSchema = z.object({
+    projectId: z.string().min(1),
+});
+export const pruneMemoriesRequestSchema = z.object({
+    projectId: z.string().min(1),
+    retentionDays: z.number().int(),
+    dryRun: z.boolean().default(true),
+});
+export const pruneMemoriesResponseSchema = z.object({
+    ok: z.literal(true),
+    deleted: z.number().int().nonnegative(),
+    eligible: z.number().int().nonnegative(),
+});
+export const redactExistingRequestSchema = z.object({
+    projectId: z.string().min(1),
+    apply: z.boolean().default(false),
+});
+export const redactExistingResponseSchema = z.object({
+    ok: z.literal(true),
+    scanned: z.number().int().nonnegative(),
+    matched: z.number().int().nonnegative(),
+    updated: z.number().int().nonnegative(),
+    // Rows that matched but could not be updated (e.g. deleted
+    // concurrently between the initial scan and the apply step). A non-zero
+    // skipped count lets the CLI report partial success instead of the whole
+    // operation erroring out and discarding prior updates/previews.
+    skipped: z.number().int().nonnegative().default(0),
+    previews: z.array(z.string()),
+});
+export const operationResultSchema = z.object({
+    ok: z.literal(true),
+});
+export const singleMemoryResponseSchema = z.object({
+    ok: z.literal(true),
+    memory: memorySchema,
+});
+// Dedicated store response: extends the single-memory shape with the
+// warningCodes envelope. getMemory continues to use
+// singleMemoryResponseSchema so its shape is unchanged.
+export const storeMemoryResponseSchema = z.object({
+    ok: z.literal(true),
+    memory: memorySchema,
+    warningCodes: z.array(z.string()),
+});
+export const memoryListResponseSchema = z.object({
+    ok: z.literal(true),
+    memories: z.array(memorySchema),
+    total: z.number().int().nonnegative(),
+});
+export const scoreBreakdownSchema = z.object({
+    raw: z.object({
+        semantic: z.number(),
+        recency: z.number(),
+        importance: z.number(),
+    }),
+    weighted: z.object({
+        semantic: z.number(),
+        recency: z.number(),
+        importance: z.number(),
+    }),
+    total: z.number(),
+});
+export const retrievedMemorySchema = memorySchema.extend({
+    semantic: z.number(),
+    score: scoreBreakdownSchema,
+});
+export const retrieveMemoriesResponseSchema = z.object({
+    ok: z.literal(true),
+    memories: z.array(retrievedMemorySchema),
+    total: z.number().int().nonnegative(),
+    // Pre-rendered startup-injection block: includes the `author:`
+    // prefix annotation for teammate-authored memories, derived via
+    // formatStartupInjection() with the local username.
+    startupInjection: z.string(),
+});
+export const exportMemoriesResponseSchema = z.object({
+    ok: z.literal(true),
+    memories: z.array(memorySchema),
+});
+export const statsResponseSchema = z.object({
+    ok: z.literal(true),
+    totalMemories: z.number().int().nonnegative(),
+    totalSessionEvents: z.number().int().nonnegative(),
+});
+export const ingestSessionEventsResponseSchema = z.object({
+    ok: z.literal(true),
+    ingested: z.number().int().nonnegative(),
+});
+export const summarizeSessionToMemoryResponseSchema = z.object({
+    ok: z.literal(true),
+    memoryId: z.string().min(1),
+});
+export const handleSessionEndResponseSchema = z.object({
+    ok: z.literal(true),
+    status: z.enum(["stored", "skipped_threshold", "skipped_disabled", "failed"]),
+    usedMode: z.enum(["local", "cloud"]),
+    warningCodes: z.array(z.string()),
+    warningMessages: z.array(z.string()),
+    failureRecordId: z.string().min(1).optional(),
+    memoryId: z.string().min(1).optional(),
+});
+export const importMemoriesResponseSchema = z.object({
+    ok: z.literal(true),
+    imported: z.number().int().nonnegative(),
+    // Count of records skipped because their `id` already belongs to a
+    // different project's memory. These are never upserted, preventing
+    // cross-project overwrite/reassignment via ON CONFLICT(id).
+    skippedCrossProject: z.number().int().nonnegative().default(0),
+    warningCodes: z.array(z.string()),
+});
+// Team pull response: distinguishes brand-new inserts from updates so the
+// `sync` CLI can render "Pushed N memories, pulled M new + updated K from
+// teammates." skippedCrossProject mirrors the import path.
+export const pullMemoriesResponseSchema = z.object({
+    ok: z.literal(true),
+    pulledNew: z.number().int().nonnegative(),
+    pulledUpdated: z.number().int().nonnegative(),
+    skippedCrossProject: z.number().int().nonnegative().default(0),
+    warningCodes: z.array(z.string()),
+});
+export const recordMemoryUsedResponseSchema = z.object({
+    ok: z.literal(true),
+    memoryId: z.string().min(1),
+    previousImportance: z.number().int().min(1).max(10),
+    newImportance: z.number().int().min(1).max(10),
+});

package/dist/core/api/errors.js

@@ -0,0 +1,29 @@
+export class DomainError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "DomainError";
+        this.code = code;
+        this.details = details;
+    }
+}
+export function toErrorEnvelope(error) {
+    if (error instanceof DomainError) {
+        return {
+            code: error.code,
+            message: error.message,
+            details: error.details,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            code: "INTERNAL",
+            message: error.message,
+        };
+    }
+    return {
+        code: "INTERNAL",
+        message: "Unexpected error",
+    };
+}

package/dist/core/api/localOnlyPolicy.js

@@ -0,0 +1,29 @@
+import { DomainError } from "./errors.js";
+function isExternalProviderEnabled(config) {
+    if (!config.enabled) {
+        return false;
+    }
+    if (config.mode && config.mode !== "local") {
+        return true;
+    }
+    if (config.provider) {
+        return config.provider !== "local";
+    }
+    return true;
+}
+export function assertLocalOnlyPolicy(config) {
+    const localOnly = config.localOnly ?? true;
+    if (!localOnly) {
+        return;
+    }
+    if (config.allowExternalProviders) {
+        return;
+    }
+    const enabledExternalProviders = Object.entries(config.providers ?? {})
+        .filter(([, providerConfig]) => providerConfig)
+        .filter(([, providerConfig]) => isExternalProviderEnabled(providerConfig))
+        .map(([name]) => name);
+    if (enabledExternalProviders.length > 0) {
+        throw new DomainError("VALIDATION", `Local-only mode blocks external providers: ${enabledExternalProviders.join(", ")}. Set allowExternalProviders=true for explicit opt-in.`);
+    }
+}