@rubytech/create-maxy-code 0.1.427 → 0.1.431

package/payload/platform/plugins/docs/PLUGIN.md

@@ -24,6 +24,7 @@ Load these when users ask about Maxy features or need guidance:
 - **Settings** → `references/settings.md` — output style, effort level, account preferences
 - **Access Control** → `references/access-control.md` — who can chat with your public agent, invitations, authentication
 - **Projects** → `references/projects-guide.md` — creating projects, tracking health, phase transitions, completing
+- **Workflows** → `references/workflows.md` — saving and running multi-step processes, declared inputs, scheduling, run history
 - **Slides** → `references/slides.md` — generating, theming, and reviewing HTML slide decks with `/slides`
 - **Calendar & booking** → `references/calendar-booking.md` — the admin calendar at `/calendar`, deploying a public booking page, setting availability, and how bookings become meetings
 - **Troubleshooting** → `references/troubleshooting.md` — common issues and how to resolve them

package/payload/platform/plugins/docs/references/admin-ui.md

@@ -75,6 +75,8 @@ either is a regression.
 
 **`/chat` Claude-desktop transcript presentation.** The admin webchat keeps the shared `Transcript` shell (stream, follow-tail) but injects a /chat-only item renderer via the component's optional `renderItems` prop: `renderChatTimeline` in `app/chat/transcript-render.tsx`. Presentation: operator turns render as a right-aligned grey bubble showing the message text and, beneath it, a subtle always-visible time-of-day stamp (no label); delivered agent replies render as plain prose with the same time-of-day stamp beneath (the reply-document filename line stays, as prose); the stamp is HH:MM from the turn's `ts` (locale-formatted, right-aligned inside the operator bubble, left-aligned under agent prose), and a turn whose `ts` is null/unparseable shows no stamp, never an empty line — so only delivered operator and agent-reply turns are stamped, while tool runs, the collapsed "Thinking" block, and the agent-error banner stay time-free; a maximal consecutive run of `tool-call`/`tool-result` turns renders as one collapsed grey one-liner ("Used N tools ›") whose expansion shows every call and result payload — a lone call still gets the one-liner, and prose or a directive row ends a run. The WhatsApp/operator reader (`/whatsapp`, `OperatorConversations`) omits the prop and keeps the default `renderTimeline`, so its bubble/DM chrome is unchanged — except that since the attachment-render extraction the default renderer draws inbound `operator-inbound` uploads and `agent-file` deliveries inline (image thumbnail / pdf.js preview / audio player / download chip) via the attachment renderer shared with `/chat`, extracted to `app/chat/attachment-render.tsx` to break the cycle with `transcript-render.tsx`; `renderChatTimeline` is untouched. Both presentations are test-pinned (`app/whatsapp/__tests__/Transcript-*.test.tsx`, `app/chat/__tests__/transcript-render.test.tsx`, `app/chat/__tests__/pdf-preview.test.tsx`). **Day-divider:** both renderers insert a centered `.day-divider` row between two consecutive timeline items on different local calendar days (label `Today`/`Yesterday`, else `Sat 14 Jun 2026`), so a thread spanning midnight is never an ambiguous run of HH:MM; the first dated item gets a leading divider, a null/unparseable `ts` marks no boundary, dividers are computed over the filtered `visibleItems`, and in `/chat` a day crossover flushes any open tool/think run first so a collapsed run never spans it. Per-bubble HH:MM stamps are unchanged. Shared helpers `dayKey`/`dayLabel`/`itemTs`/`DayDivider` live in `app/whatsapp/Transcript.tsx`.
 
+**WhatsApp reader is read/write (WhatsApp-Web surface).** A WhatsApp store conversation in the operator Conversations reader (`OperatorConversations`) and the admin root channel viewer (`app/page.tsx`) no longer opens the plain read-only DM chrome — it opens `app/whatsapp/WhatsappWebConversation.tsx`, a WhatsApp-Web-styled surface: a conversation header, the delivered-only store transcript reskinned green/white under a `.wa-web` root class, and a reply composer (`app/whatsapp/ReplyComposer.tsx`). The operator can type text and attach files (the webchat allowlist: `SUPPORTED_MIME_SET` / 50 MB / 5 files) and send them into that WhatsApp conversation. **Send is reply-only and DM-only:** `POST /api/whatsapp-reader/reply` (`requireAdminSession`) refuses any target with no existing stored conversation (`reason=no-existing-conversation`, HTTP 403) — a cold first-contact send bans the account, so the composer is never a cold-contact path, enforced server-side — and refuses `@g.us` groups (`reason=group-send-blocked`), matching the agent's observe-only group invariant; a group thread shows a read-only note in place of the composer. The endpoint is the sole store writer for a manual send: right after each send resolves it appends the record itself, stamped `origin:'operator-manual'` (attributed "You", distinct from an assistant reply), because the Baileys echo that normally persists the store is gated on message text (`manager.ts:906`) and would leave an uncaptioned media send delivered-but-invisible. The record's `messageId` matches the echo's derivation so the async text echo's own persist dedups to a no-op; the send is confirmed by re-read (`op=recorded present=<bool>`). A sent send does not spawn an assistant turn (echo dispatch stays suppressed). Attachments deliver as WhatsApp media/documents and appear in the reader as an attributed text line (`[sent <file>]`) — inline media rendering in the store reader is a follow-up. The `.wa-web` skin is scoped to WhatsApp store threads only, so `/chat`, the admin agent session view, and the public visitor webchat are unchanged; the visitor webchat gains no send capability. The header call/video/search icons and the in-bubble delivered-tick are cosmetic (no presence or read-receipt data is stored); inbound bubbles keep their sender name so group threads stay attributable. Non-WhatsApp reader rows (Telegram/webchat session JSONLs) keep the plain read-only `Transcript`. Observability rides `[wa-manual-send]` lines correlated by a per-request `sendId`.
+
 **`/chat` live activity line.** While a turn is in flight the transcript tail shows one ephemeral `ChatActivity` line (mounted only while `busy`, admin/operator only). It tracks real activity, not a timer: while a `Task` subagent runs it shows that subagent's headline (`agentType · description`, prefixed `N agents ·` when ≥2 are concurrent), sourced from `agent-<hex>.meta.json` via named `activity` SSE events the admin reader pushes from the session's `subagents/` dir; with no subagent active it shows a neutral word that advances only on a real turn arrival. The line carries a turn-elapsed clock and flips to a `stalled` state once nothing has been written for 5 minutes (`now − lastEmitAt`), so the operator can tell a wedge from progress without SSH. It is never added to the persisted timeline. Detail and the `[webchat-activity]` observability live in [`admin-webchat-native-channel.md`](../../../.docs/admin-webchat-native-channel.md).
 
 **maxy title for public sessions.** A `role=public` webchat spawn never produces a useful Claude Code `ai-title` (an anonymous one-line visitor turn), so every public row would otherwise read identically. The webchat route (`chat.ts`) composes a deterministic title — `Web · <senderId[:8]>[ · <personId>] · <UTC YYYY-MM-DD HH:mm>` (personId present only for gated visitors) — and threads it through the native webchat gateway's public spawn (`handleInbound` → `buildPublicWebchatSpawnRequest` → `managerSpawn`) to the manager `POST /public-spawn` body as `name`. `/spawn` validates it with `validateUserTitle` and, for `role=public` only, writes it into `UserTitleStore` so it occupies the operator-rename tier and wins over `ai-title`. Admin (`/rc-spawn`) and WhatsApp titling are unchanged. Observability: every public spawn logs `[spawn] role=public … title="…"` (or `title=missing`); the manager's row builder emits `[public-title] sessionId=… unexpected titleSource=<ai|null>` on the next list read for any public row that did not resolve from the user tier.

