@wappy_ai/core 0.1.0

package/dist/clock.d.ts

@@ -0,0 +1,8 @@
+/** Injectable time + scheduling port. Never call Date.now()/setTimeout directly outside an impl of this. */
+export interface Clock {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): number;
+    clearTimeout(handle: number): void;
+    sleep(ms: number): Promise<void>;
+}
+export declare const systemClock: Clock;

package/dist/clock.js

@@ -0,0 +1,17 @@
+const timers = new Map();
+let nextHandle = 1;
+export const systemClock = {
+    now: () => Date.now(),
+    setTimeout(fn, ms) {
+        const handle = nextHandle++;
+        timers.set(handle, setTimeout(fn, ms));
+        return handle;
+    },
+    clearTimeout(handle) {
+        const native = timers.get(handle);
+        if (native !== undefined)
+            clearTimeout(native);
+        timers.delete(handle);
+    },
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export declare const packageName = "@wappy_ai/core";
+/** Kept in sync with package.json "version" by hand; PluginRegistry checks against this. */
+export declare const CORE_VERSION = "0.1.0";
+export * from "./schemas.js";
+export * from "./clock.js";
+export * from "./logger.js";
+export * from "./tracer.js";
+export * from "./interfaces.js";
+export * from "./semver.js";
+export * from "./setup-manifest.js";
+export * from "./registry.js";
+export * from "./state/index.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export const packageName = "@wappy_ai/core";
+/** Kept in sync with package.json "version" by hand; PluginRegistry checks against this. */
+export const CORE_VERSION = "0.1.0";
+export * from "./schemas.js";
+export * from "./clock.js";
+export * from "./logger.js";
+export * from "./tracer.js";
+export * from "./interfaces.js";
+export * from "./semver.js";
+export * from "./setup-manifest.js";
+export * from "./registry.js";
+export * from "./state/index.js";

package/dist/interfaces.d.ts

@@ -0,0 +1,92 @@
+import type { DeliveryResult, InboundMessage, RouterDecision, SessionProfile, SmartMessage, ToolResult, Turn } from "./schemas.js";
+/** JSON Schema object, as produced by zod's toJSONSchema and consumed by Model tool-calling. */
+export type JsonSchema = Record<string, unknown>;
+/** A single callable tool (§3, §8). */
+export interface Tool {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+    /** Never mutates external state; safe to auto-call without confirmation. */
+    readOnly: boolean;
+    /** Requires explicit user/operator confirmation before executing, regardless of readOnly. */
+    confirmBefore: boolean;
+    execute(args: unknown): Promise<ToolResult>;
+}
+/** Generates Tools from a source (OpenAPI spec, Shopify, custom code) (§3, §8). */
+export interface ToolProvider {
+    name: string;
+    listTools(): Promise<Tool[]> | Tool[];
+}
+/** Prompt fragment + tools + optional memory schema for one capability (§17 glossary). */
+export interface Skill {
+    name: string;
+    description: string;
+    promptFragment: string;
+    /** Names of tools (from registered ToolProviders) this skill may use. */
+    tools?: string[];
+    /** Opaque, skill-owned shape persisted alongside Memory; core never interprets it. */
+    memorySchema?: unknown;
+}
+/**
+ * receive() returns an array: one webhook payload may batch several message
+ * events, or contain zero when it's a status/read-receipt-only notification
+ * (§6.2). send() takes an explicit recipient because a channel serves many
+ * contacts.
+ */
+export interface MessageChannel {
+    name: string;
+    receive(rawWebhook: unknown): Promise<InboundMessage[]> | InboundMessage[];
+    send(to: string, message: SmartMessage): Promise<DeliveryResult>;
+}
+export interface Memory {
+    load(contactId: string): Promise<Turn[]>;
+    append(turn: Turn): Promise<void>;
+    /** Semantic recall scoped to one contact's history/knowledge. Returns text snippets. */
+    recall(contactId: string, query: string): Promise<string[]>;
+}
+/** M13: one focused store for the session profile, same pattern as `@wappy_ai/whatsapp`'s
+ * `SeenStore`/`SessionWindowTracker` — not an overload of `Memory` (turn history is a separate
+ * concern from a structured, TTL-bound profile). */
+export interface SessionProfileStore {
+    /** `undefined` when no profile exists for this contact, OR it exists but `now > expiresAt` — a
+     * caller never has to separately check expiry; an expired profile IS an absent one. */
+    get(contactId: string, now: number): Promise<SessionProfile | undefined>;
+    /** Upsert. Callers always pass a fresh `expiresAt`, so calling this after every successful turn
+     * is also how the TTL renews — there's no separate "touch" operation. */
+    set(profile: SessionProfile): Promise<void>;
+}
+export interface RouterInput {
+    message: InboundMessage;
+    history: Turn[];
+    availableSkills: string[];
+    availableTools: string[];
+}
+export interface Router {
+    route(input: RouterInput): Promise<RouterDecision>;
+}
+export interface ModelToolCall {
+    name: string;
+    args: unknown;
+}
+export interface ModelRequest {
+    prompt: string;
+    /** Sent as a system-role message when the underlying adapter supports it — kept separate from `prompt` so structured role separation survives even when the caller has already assembled everything into one deterministic prompt string (T6.2). */
+    system?: string;
+    history?: Turn[];
+    tools?: Tool[];
+    /** e.g. smartMessageJsonSchema, when the model must emit a SmartMessage (§6.3). */
+    responseSchema?: JsonSchema;
+}
+export interface ModelResult {
+    text?: string;
+    structured?: unknown;
+    toolCalls?: ModelToolCall[];
+}
+/** The model port — Vercel AI SDK or any provider sits behind this (§2.1). */
+export interface Model {
+    generate(req: ModelRequest): Promise<ModelResult>;
+}
+/** Orchestrates a single inbound message -> reply, wiring Router/Memory/Tools/Channel/Model (§3). */
+export interface Agent {
+    handle(message: InboundMessage): Promise<DeliveryResult>;
+}

package/dist/interfaces.js

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

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+export interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+export declare const noopLogger: Logger;

package/dist/logger.js

@@ -0,0 +1,6 @@
+export const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};

