@wappy_ai/core 0.1.0

package/dist/state/step-runner.d.ts

@@ -0,0 +1,24 @@
+import { type Clock } from "../clock.js";
+import { type State } from "./schema.js";
+export interface StepDef {
+    id: string;
+    part: string;
+    run: () => Promise<void> | void;
+}
+export interface StepResult {
+    id: string;
+    status: "done" | "failed";
+    error?: string;
+    /** true if the step was already `done` in state and run() was not called again. */
+    skipped: boolean;
+}
+/** Idempotent: a step already `done` is skipped, never re-run. Persists status either way. */
+export declare function runStep(state: State, def: StepDef, clock?: Pick<Clock, "now">): Promise<{
+    state: State;
+    result: StepResult;
+}>;
+/** Runs steps in order, resuming from the first not-yet-done one; stops (without running later steps) on the first failure. */
+export declare function runSteps(state: State, defs: StepDef[], clock?: Pick<Clock, "now">): Promise<{
+    state: State;
+    results: StepResult[];
+}>;

package/dist/state/step-runner.js

@@ -0,0 +1,42 @@
+import { systemClock } from "../clock.js";
+import { stepKey } from "./schema.js";
+function upsertStep(steps, next) {
+    const key = stepKey(next);
+    const i = steps.findIndex((s) => stepKey(s) === key);
+    if (i === -1)
+        return [...steps, next];
+    const copy = [...steps];
+    copy[i] = next;
+    return copy;
+}
+/** Idempotent: a step already `done` is skipped, never re-run. Persists status either way. */
+export async function runStep(state, def, clock = systemClock) {
+    const key = stepKey(def);
+    const existing = state.steps.find((s) => stepKey(s) === key);
+    if (existing?.status === "done") {
+        return { state, result: { id: def.id, status: "done", skipped: true } };
+    }
+    try {
+        await def.run();
+        const steps = upsertStep(state.steps, { id: def.id, part: def.part, status: "done" });
+        return { state: { ...state, steps, lastStep: def.id, updatedAt: clock.now() }, result: { id: def.id, status: "done", skipped: false } };
+    }
+    catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        const steps = upsertStep(state.steps, { id: def.id, part: def.part, status: "failed", error });
+        return { state: { ...state, steps, lastStep: def.id, updatedAt: clock.now() }, result: { id: def.id, status: "failed", error, skipped: false } };
+    }
+}
+/** Runs steps in order, resuming from the first not-yet-done one; stops (without running later steps) on the first failure. */
+export async function runSteps(state, defs, clock = systemClock) {
+    let current = state;
+    const results = [];
+    for (const def of defs) {
+        const { state: next, result } = await runStep(current, def, clock);
+        current = next;
+        results.push(result);
+        if (result.status === "failed")
+            break;
+    }
+    return { state: current, results };
+}

package/dist/state/version-skew.d.ts

@@ -0,0 +1,9 @@
+export interface VersionSkewWarning {
+    part: string;
+    message: string;
+}
+/** Core/part version skew check (SPEC §10) — pure, returns warnings; the CLI decides how to surface them. */
+export declare function checkVersionSkew(coreVersion: string, parts: {
+    name: string;
+    coreVersionRange: string;
+}[]): VersionSkewWarning[];

package/dist/state/version-skew.js

@@ -0,0 +1,7 @@
+import { satisfiesRange } from "../semver.js";
+/** Core/part version skew check (SPEC §10) — pure, returns warnings; the CLI decides how to surface them. */
+export function checkVersionSkew(coreVersion, parts) {
+    return parts
+        .filter((p) => !satisfiesRange(coreVersion, p.coreVersionRange))
+        .map((p) => ({ part: p.name, message: `${p.name} requires core ${p.coreVersionRange}, running ${coreVersion}` }));
+}

package/dist/tracer.d.ts

@@ -0,0 +1,16 @@
+import { type Clock } from "./clock.js";
+/** Systems a canonical trace (SPEC §9) can touch. */
+export type TracedSystem = "whatsapp" | "memory" | "router" | "skill" | "rag" | "tools" | "llm";
+export interface TraceEvent {
+    system: TracedSystem;
+    event: string;
+    data?: unknown;
+    at: number;
+}
+export interface Tracer {
+    record(system: TracedSystem, event: string, data?: unknown): void;
+    /** Set of systems touched so far — spine tests assert this exactly (B5). */
+    touched(): Set<TracedSystem>;
+    events(): TraceEvent[];
+}
+export declare function createInMemoryTracer(clock?: Pick<Clock, "now">): Tracer;

package/dist/tracer.js

@@ -0,0 +1,13 @@
+import { systemClock } from "./clock.js";
+export function createInMemoryTracer(clock = systemClock) {
+    const events = [];
+    const touched = new Set();
+    return {
+        record(system, event, data) {
+            touched.add(system);
+            events.push({ system, event, data, at: clock.now() });
+        },
+        touched: () => new Set(touched),
+        events: () => [...events],
+    };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@wappy_ai/core",
+  "version": "0.1.0",
+  "description": "Shared contracts (Tool, Memory, MessageChannel, SmartMessage) for building a WhatsApp AI agent. The interfaces every Wappy package implements.",
+  "keywords": [
+    "whatsapp",
+    "whatsapp-bot",
+    "ai-agent",
+    "agent-framework",
+    "llm",
+    "chatbot",
+    "typescript"
+  ],
+  "homepage": "https://github.com/csr1010/wappy-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/csr1010/wappy-kit.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/csr1010/wappy-kit/issues",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  }
+}