package/payload/platform/plugins/docs/references/internals.md

@@ -95,7 +95,7 @@ If Ollama is unavailable at write time, the node is stored without an embedding
 
 The `memory-reindex` tool backfills missing embeddings by iterating nodes where `embedding IS NULL`. It uses the bounded representation (the `summary` for document/archive labels, never the raw body), embeds in batches with a per-node fallback on batch error, and **skips and continues** past a failing node — keeping skipped nodes out of the re-fetch via an exclude set — instead of aborting the whole run. `embed()`/`embedBatch()` cap oversized input (`EMBED_INPUT_MAX_CHARS`) before the Ollama POST, so a large body embeds truncated rather than throwing. Per-node `[reindex] op=embedded|skip-error` lines and a terminal `[reindex] op=done processed=N skipped=M`.
 
-`embedBatch()` also paces large batches. A document's summary plus every section body in one `/api/embed` POST pins ollama's `llama-server` across all cores for the whole batch with no idle gaps; on a passively-cooled Pi the SoC climbs past its soft-temp limit and the board thermally hard-resets. `embedBatch` splits an input array longer than `EMBED_SUBBATCH_SIZE` (default 32) into sub-batches, waiting `EMBED_SUBBATCH_COOLDOWN_MS` (default 1000) between them so the SoC gets cooling gaps; vectors are concatenated in input order. Both knobs are env-overridable for on-device tuning. The load-bearing thermal protection is the installer's `CPUQuota` cap on `ollama.service` (every embed caller is bounded there regardless of batch shape); this pacing is defence-in-depth. The UI's file-index path uses its own single-input embed client in `platform/ui/app/lib/neo4j-store.ts` (one embed per file, not a batch), so it is covered by the CPU cap, not by `embedBatch` pacing.
+`embedBatch()` also paces large batches. A document's summary plus every section body in one `/api/embed` POST pins ollama's `llama-server` across all cores for the whole batch with no idle gaps; on a passively-cooled Pi the SoC climbs past its soft-temp limit and the board thermally hard-resets. `embedBatch` splits an input array longer than the effective sub-batch size into sub-batches, waiting `EMBED_SUBBATCH_COOLDOWN_MS` (default 1000) between them so the SoC gets cooling gaps; vectors are concatenated in input order. The effective sub-batch size is the smaller of two ceilings: the thermal count ceiling `EMBED_SUBBATCH_SIZE` (default 32) and a throughput ceiling `floor(EMBED_REQUEST_TIMEOUT_MS * 0.8 / EMBED_MS_PER_INPUT)`. The throughput ceiling exists because on a CPU-only embedder a fixed 32-input POST can exceed `EMBED_REQUEST_TIMEOUT_MS` and abort the atomic ingest write, so `EMBED_MS_PER_INPUT` (the budgeted worst-case wall-time for one capped input, default 6000 ms, env-tunable) bounds each POST to 80 % of the request timeout. Every `/api/embed` POST also carries `keep_alive` (`EMBED_KEEP_ALIVE`, default `-1` = keep the model resident forever) so an interactive graph query-embed never cold-loads and blows its 5 s timeout. All knobs are env-overridable for on-device tuning. The load-bearing thermal protection is the installer's `CPUQuota` cap on `ollama.service` (every embed caller is bounded there regardless of batch shape); this pacing is defence-in-depth. The UI's file-index path uses its own single-input embed client in `platform/ui/app/lib/neo4j-store.ts` (one embed per file, not a batch), so it is covered by the CPU cap, not by `embedBatch` pacing.
 
 ---
 