package/dist/registry.d.ts

@@ -0,0 +1,26 @@
+import type { SetupManifest } from "./setup-manifest.js";
+export type PluginKind = "channel" | "memory" | "router" | "toolProvider" | "skill" | "model";
+export interface Plugin<T = unknown> {
+    name: string;
+    kind: PluginKind;
+    /** semver range of @wappy_ai/core this plugin was built against. */
+    coreVersionRange: string;
+    instance: T;
+    setup?: SetupManifest;
+}
+/** Parts self-register here; core loads the enabled subset from config (§3). Deterministic (registration) order. */
+export declare class PluginRegistry {
+    private readonly coreVersion;
+    private readonly plugins;
+    private readonly names;
+    constructor(coreVersion: string);
+    register(plugin: Plugin): void;
+    /** First-registered plugin of `kind` (optionally by `name`); undefined if none match — never throws on an unknown kind. */
+    get<T>(kind: PluginKind, name?: string): T | undefined;
+    list(kind?: PluginKind): Plugin[];
+}
+export interface RegistryConfig {
+    enabled: string[];
+}
+/** Resolves the configured enabled-plugin list in config order; throws on an unregistered name. */
+export declare function resolveEnabledPlugins(registry: PluginRegistry, config: RegistryConfig): Plugin[];

package/dist/registry.js

@@ -0,0 +1,40 @@
+import { satisfiesRange } from "./semver.js";
+/** Parts self-register here; core loads the enabled subset from config (§3). Deterministic (registration) order. */
+export class PluginRegistry {
+    coreVersion;
+    plugins = [];
+    names = new Set();
+    constructor(coreVersion) {
+        this.coreVersion = coreVersion;
+    }
+    register(plugin) {
+        if (this.names.has(plugin.name)) {
+            throw new Error(`PluginRegistry: duplicate plugin name "${plugin.name}"`);
+        }
+        if (!satisfiesRange(this.coreVersion, plugin.coreVersionRange)) {
+            throw new Error(`PluginRegistry: plugin "${plugin.name}" requires core ${plugin.coreVersionRange}, running ${this.coreVersion}`);
+        }
+        this.names.add(plugin.name);
+        this.plugins.push(plugin);
+    }
+    /** First-registered plugin of `kind` (optionally by `name`); undefined if none match — never throws on an unknown kind. */
+    get(kind, name) {
+        const found = name
+            ? this.plugins.find((p) => p.kind === kind && p.name === name)
+            : this.plugins.find((p) => p.kind === kind);
+        return found?.instance;
+    }
+    list(kind) {
+        return kind ? this.plugins.filter((p) => p.kind === kind) : [...this.plugins];
+    }
+}
+/** Resolves the configured enabled-plugin list in config order; throws on an unregistered name. */
+export function resolveEnabledPlugins(registry, config) {
+    const byName = new Map(registry.list().map((p) => [p.name, p]));
+    return config.enabled.map((name) => {
+        const plugin = byName.get(name);
+        if (!plugin)
+            throw new Error(`resolveEnabledPlugins: unknown plugin "${name}"`);
+        return plugin;
+    });
+}