@@ -400,9 +400,9 @@ Standing rules the operator gives over a channel are `Preference` nodes. Two mec
 
 **Reconcile by meaning on write (`profile-update`).** The existence check is two-tier. First an exact `(category, key)` match — the classic fast path, unchanged. When that misses, a semantic-neighbour lookup runs over the `preference_embedding` vector index, scoped to the same `accountId` and `scope:'admin'`, non-trashed. If the nearest neighbour is at or above `SAME_SUBJECT_COSINE` (0.85), the write lands on that node through the existing reinforce/update/contradict curve instead of minting a duplicate; the matched neighbours are returned in the tool result so the agent can classify future writes against real prior state. The confidence constants are unchanged — only the join key widens, so a rephrasing under a new `key` no longer forks the rule and a correction demotes the prior node rather than adding a contradictory one.
 
-**Inject the active rule-set every turn (channel gateways).** The one definition of "this account's active rules" is `@maxy/active-rules`: a bounded, floor-filtered (`confidence >= 0.4`), confidence-ordered candidate query, then semantic de-confliction (one winner per subject at the same 0.85 cosine), capped to `INJECTION_RULE_CAP` (12). `profile-read` exposes this set as `activeRules`, and the three inbound gateways (`wa-gateway`, `telegram-gateway`, `webchat-gateway`) fetch it for the effective session account and attach it as `standingRules` on the inbound frame; the channel builders prepend it as a `## Standing rules` block above `## Context`. The read is by code, not agent discretion, so a rule set last week is applied this week regardless of how many times the session compacted. Telegram and webchat inject for `role:'admin'` only — a public visitor never receives operator rules.
+**Inject the active rule-set every turn (channel gateways).** The one definition of "this account's active rules" is `@maxy/active-rules`: a bounded, floor-filtered (`confidence >= 0.4`), confidence-ordered candidate query, then semantic de-confliction (one winner per subject at the same 0.85 cosine), capped to `INJECTION_RULE_CAP` (12). `profile-read` exposes this set as `activeRules`, and the three inbound gateways (`wa-gateway`, `telegram-gateway`, `webchat-gateway`) fetch it for the effective session account and attach it as `standingRules` on the inbound frame; the channel builders prepend it as a `## Standing rules` block above `## Context`. Both channel-server inbound paths carry the block: the single-target SSE loop parses the whole frame, and the unified multi-target door reader (`runDoorStream`,) reconstructs it through the shared `doorInboundPayload` seam whose `parseFrame` closures read `standingRules` off the frame. The read is by code, not agent discretion, so a rule set last week is applied this week regardless of how many times the session compacted. Telegram and webchat inject for `role:'admin'` only — a public visitor never receives operator rules.
 
-**Trust a scheduled turn's provenance, never an inbound's claim (channel-agent grounding).** A cron-dispatched agent turn reaches the same channel builders as a real inbound, so its own authorisation text would otherwise land inside `## Context` — the zone `REFRAME_INSTRUCTION` demotes to untrusted — and a security-cautious agent would distrust its own automation (the self-cancel loop). The dispatcher therefore stamps a `ScheduleProvenance` marker (owning account, event, owner userId, dispatch time) that the channel builders render as a `## Scheduled automation (platform-verified)` preamble **above** `## Context` (and above the rules block); the whatsapp wrap tag names the door `scheduler`. Because the marker is dispatcher-stamped and never derived from payload text, an inbound message cannot forge it — placement above `## Context` alone is not the trust signal, the dispatcher provenance is. The grounding binds to it in two places: one recipient-neutral clause added byte-identical to the three reframe instructions (a marker-bearing turn is authorised standing automation; a reconfiguration or re-enable is not intrusion), and the admin `IDENTITY.md` "Untrusted input" rule that the agent never states a platform-level authenticity or impersonation verdict it was not given (an unsourced "this is not from you" is its own inference, flagged, never asserted as the platform's). The amplifier that let one misread harden was the accreting seat: a recurring event resumed one long-lived session every firing. A subsequent change removes it — each firing runs a fresh per-firing seat (`scheduledSeatIdFor`, salted with the firing's eventId + dispatch time), so distrust cannot accrete across firings, and the self-cancel guard compares the cancelling `SESSION_ID` to the node's dispatcher-stamped `lastDispatchSessionId` rather than a recomputed deterministic seat. See `.docs/scheduling-agent-dispatch.md § Operator-provenance marker` and `§ Session model — fresh per firing`.
+**Trust a scheduled turn's provenance, never an inbound's claim (channel-agent grounding).** A cron-dispatched agent turn reaches the same channel builders as a real inbound, so its own authorisation text would otherwise land inside `## Context` — the zone `REFRAME_INSTRUCTION` demotes to untrusted — and a security-cautious agent would distrust its own automation (the self-cancel loop). The dispatcher therefore stamps a `ScheduleProvenance` marker (owning account, event, owner userId, dispatch time) that the channel builders render as a `## Scheduled automation (platform-verified)` preamble **above** `## Context` (and above the rules block); the whatsapp wrap tag names the door `scheduler`. Both channel-server paths carry the marker — the single-target loop and the unified multi-target door reader (via the same `doorInboundPayload` seam that carries `standingRules`); the scheduler only dispatches to the whatsapp/telegram door, so a webchat frame never bears one. Because the marker is dispatcher-stamped and never derived from payload text, an inbound message cannot forge it — placement above `## Context` alone is not the trust signal, the dispatcher provenance is. The grounding binds to it in two places: one recipient-neutral clause added byte-identical to the three reframe instructions (a marker-bearing turn is authorised standing automation; a reconfiguration or re-enable is not intrusion), and the admin `IDENTITY.md` "Untrusted input" rule that the agent never states a platform-level authenticity or impersonation verdict it was not given (an unsourced "this is not from you" is its own inference, flagged, never asserted as the platform's). The amplifier that let one misread harden was the accreting seat: a recurring event resumed one long-lived session every firing. A subsequent change removes it — each firing runs a fresh per-firing seat (`scheduledSeatIdFor`, salted with the firing's eventId + dispatch time), so distrust cannot accrete across firings, and the self-cancel guard compares the cancelling `SESSION_ID` to the node's dispatcher-stamped `lastDispatchSessionId` rather than a recomputed deterministic seat. See `.docs/scheduling-agent-dispatch.md § Operator-provenance marker` and `§ Session model — fresh per firing`.
 
 **Observability.** `[preference-write] op=reconcile … mode=<reinforce|update|contradict|new> similarity=…` — a stream of `mode=new` for subjects that already exist is the duplicate-minting signature. `[preference-inject] op=inject channel=<wa|tg|web> injected=<N>` — `injected=0` on an account with stored rules is the write-only regression re-appearing. `[preference-audit] op=drift accountId=… storedActive=… injectedActive=… duplicateClusters=…` — the standing reconciliation audit (claude-session-manager, 5-minute tick) flags any account whose store holds more active rows than injection would surface, the no-event detector for drift.
 

package/payload/platform/plugins/docs/references/workflows.md

@@ -0,0 +1,61 @@
+# Workflows Guide
+
+## What a Workflow Is
+
+A workflow is a saved, named sequence of steps that {{productName}} runs for you on demand. Each step calls one tool, and steps can pass their results to later steps. Use a workflow when you have a recurring process with two or more steps that you would otherwise ask for by hand every time. A single one-off action does not need a workflow.
+
+Examples of good workflows:
+
+- "When a new lead comes in, create a contact, log it, and send me a notification."
+- "Every time I book a viewing, add the calendar event and message the client the details."
+
+## Creating a Workflow
+
+Describe the process to {{productName}} naturally:
+
+- "Set up a workflow: when I get a new lead, create the contact and send a Telegram notification."
+- "Make a follow-up workflow that adds a calendar reminder and drafts an email."
+
+{{productName}} will confirm the name, the steps, and how data flows between them before saving. If a step needs a tool from a plugin you have not installed yet, the workflow is saved as a draft and activates automatically once that plugin is in place.
+
+## Declared Inputs
+
+Most workflows need a few values that are specific to each run, for example a customer name or a chosen option. A workflow can declare these up front as its inputs. Declaring them means {{productName}} asks you the same questions every time it runs the workflow, so nothing is forgotten and nothing is guessed.
+
+Each declared input has a question to ask you, a type, whether it is required, and an optional default. When a value has a default, {{productName}} offers it and you can accept or change it.
+
+You do not manage inputs by hand. When you describe a workflow that clearly needs a per-run value, {{productName}} proposes the input and confirms it with you. At run time it reads the list and asks you each question before starting.
+
+## Running a Workflow
+
+Ask {{productName}} to run it:
+
+- "Run the new-lead workflow."
+- "Start the viewing follow-up for the Cardinal Roofing booking."
+
+Before it starts, {{productName}} gathers every required input by asking you. If you leave a required value out, the workflow does not start and no steps run. {{productName}} tells you which value is missing and asks for it, then runs the workflow with the complete set. This is deliberate: the workflow refuses to run half-finished rather than failing partway through.
+
+## Seeing What Ran
+
+Ask for the history:
+
+- "Show me recent workflow runs."
+- "Did the new-lead workflow run today?"
+
+You get each run's status, timing, and how many steps completed, were skipped, or failed. If a step failed, {{productName}} can show you which one and why.
+
+## Managing Workflows
+
+Tell {{productName}} naturally:
+
+- "List my workflows."
+- "Show me the follow-up workflow."
+- "Pause the new-lead workflow." or "Turn the new-lead workflow back on."
+- "Change the follow-up workflow so it also messages me."
+- "Delete the old onboarding workflow."
+
+Pausing keeps a workflow but stops it running. Editing replaces the steps or the inputs with the new version you describe. Deleting removes the workflow and its run history, so {{productName}} confirms with you first.
+
+## Scheduling a Workflow
+
+A workflow can run on a schedule instead of on demand. Tell {{productName}} when you want it to run, for example "run the daily summary workflow every morning at eight," and it sets up the schedule. Scheduled runs happen with no one present, so a workflow that needs you to supply inputs is best run on demand rather than scheduled.

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embed-throughput.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=embed-throughput.test.d.ts.map

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embed-throughput.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed-throughput.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/embed-throughput.test.ts"],"names":[],"mappings":""}

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embed-throughput.test.js