package/dist/schemas.d.ts

@@ -0,0 +1,285 @@
+import { z } from "zod";
+/**
+ * Runtime schemas for the core data shapes (§3, §6.1, §6.3, §9 of SPEC.md).
+ *
+ * Layering rule for WhatsApp send-time limits (§6.1): this schema enforces
+ * STRUCTURAL bounds only (button/row/section counts) because those can't be
+ * fixed by truncation without changing meaning. TEXT LENGTH limits (button
+ * title <=20, list row title <=24, row description <=72) are intentionally
+ * NOT enforced here — @wappy_ai/whatsapp (M4) truncates them at send time, so
+ * an over-length string is valid input at this layer and a renderer concern
+ * downstream. See docs/CONTRACTS.md.
+ */
+export declare const InboundMediaSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        image: "image";
+        document: "document";
+        video: "video";
+        audio: "audio";
+        voice: "voice";
+        location: "location";
+    }>;
+    url: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    caption: z.ZodOptional<z.ZodString>;
+    latitude: z.ZodOptional<z.ZodNumber>;
+    longitude: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type InboundMedia = z.infer<typeof InboundMediaSchema>;
+export declare const InboundMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    contactId: z.ZodString;
+    channel: z.ZodString;
+    text: z.ZodOptional<z.ZodString>;
+    media: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            image: "image";
+            document: "document";
+            video: "video";
+            audio: "audio";
+            voice: "voice";
+            location: "location";
+        }>;
+        url: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        caption: z.ZodOptional<z.ZodString>;
+        latitude: z.ZodOptional<z.ZodNumber>;
+        longitude: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    selectionId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodNumber;
+    raw: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type InboundMessage = z.infer<typeof InboundMessageSchema>;
+export declare const SmartButtonSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>;
+export declare const SmartButtonsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>>;
+export declare const SmartListRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SmartListSectionSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    rows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const SmartListSchema: z.ZodObject<{
+    buttonText: z.ZodString;
+    sections: z.ZodArray<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        rows: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const SmartCtaSchema: z.ZodObject<{
+    text: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+/** An interactive message's header (§6.1/M12): image/video/document/text alongside body + action.
+ * Meta's real Cloud API supports this on button/list interactive messages — verified against
+ * their docs, not assumed — for a "preview, then text, then CTA/list" reply. Valid only alongside
+ * buttons/list/cta (enforced below); a header on a plain text/media-only send is meaningless. */
+export declare const SmartHeaderSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+    subText: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"video">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"document">;
+    url: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export declare const SmartMediaSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        image: "image";
+        document: "document";
+        video: "video";
+        audio: "audio";
+        voice: "voice";
+    }>;
+    url: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    filename: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SmartMessageSchema: z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    buttons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>>>;
+    list: z.ZodOptional<z.ZodObject<{
+        buttonText: z.ZodString;
+        sections: z.ZodArray<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            rows: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    cta: z.ZodOptional<z.ZodObject<{
+        text: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>>;
+    media: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            image: "image";
+            document: "document";
+            video: "video";
+            audio: "audio";
+            voice: "voice";
+        }>;
+        url: z.ZodString;
+        caption: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        filename: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    header: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+        subText: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"video">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"document">;
+        url: z.ZodString;
+        filename: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>;
+    quoteId: z.ZodOptional<z.ZodString>;
+    flow: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type SmartMessage = z.infer<typeof SmartMessageSchema>;
+/** JSON Schema for SmartMessage — this is what the model is asked to emit (§6.3). */
+export declare const smartMessageJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    buttons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>>>;
+    list: z.ZodOptional<z.ZodObject<{
+        buttonText: z.ZodString;
+        sections: z.ZodArray<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            rows: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    cta: z.ZodOptional<z.ZodObject<{
+        text: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>>;
+    media: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            image: "image";
+            document: "document";
+            video: "video";
+            audio: "audio";
+            voice: "voice";
+        }>;
+        url: z.ZodString;
+        caption: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        filename: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    header: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+        subText: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"video">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"document">;
+        url: z.ZodString;
+        filename: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>;
+    quoteId: z.ZodOptional<z.ZodString>;
+    flow: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>>;
+export declare const DeliveryStatusSchema: z.ZodEnum<{
+    sent: "sent";
+    failed: "failed";
+    queued: "queued";
+    fellBack: "fellBack";
+}>;
+export declare const DeliveryResultSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        sent: "sent";
+        failed: "failed";
+        queued: "queued";
+        fellBack: "fellBack";
+    }>;
+    messageId: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DeliveryResult = z.infer<typeof DeliveryResultSchema>;
+export declare const TurnSchema: z.ZodObject<{
+    id: z.ZodString;
+    contactId: z.ZodString;
+    role: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>;
+    text: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodNumber;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type Turn = z.infer<typeof TurnSchema>;
+export declare const RouterDecisionSchema: z.ZodObject<{
+    intent: z.ZodString;
+    skill: z.ZodOptional<z.ZodString>;
+    needsRAG: z.ZodBoolean;
+    needsTool: z.ZodBoolean;
+    escalate: z.ZodBoolean;
+    confidence: z.ZodNumber;
+}, z.core.$strip>;
+export type RouterDecision = z.infer<typeof RouterDecisionSchema>;
+/** M13: a small, structured, per-contact profile — facts (name, location, ...), the fresh open
+ * thread right now (`currentState`, updated every turn, never compressed), and a coarser
+ * `summary` allowed to lag behind it. TTL-bound via `expiresAt`; session-scoped, not a permanent
+ * cross-session user profile (see docs/milestones/M13.md — that's explicitly deferred). */
+export declare const SessionProfileSchema: z.ZodObject<{
+    contactId: z.ZodString;
+    facts: z.ZodRecord<z.ZodString, z.ZodString>;
+    currentState: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+export type SessionProfile = z.infer<typeof SessionProfileSchema>;
+export declare const ToolResultSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    ok: z.ZodBoolean;
+    data: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ToolResult = z.infer<typeof ToolResultSchema>;

package/dist/schemas.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+/**
+ * Runtime schemas for the core data shapes (§3, §6.1, §6.3, §9 of SPEC.md).
+ *
+ * Layering rule for WhatsApp send-time limits (§6.1): this schema enforces
+ * STRUCTURAL bounds only (button/row/section counts) because those can't be
+ * fixed by truncation without changing meaning. TEXT LENGTH limits (button
+ * title <=20, list row title <=24, row description <=72) are intentionally
+ * NOT enforced here — @wappy_ai/whatsapp (M4) truncates them at send time, so
+ * an over-length string is valid input at this layer and a renderer concern
+ * downstream. See docs/CONTRACTS.md.
+ */
+export const InboundMediaSchema = z.object({
+    kind: z.enum(["image", "document", "video", "audio", "voice", "location"]),
+    url: z.string().optional(),
+    mimeType: z.string().optional(),
+    caption: z.string().optional(),
+    /** Only meaningful when kind === "location". */
+    latitude: z.number().optional(),
+    longitude: z.number().optional(),
+});
+export const InboundMessageSchema = z.object({
+    /** Channel-native message id, used for idempotency/dedupe (§6.2). */
+    id: z.string().min(1),
+    /** Opaque contact identifier, stable per sender on this channel. */
+    contactId: z.string().min(1),
+    /** Which MessageChannel produced this, e.g. "whatsapp". */
+    channel: z.string().min(1),
+    text: z.string().optional(),
+    media: InboundMediaSchema.optional(),
+    /**
+     * The stable id of whatever discrete option the user picked (a button/list-row id, a quick-reply
+     * payload, ...) — distinct from `text`, which carries the human-readable title and may be
+     * duplicated, localized, or renamed. Routing must key off this, never off `text`.
+     */
+    selectionId: z.string().optional(),
+    /** Epoch milliseconds. */
+    timestamp: z.number(),
+    /** Channel-native payload, kept for debugging/replay; never parsed by core. */
+    raw: z.unknown().optional(),
+});
+export const SmartButtonSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+});
+export const SmartButtonsSchema = z.array(SmartButtonSchema).min(1).max(3);
+export const SmartListRowSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    description: z.string().optional(),
+});
+export const SmartListSectionSchema = z.object({
+    title: z.string().optional(),
+    rows: z.array(SmartListRowSchema).min(1),
+});
+export const SmartListSchema = z
+    .object({
+    buttonText: z.string().min(1),
+    sections: z.array(SmartListSectionSchema).min(1).max(10),
+})
+    .refine((l) => l.sections.reduce((n, s) => n + s.rows.length, 0) <= 10, {
+    message: "list: total rows across all sections must be <= 10",
+});
+export const SmartCtaSchema = z.object({
+    text: z.string().min(1),
+    url: z.string().url(),
+});
+/** An interactive message's header (§6.1/M12): image/video/document/text alongside body + action.
+ * Meta's real Cloud API supports this on button/list interactive messages — verified against
+ * their docs, not assumed — for a "preview, then text, then CTA/list" reply. Valid only alongside
+ * buttons/list/cta (enforced below); a header on a plain text/media-only send is meaningless. */
+export const SmartHeaderSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("text"), text: z.string().min(1), subText: z.string().optional() }),
+    z.object({ type: z.literal("image"), url: z.string().min(1) }),
+    z.object({ type: z.literal("video"), url: z.string().min(1) }),
+    z.object({ type: z.literal("document"), url: z.string().min(1), filename: z.string().optional() }),
+]);
+export const SmartMediaSchema = z.object({
+    kind: z.enum(["image", "document", "video", "audio", "voice"]),
+    url: z.string().min(1),
+    caption: z.string().optional(),
+    mimeType: z.string().optional(),
+    filename: z.string().optional(),
+});
+export const SmartMessageSchema = z
+    .object({
+    text: z.string().min(1).optional(),
+    buttons: SmartButtonsSchema.optional(),
+    list: SmartListSchema.optional(),
+    cta: SmartCtaSchema.optional(),
+    media: SmartMediaSchema.optional(),
+    header: SmartHeaderSchema.optional(),
+    /** id of an inbound message this reply quotes ("reply in context"). */
+    quoteId: z.string().optional(),
+    /** Reserved slot for WhatsApp Flows/forms (deferred; SPEC §6.1). Not validated in v0.1. */
+    flow: z.unknown().optional(),
+})
+    .refine((m) => Boolean(m.text ?? m.buttons ?? m.list ?? m.cta ?? m.media), {
+    message: "SmartMessage: at least one of text/buttons/list/cta/media is required",
+})
+    .refine((m) => !m.header || Boolean(m.buttons ?? m.list ?? m.cta), {
+    message: "SmartMessage: header is only valid alongside buttons/list/cta (Meta's own constraint)",
+});
+/** JSON Schema for SmartMessage — this is what the model is asked to emit (§6.3). */
+export const smartMessageJsonSchema = z.toJSONSchema(SmartMessageSchema);
+export const DeliveryStatusSchema = z.enum(["sent", "failed", "queued", "fellBack"]);
+export const DeliveryResultSchema = z
+    .object({
+    status: DeliveryStatusSchema,
+    messageId: z.string().optional(),
+    /** Actionable, human-readable reason — never a raw stack trace (§10). */
+    reason: z.string().optional(),
+})
+    .refine((d) => (d.status === "failed" || d.status === "fellBack" ? Boolean(d.reason) : true), {
+    message: "DeliveryResult: reason is required when status is failed or fellBack",
+});
+export const TurnSchema = z.object({
+    id: z.string().min(1),
+    contactId: z.string().min(1),
+    role: z.enum(["user", "agent", "system"]),
+    text: z.string().optional(),
+    timestamp: z.number(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
+export const RouterDecisionSchema = z.object({
+    intent: z.string().min(1),
+    skill: z.string().optional(),
+    needsRAG: z.boolean(),
+    needsTool: z.boolean(),
+    escalate: z.boolean(),
+    confidence: z.number().min(0).max(1),
+});
+/** M13: a small, structured, per-contact profile — facts (name, location, ...), the fresh open
+ * thread right now (`currentState`, updated every turn, never compressed), and a coarser
+ * `summary` allowed to lag behind it. TTL-bound via `expiresAt`; session-scoped, not a permanent
+ * cross-session user profile (see docs/milestones/M13.md — that's explicitly deferred). */
+export const SessionProfileSchema = z.object({
+    contactId: z.string().min(1),
+    facts: z.record(z.string(), z.string()),
+    currentState: z.string().optional(),
+    summary: z.string().optional(),
+    expiresAt: z.number(),
+});
+export const ToolResultSchema = z.object({
+    toolName: z.string().min(1),
+    ok: z.boolean(),
+    data: z.unknown().optional(),
+    error: z.string().optional(),
+});

package/dist/semver.d.ts

@@ -0,0 +1 @@
+export declare function satisfiesRange(version: string, range: string): boolean;