@@ -0,0 +1,92 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+// Record the size of every /api/embed POST's input array, and return one
+// zero-vector per input so the index-aligned contract can be checked.
+function stubFetchRecordingBatchSizes(sizes) {
+    vi.stubGlobal("fetch", vi.fn(async (_url, init) => {
+        const body = JSON.parse(init.body);
+        const inputs = Array.isArray(body.input) ? body.input : [body.input];
+        sizes.push(inputs.length);
+        return {
+            ok: true,
+            json: async () => ({ embeddings: inputs.map(() => [0]) }),
+        };
+    }));
+}
+describe("throughput-aware embed sub-batch sizing", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        vi.resetModules();
+        process.env.EMBED_REQUEST_TIMEOUT_MS = "120000";
+        process.env.EMBED_SUBBATCH_SIZE = "32";
+        process.env.EMBED_SUBBATCH_COOLDOWN_MS = "0"; // no real sleeps in test
+    });
+    afterEach(() => {
+        delete process.env.EMBED_REQUEST_TIMEOUT_MS;
+        delete process.env.EMBED_SUBBATCH_SIZE;
+        delete process.env.EMBED_SUBBATCH_COOLDOWN_MS;
+        delete process.env.EMBED_MS_PER_INPUT;
+    });
+    it("caps each POST at min(count, duration) and keeps vectors index-aligned", async () => {
+        process.env.EMBED_MS_PER_INPUT = "6000"; // durationCap = floor(120000*0.8/6000) = 16
+        const sizes = [];
+        stubFetchRecordingBatchSizes(sizes);
+        const { embedBatch } = await import("../../lib/embeddings.js");
+        const texts = Array.from({ length: 35 }, (_, i) => `section ${i}`);
+        const out = await embedBatch(texts);
+        expect(out).toHaveLength(35);
+        expect(sizes.every((n) => n <= 16)).toBe(true); // duration cap wins over 32
+        expect(sizes.reduce((a, b) => a + b, 0)).toBe(35); // every input embedded once
+    });
+    it("lets the count cap win when per-input duration is small", async () => {
+        process.env.EMBED_MS_PER_INPUT = "1000"; // durationCap = floor(120000*0.8/1000) = 96 -> count cap 32 wins
+        const sizes = [];
+        stubFetchRecordingBatchSizes(sizes);
+        const { embedBatch } = await import("../../lib/embeddings.js");
+        await embedBatch(Array.from({ length: 40 }, (_, i) => `s${i}`));
+        expect(Math.max(...sizes)).toBe(32);
+    });
+});
+describe("embed keep_alive + per-POST breadcrumb", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        vi.resetModules();
+        process.env.EMBED_SUBBATCH_COOLDOWN_MS = "0";
+    });
+    afterEach(() => {
+        delete process.env.EMBED_KEEP_ALIVE;
+        delete process.env.EMBED_SUBBATCH_COOLDOWN_MS;
+    });
+    it("sends keep_alive=-1 by default in the POST body", async () => {
+        let seenBody = {};
+        vi.stubGlobal("fetch", vi.fn(async (_u, init) => {
+            seenBody = JSON.parse(init.body);
+            return { ok: true, json: async () => ({ embeddings: [[0]] }) };
+        }));
+        const { embed } = await import("../../lib/embeddings.js");
+        await embed("hello");
+        expect(seenBody.keep_alive).toBe(-1);
+    });
+    it("treats an empty-string EMBED_KEEP_ALIVE env as unset (defaults to -1)", async () => {
+        process.env.EMBED_KEEP_ALIVE = "";
+        let seenBody = {};
+        vi.stubGlobal("fetch", vi.fn(async (_u, init) => {
+            seenBody = JSON.parse(init.body);
+            return { ok: true, json: async () => ({ embeddings: [[0]] }) };
+        }));
+        const { embed } = await import("../../lib/embeddings.js");
+        await embed("hello");
+        expect(seenBody.keep_alive).toBe(-1);
+    });
+    it("writes a per-POST breadcrumb on success", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => ({ ok: true, json: async () => ({ embeddings: [[0]] }) })));
+        const writes = [];
+        vi.spyOn(process.stderr, "write").mockImplementation((s) => {
+            writes.push(String(s));
+            return true;
+        });
+        const { embed } = await import("../../lib/embeddings.js");
+        await embed("hello");
+        expect(writes.some((w) => /\[embed\] op=post inputs=1 /.test(w))).toBe(true);
+    });
+});
+//# sourceMappingURL=embed-throughput.test.js.map

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embed-throughput.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed-throughput.test.js","sourceRoot":"","sources":["../../../src/tools/__tests__/embed-throughput.test.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embed-timeout.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=embed-timeout.test.d.ts.map

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embed-timeout.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed-timeout.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/embed-timeout.test.ts"],"names":[],"mappings":""}

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embed-timeout.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+describe("embed request timeout + enriched errors", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        process.env.EMBED_REQUEST_TIMEOUT_MS = "50";
+        // These tests assert enriched errors for a whole POST (inputs=2), not
+        // sub-batch sizing. Throughput-aware sizing (Task 1533) derives the POST
+        // size from the timeout, and a 50 ms timeout would otherwise floor the
+        // batch to one input per POST. Pin a 1 ms per-input estimate so the
+        // 2-input batch stays a single POST and the error still names inputs=2.
+        process.env.EMBED_MS_PER_INPUT = "1";
+        vi.resetModules();
+    });
+    afterEach(() => {
+        delete process.env.EMBED_REQUEST_TIMEOUT_MS;
+        delete process.env.EMBED_MS_PER_INPUT;
+    });
+    it("rejects promptly with an enriched timeout error, not a bare fetch failed", async () => {
+        // Honour the abort signal: never resolve, reject when the timeout fires.
+        vi.stubGlobal("fetch", vi.fn((_u, init) => new Promise((_res, rej) => {
+            init.signal.addEventListener("abort", () => rej(init.signal.reason ?? new Error("aborted")));
+        })));
+        const { embed } = await import("../../lib/embeddings.js");
+        const start = Date.now();
+        await expect(embed("hello")).rejects.toThrow(/timed out/i);
+        // Nowhere near undici's 300000ms default.
+        expect(Date.now() - start).toBeLessThan(5000);
+    });
+    it("names input count and largest input size in the timeout error", async () => {
+        vi.stubGlobal("fetch", vi.fn((_u, init) => new Promise((_res, rej) => {
+            init.signal.addEventListener("abort", () => rej(init.signal.reason ?? new Error("aborted")));
+        })));
+        const { embedBatch } = await import("../../lib/embeddings.js");
+        await expect(embedBatch(["a", "bbbb"])).rejects.toThrow(/timed out.*inputs=2.*largestInputChars=4/s);
+    });
+    it("names the underlying cause on a connection failure, not a bare fetch failed", async () => {
+        // Mirrors undici on a refused connection: TypeError("fetch failed", { cause }).
+        vi.stubGlobal("fetch", vi.fn(async () => {
+            throw new TypeError("fetch failed", {
+                cause: new Error("connect ECONNREFUSED 127.0.0.1:11434"),
+            });
+        }));
+        const { embed } = await import("../../lib/embeddings.js");
+        await expect(embed("hello")).rejects.toThrow(/failed.*inputs=1.*largestInputChars=5.*ECONNREFUSED/s);
+    });
+    it("enriches an HTTP error with status, input count and largest input size", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => ({
+            ok: false,
+            status: 400,
+            text: async () => '{"error":"the input length exceeds the context length"}',
+        })));
+        const { embedBatch } = await import("../../lib/embeddings.js");
+        await expect(embedBatch(["a", "bbbb"])).rejects.toThrow(/400.*inputs=2.*largestInputChars=4/s);
+    });
+});
+//# sourceMappingURL=embed-timeout.test.js.map

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embed-timeout.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed-timeout.test.js","sourceRoot":"","sources":["../../../src/tools/__tests__/embed-timeout.test.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embeddings-cap.test.js

@@ -31,4 +31,60 @@ describe("embed input capping", () => {
         expect(sent[1].length).toBe(EMBED_INPUT_MAX_CHARS);
     });
 });
+describe("token-safe cap default", () => {
+    beforeEach(() => vi.restoreAllMocks());
+    it("defaults to 6000 chars, provably under a 2048-token context at 3 chars/token", async () => {
+        const { EMBED_INPUT_MAX_CHARS } = await import("../../lib/embeddings.js");
+        expect(EMBED_INPUT_MAX_CHARS).toBe(6000);
+        // 6000 chars / 3 chars-per-token = 2000 tokens <= 2048 context
+        expect(EMBED_INPUT_MAX_CHARS / 3).toBeLessThanOrEqual(2048);
+    });
+    it("caps a dense 24k-char emoji/markup body to <= 6000 chars before POST", async () => {
+        const dense = "🟢🟡🔴 ## Observatory\n".repeat(1400); // ~24k chars
+        let sent = "";
+        vi.stubGlobal("fetch", vi.fn(async (_u, init) => {
+            sent = JSON.parse(init.body).input;
+            return {
+                ok: true,
+                json: async () => ({ embeddings: [[0.1]] }),
+            };
+        }));
+        const { embed, EMBED_INPUT_MAX_CHARS } = await import("../../lib/embeddings.js");
+        await embed(dense);
+        expect(sent.length).toBeLessThanOrEqual(6000);
+        expect(sent.length).toBe(EMBED_INPUT_MAX_CHARS);
+    });
+});
+describe("multi-section document batch (exitchatcontrol regression)", () => {
+    beforeEach(() => vi.restoreAllMocks());
+    it("embeds a mix of short and dense oversized sections with no 400 and no timeout", async () => {
+        // Resembles ingesting a document: a summary plus several sections, one of
+        // them the dense emoji/markup 'observatory' chapter that used to 400.
+        const sections = [
+            "Exit Chat Control summary.",
+            "🟢🟡🔴 ## Observatory\n".repeat(1400), // ~30k dense chars
+            "A normal-length prose section about the campaign.",
+            "🔴🔴🔴 status matrix ".repeat(600),
+            "Closing section.",
+        ];
+        const sentInputs = [];
+        vi.stubGlobal("fetch", vi.fn(async (_u, init) => {
+            const inp = JSON.parse(init.body).input;
+            sentInputs.push(inp);
+            return {
+                ok: true,
+                json: async () => ({ embeddings: inp.map(() => [0.1]) }),
+            };
+        }));
+        const { embedBatch } = await import("../../lib/embeddings.js");
+        const vectors = await embedBatch(sections);
+        // One vector per section, index-aligned.
+        expect(vectors).toHaveLength(sections.length);
+        // Every input actually POSTed was within the token-safe cap.
+        for (const batch of sentInputs) {
+            for (const s of batch)
+                expect(s.length).toBeLessThanOrEqual(6000);
+        }
+    });
+});
 //# sourceMappingURL=embeddings-cap.test.js.map

package/payload/platform/plugins/memory/mcp/dist/tools/__tests__/embeddings-cap.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"embeddings-cap.test.js","sourceRoot":"","sources":["../../../src/tools/__tests__/embeddings-cap.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAE9D,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;IAEvC,EAAE,CAAC,mFAAmF,EAAE,KAAK,IAAI,EAAE;QACjG,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,SAAkB,CAAC;QACvB,EAAE,CAAC,UAAU,CACX,OAAO,EACP,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,IAAsB,EAAE,EAAE;YACnD,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC;YACxC,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;aAC1B,CAAC;QAC3B,CAAC,CAAC,CACH,CAAC;QACF,MAAM,EAAE,KAAK,EAAE,qBAAqB,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACjF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAChC,MAAM,CAAE,SAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kEAAkE,EAAE,KAAK,IAAI,EAAE;QAChF,IAAI,IAAI,GAAa,EAAE,CAAC;QACxB,EAAE,CAAC,UAAU,CACX,OAAO,EACP,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAU,EAAE,IAAsB,EAAE,EAAE;YACjD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC;YACnC,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;aACnC,CAAC;QAC3B,CAAC,CAAC,CACH,CAAC;QACF,MAAM,EAAE,UAAU,EAAE,qBAAqB,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACtF,MAAM,UAAU,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAChD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"embeddings-cap.test.js","sourceRoot":"","sources":["../../../src/tools/__tests__/embeddings-cap.test.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/whatsapp/mcp/dist/resolve-read-account.d.ts

@@ -2,6 +2,13 @@
  *  admin reading a specific account); otherwise the calling session's own account
  *  (`ACCOUNT_ID`, stamped per-spawn by pty-spawner — the sub-account for a sub-account
  *  session); otherwise the legacy `"default"`. An empty env value is treated as
- *  absent so a boot-tolerant empty ACCOUNT_ID never scopes reads to "". */
+ *  absent so a boot-tolerant empty ACCOUNT_ID never scopes reads to "".
+ *
+ *  `"default"` is a sentinel, not a store key: the in-memory message store is keyed
+ *  by platform UUID (Task 1532), so the platform read routes resolve `"default"` (the
+ *  legacy waname / connection map key) to the socket-owning account's UUID before
+ *  hitting the store (`resolveReadStoreKey`, Task 1535). This resolver has no access
+ *  to the connection map — the UUID lives in the platform server, not the MCP env —
+ *  so the sentinel is produced here and resolved there. */
 export declare function resolveReadAccountId(explicit: string | undefined, envAccountId: string | undefined): string;
 //# sourceMappingURL=resolve-read-account.d.ts.map

package/payload/platform/plugins/whatsapp/mcp/dist/resolve-read-account.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-read-account.d.ts","sourceRoot":"","sources":["../src/resolve-read-account.ts"],"names":[],"mappings":"AAAA;;;;2EAI2E;AAC3E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,CAIR"}
+{"version":3,"file":"resolve-read-account.d.ts","sourceRoot":"","sources":["../src/resolve-read-account.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;2DAW2D;AAC3D,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,CAIR"}

package/payload/platform/plugins/whatsapp/mcp/dist/resolve-read-account.js

@@ -2,7 +2,14 @@
  *  admin reading a specific account); otherwise the calling session's own account
  *  (`ACCOUNT_ID`, stamped per-spawn by pty-spawner — the sub-account for a sub-account
  *  session); otherwise the legacy `"default"`. An empty env value is treated as
- *  absent so a boot-tolerant empty ACCOUNT_ID never scopes reads to "". */
+ *  absent so a boot-tolerant empty ACCOUNT_ID never scopes reads to "".
+ *
+ *  `"default"` is a sentinel, not a store key: the in-memory message store is keyed
+ *  by platform UUID (Task 1532), so the platform read routes resolve `"default"` (the
+ *  legacy waname / connection map key) to the socket-owning account's UUID before
+ *  hitting the store (`resolveReadStoreKey`, Task 1535). This resolver has no access
+ *  to the connection map — the UUID lives in the platform server, not the MCP env —
+ *  so the sentinel is produced here and resolved there. */
 export function resolveReadAccountId(explicit, envAccountId) {
     if (explicit)
         return explicit;

package/payload/platform/plugins/whatsapp/mcp/dist/resolve-read-account.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-read-account.js","sourceRoot":"","sources":["../src/resolve-read-account.ts"],"names":[],"mappings":"AAAA;;;;2EAI2E;AAC3E,MAAM,UAAU,oBAAoB,CAClC,QAA4B,EAC5B,YAAgC;IAEhC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,IAAI,YAAY,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IACjE,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"resolve-read-account.js","sourceRoot":"","sources":["../src/resolve-read-account.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;2DAW2D;AAC3D,MAAM,UAAU,oBAAoB,CAClC,QAA4B,EAC5B,YAAgC;IAEhC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,IAAI,YAAY,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IACjE,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/payload/platform/plugins/work/mcp/dist/lib/embeddings.d.ts

@@ -1,7 +1,13 @@
 /**
- * Non-fatal embedding: returns empty array if Ollama is unavailable.
- * Task operations succeed without embeddings — memory-search just won't
- * find the task by similarity until the next update re-embeds.
+ * Non-fatal embedding: returns an empty array if the shared embed client fails
+ * (Ollama unavailable, slow or wedged past the request timeout, or a dense body
+ * that still errors after the token-safe cap). Task operations succeed without
+ * an embedding — memory-search just will not find the node by similarity until
+ * the next update re-embeds. Delegates the POST to platform/lib/embed-client so
+ * the token-safe cap, the explicit request timeout, and the cause-naming error
+ * are inherited (Task 1530). The failure the shared client would throw is caught
+ * here and downgraded to `[]`, but first written as a greppable breadcrumb so a
+ * swallowed embed is diagnosable rather than silent.
  */
 export declare function computeEmbedding(text: string): Promise<number[]>;
 //# sourceMappingURL=embeddings.d.ts.map

package/payload/platform/plugins/work/mcp/dist/lib/embeddings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/lib/embeddings.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAatE"}
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/lib/embeddings.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAetE"}

package/payload/platform/plugins/work/mcp/dist/lib/embeddings.js

@@ -1,23 +1,27 @@
-const OLLAMA_URL = process.env.OLLAMA_URL ?? "http://localhost:11434";
-const EMBED_MODEL = process.env.EMBED_MODEL ?? "nomic-embed-text";
+import { embed } from "../../../../../lib/embed-client/dist/index.js";
 /**
- * Non-fatal embedding: returns empty array if Ollama is unavailable.
- * Task operations succeed without embeddings — memory-search just won't
- * find the task by similarity until the next update re-embeds.
+ * Non-fatal embedding: returns an empty array if the shared embed client fails
+ * (Ollama unavailable, slow or wedged past the request timeout, or a dense body
+ * that still errors after the token-safe cap). Task operations succeed without
+ * an embedding — memory-search just will not find the node by similarity until
+ * the next update re-embeds. Delegates the POST to platform/lib/embed-client so
+ * the token-safe cap, the explicit request timeout, and the cause-naming error
+ * are inherited (Task 1530). The failure the shared client would throw is caught
+ * here and downgraded to `[]`, but first written as a greppable breadcrumb so a
+ * swallowed embed is diagnosable rather than silent.
  */
 export async function computeEmbedding(text) {
     try {
-        const res = await fetch(`${OLLAMA_URL}/api/embed`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ model: EMBED_MODEL, input: text }),
-        });
-        if (!res.ok)
-            return [];
-        const data = (await res.json());
-        return data.embeddings[0] ?? [];
+        // Coerce to [] so the returns-[] contract holds even on the shared client's
+        // one non-throwing empty-result path: an empty input string makes ollama
+        // answer HTTP 200 with `embeddings: []`, so embed() resolves undefined
+        // rather than rejecting. The old local client guarded this with the same
+        // `?? []`; keep it so a caller never reads `.length` on undefined.
+        return (await embed(text)) ?? [];
     }
-    catch {
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[work-embed] op=failed inputChars=${text.length} reason=${reason}\n`);
         return [];
     }
 }

package/payload/platform/plugins/work/mcp/dist/lib/embeddings.js.map

@@ -1 +1 @@
-{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../src/lib/embeddings.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,wBAAwB,CAAC;AACtE,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,kBAAkB,CAAC;AAElE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,UAAU,YAAY,EAAE;YACjD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;SAC1D,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA+B,CAAC;QAC9D,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../src/lib/embeddings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,+CAA+C,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,IAAI,CAAC;QACH,4EAA4E;QAC5E,yEAAyE;QACzE,uEAAuE;QACvE,yEAAyE;QACzE,mEAAmE;QACnE,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,qCAAqC,IAAI,CAAC,MAAM,WAAW,MAAM,IAAI,CACtE,CAAC;QACF,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/payload/platform/plugins/workflows/PLUGIN.md

@@ -66,6 +66,22 @@ Every step is `type: "tool"`:
 - **retryLimit** — max retries when onFailure is `retry` (max 3)
 - **outputKey** — name under which this step's output is stored for use in subsequent step templates
 
+### Declared inputs
+
+A workflow can declare the inputs it needs before it can run. This is the front half of gather-then-execute: the contract states what the workflow requires, `workflow-manager` gathers those values from the operator, and `workflow-execute` refuses to run any step until every required input is present. Because each variable choice is resolved with the operator at collection time, the run context is flat and concrete and the linear step DAG is all execution needs.
+
+Each entry in `inputs` has:
+
+- **key** — the context key this input provides, referenced as `{{key}}` in step params
+- **prompt** — the operator-facing question that gathers the value
+- **type** — `string`, `number`, `boolean`, or `object`
+- **required** — when true, execution is refused until the input is present
+- **default** — optional value seeded when the input is absent; a required input with a default is satisfied without asking
+
+The contract is a full-replacement field on both `workflow-create` and `workflow-update`, stored like step params. A workflow that declares no inputs runs exactly as before — the gate passes on an empty contract.
+
+A scalar input referenced as `{{key}}` resolves to its value (for example `{{customerName}}` becomes `Cardinal Roofing`), not a wrapper object.
+
 ### Capability validation
 
 At creation time, every step's referenced plugin directory and built MCP server are checked. If any capability is missing, the workflow's status is set to `draft` with specific error messages listing which plugins or tools are unavailable. Only `active` workflows can be executed.
@@ -87,11 +103,14 @@ Active workflows are discoverable via `workflow-list` and via `memory-search` (t
 ## Execution
 
 Use `workflow-execute` to run a workflow. The engine:
-1. Loads the workflow and its steps
-2. Resolves step dependencies into execution order (topological sort)
-3. For each step: resolves `{{template.variables}}` from context and prior step outputs, spawns the target plugin's MCP server, and calls the specified tool
-4. Records every step's outcome as a StepResult node
-5. Creates a WorkflowRun node with the overall status
+1. Loads the workflow, its steps, and its declared input contract
+2. Pre-flight gate: applies any declared defaults, then checks that every required input is present. If any are missing it returns `status: "incomplete"` with the missing keys, runs zero steps, and creates no WorkflowRun node
+3. Resolves step dependencies into execution order (topological sort)
+4. For each step: resolves `{{template.variables}}` from context and prior step outputs, spawns the target plugin's MCP server, and calls the specified tool
+5. Records every step's outcome as a StepResult node
+6. Creates a WorkflowRun node with the overall status
+
+The pre-flight gate runs before any WorkflowRun is created, so a refused execution leaves no orphan `running` run behind. A missing required input is caught up front by the contract rather than late, mid-pipeline, as an unresolved-template failure.
 
 ### Template variables
 
@@ -115,6 +134,7 @@ Each step declares an `onFailure` policy:
 | `completed` | Every step succeeded |
 | `partial` | Finished, but one or more steps were skipped |
 | `failed` | A step failed with abort policy, execution stopped |
+| `incomplete` | Refused at the pre-flight gate — a required input was missing, zero steps ran, no WorkflowRun was created |
 
 ### Step status values
 
@@ -150,11 +170,11 @@ Scheduled workflows are dispatched by `check-due-events`, which the installer ar
 
 ## Tools
 
-- `workflow-create` — Create a workflow with name, description, and tool steps
+- `workflow-create` — Create a workflow with name, description, tool steps, and an optional declared input contract
 - `workflow-list` — List workflows with status and step counts
-- `workflow-get` — Fetch a workflow with full step details
-- `workflow-update` — Update name, description, steps (full replacement), or status
+- `workflow-get` — Fetch a workflow with full step details and its declared inputs
+- `workflow-update` — Update name, description, steps (full replacement), inputs (full replacement), or status
 - `workflow-delete` — Permanently remove a workflow and all history
 - `workflow-validate` — Re-check step capabilities and update status
-- `workflow-execute` — Execute a workflow with optional runtime context
+- `workflow-execute` — Execute a workflow with optional runtime context; refuses with `status: "incomplete"` when a required input is missing
 - `workflow-runs` — Query execution history with optional filters