@rubytech/create-realagent-code 0.1.575 → 0.1.577

package/payload/platform/lib/dispatch-read/src/__tests__/allocate.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { selectCandidates, overlaps } from "../allocate.js";
+import type { DispatchConfig } from "../types.js";
+
+const cfg = {
+  statuses: { job: [], visit: [], jobTransitions: [], visitTransitions: [] },
+  jobTypes: [{ name: "Boiler", requiredQualification: "gas", defaultDurationMin: 60 }],
+  workers: [
+    { workerId: "w1", name: "Ann", qualifications: ["gas"], workingHours: {} },
+    { workerId: "w2", name: "Ben", qualifications: [], workingHours: {} },
+  ],
+  records: { checklists: {}, requiredBeforeTerminal: {} },
+  vocabulary: { job: "job", visit: "visit", worker: "worker" },
+  vehicles: { enabled: false },
+} as unknown as DispatchConfig;
+
+describe("selectCandidates, from the shared lib", () => {
+  it("offers a qualified worker and names why the other is excluded", () => {
+    const r = selectCandidates({ jobType: "Boiler", cfg, commitments: new Map() });
+    expect(r.offered.map((c) => c.workerId)).toEqual(["w1"]);
+    expect(r.excluded).toEqual([{ workerId: "w2", reason: "missing-qualification" }]);
+    expect(r.required).toBe("gas");
+  });
+
+  it("offers a busy qualified worker WITH the conflict shown, never dropped", () => {
+    const busy = new Map([["w1", [{ visitId: "v9", start: "a", end: "b" }]]]);
+    const r = selectCandidates({ jobType: "Boiler", cfg, commitments: busy });
+    expect(r.offered).toHaveLength(1);
+    expect(r.offered[0].conflicts).toHaveLength(1);
+  });
+
+  it("excludes nobody for an unknown job type, because every reason would be a lie", () => {
+    const r = selectCandidates({ jobType: "Nope", cfg, commitments: new Map() });
+    expect(r).toEqual({ offered: [], excluded: [], required: "" });
+  });
+
+  it("treats touching endpoints as no overlap", () => {
+    expect(overlaps({ start: "1", end: "2" }, { start: "2", end: "3" })).toBe(false);
+    expect(overlaps({ start: "1", end: "3" }, { start: "2", end: "4" })).toBe(true);
+  });
+});

package/payload/platform/lib/dispatch-read/src/allocate.ts

@@ -0,0 +1,89 @@
+/**
+ * Who can be sent to this job, and why the others cannot.
+ *
+ * The rule that matters: **a qualified worker who is already committed in the
+ * window is offered WITH the conflict shown, never dropped.** The office
+ * routinely double-books on purpose — a job runs short, a customer is on the
+ * way home, an engineer volunteers. A tool that silently removes the busy
+ * option makes that decision for them and gives no way to see it was made.
+ *
+ * Only a missing qualification excludes, and every exclusion is named with its
+ * worker and its reason, because `offered=0` with no explanation is the shape a
+ * quiet day and an unstaffable job type share.
+ *
+ * It lives in this shared lib rather than in the dispatch plugin because the
+ * portal visits push runs in `platform/ui` and cannot import a plugin's build
+ * output, and a second implementation of qualification and clash is the defect
+ * `functions/api/visits.ts:33-36` names: a gate written once per client is a
+ * gate got wrong once per client. Task 2510 moved `buildVisitKeyboard` here for
+ * the same reason. The dispatch plugin re-exports both from
+ * `mcp/src/lib/allocate.ts`, which is the import site its tools and tests
+ * already name.
+ */
+import type { DispatchConfig } from "./types.js";
+// `Commitment` is `readCommitments`'s own return shape and is declared once, in
+// read.ts. The dispatch plugin carried a second structurally-identical
+// declaration beside its copy of this file; consolidating to one is part of the
+// move, because two declarations of one contract can drift on a field.
+import type { Commitment } from "./read.js";
+
+export type { Commitment };
+
+export interface Candidate {
+  readonly workerId: string;
+  readonly name: string;
+  /** Commitments overlapping the requested window. Empty means free. */
+  readonly conflicts: readonly Commitment[];
+}
+
+export interface Exclusion {
+  readonly workerId: string;
+  readonly reason: "missing-qualification";
+}
+
+export interface SelectCandidatesParams {
+  readonly jobType: string;
+  readonly cfg: DispatchConfig;
+  /** Committed visits per workerId, already narrowed to the window. */
+  readonly commitments: ReadonlyMap<string, readonly Commitment[]>;
+}
+
+export interface CandidateSelection {
+  readonly offered: readonly Candidate[];
+  readonly excluded: readonly Exclusion[];
+  /** The qualification the job type demands, echoed for the log line. */
+  readonly required: string;
+}
+
+export function selectCandidates(params: SelectCandidatesParams): CandidateSelection {
+  const { jobType, cfg, commitments } = params;
+  const type = cfg.jobTypes.find((t) => t.name === jobType);
+  if (!type) {
+    // An unknown job type is the caller's error, not a staffing outcome. Every
+    // worker is excluded for a reason that would be a lie, so none are: the
+    // caller checks the type before asking.
+    return { offered: [], excluded: [], required: "" };
+  }
+  const offered: Candidate[] = [];
+  const excluded: Exclusion[] = [];
+  for (const worker of cfg.workers) {
+    if (!worker.qualifications.includes(type.requiredQualification)) {
+      excluded.push({ workerId: worker.workerId, reason: "missing-qualification" });
+      continue;
+    }
+    offered.push({
+      workerId: worker.workerId,
+      name: worker.name,
+      conflicts: commitments.get(worker.workerId) ?? [],
+    });
+  }
+  return { offered, excluded, required: type.requiredQualification };
+}
+
+/** `[a, b)` overlap. Touching endpoints do not overlap. */
+export function overlaps(
+  a: { start: string; end: string },
+  b: { start: string; end: string },
+): boolean {
+  return a.start < b.end && b.start < a.end;
+}

package/payload/platform/lib/dispatch-read/src/index.ts

@@ -30,6 +30,20 @@ export {
 } from "./keyboard.js";
 export type { DispatchButton, VisitKeyboard } from "./keyboard.js";
 
+// Task 2511 — qualification and clash, shared by the dispatch tools and the
+// portal visits push. One implementation, for the reason allocate.ts states:
+// the push runs in platform/ui and cannot import a plugin's build output, and a
+// second copy of these rules is a gate got wrong once per client.
+// `Commitment` is NOT re-exported here: it is `readCommitments`'s own shape,
+// declared once in read.ts and already exported below.
+export { overlaps, selectCandidates } from "./allocate.js";
+export type {
+  Candidate,
+  CandidateSelection,
+  Exclusion,
+  SelectCandidatesParams,
+} from "./allocate.js";
+
 export { withSession } from "./session.js";
 export { resolveAccountZone } from "./zone.js";
 export {

package/payload/platform/plugins/admin/hooks/__tests__/prompt-optimiser-compliance.test.sh

@@ -66,10 +66,15 @@ CHANNEL_REFRAME_MULTI='{"type":"user","isMeta":true,"message":{"role":"user","co
 # the reader anchor, so a rules-present turn is evaluated identically to a
 # rules-absent one; without the strip the turn no longer starts with ## Context
 # and the hook silently stops flagging on exactly the rule-carrying turns.
-CHANNEL_REFRAME_RULES='{"type":"user","isMeta":true,"message":{"role":"user","content":"<channel source=\"whatsapp-channel\">## Standing rules\n- Always greet the client by name\n- Use British spelling\n\n## Context\nplease draft the works order PDF for order 926\n\n## Instruction\nChoose the installed specialist that owns this request and dispatch it with the Agent tool.</channel>"}}'
+# Task 2562 — the header is now `## Standing rules (account owner)` and the block
+# carries a do-not-infer line between the header and the bullets. Both fixtures
+# hold the exact emitted copy, so a header change that misses the strip below
+# fails here instead of silently un-flagging every rule-carrying turn again. The
+# emitted copy carries no apostrophe, which is what lets these stay single-quoted.
+CHANNEL_REFRAME_RULES='{"type":"user","isMeta":true,"message":{"role":"user","content":"<channel source=\"whatsapp-channel\">## Standing rules (account owner)\nThese standing rules belong to the account owner. Some of them may name the account owner in the third person. None of them says who sent this turn, so do not infer from them who is speaking.\n- Always greet the client by name\n- Use British spelling\n\n## Context\nplease draft the works order PDF for order 926\n\n## Instruction\nChoose the installed specialist that owns this request and dispatch it with the Agent tool.</channel>"}}'
 # Same rules-prefixed shape, one-word Context payload — after the prefix strip the
 # trivial filter must still read just the payload (`yes`), not the rules block.
-CHANNEL_REFRAME_RULES_TRIVIAL='{"type":"user","isMeta":true,"message":{"role":"user","content":"<channel source=\"whatsapp-channel\">## Standing rules\n- Always greet the client by name\n- Use British spelling\n\n## Context\nyes\n\n## Instruction\nChoose the installed specialist that owns this request and dispatch it with the Agent tool.</channel>"}}'
+CHANNEL_REFRAME_RULES_TRIVIAL='{"type":"user","isMeta":true,"message":{"role":"user","content":"<channel source=\"whatsapp-channel\">## Standing rules (account owner)\nThese standing rules belong to the account owner. Some of them may name the account owner in the third person. None of them says who sent this turn, so do not infer from them who is speaking.\n- Always greet the client by name\n- Use British spelling\n\n## Context\nyes\n\n## Instruction\nChoose the installed specialist that owns this request and dispatch it with the Agent tool.</channel>"}}'
 
 assert_flagged() {
   local name="$1" t="$2" out

package/payload/platform/plugins/admin/hooks/prompt-optimiser-compliance.sh

@@ -149,13 +149,19 @@ while inner.startswith("<channel"):
 # (`## Standing rules\n- …\n\n`) above `## Context`, so a rules-present channel turn
 # no longer begins with `## Context` and both the reframe detection and the trivial
 # strip below silently stopped firing on exactly those turns. Strip an optional
-# leading standing-rules block — anchored to the `## Standing rules` header (not any
+# leading standing-rules block — anchored to the standing-rules header (not any
 # prefix), non-greedy up to the `\n\n` immediately before `## Context` — so both see
 # the `## Context` payload as before rules injection. Channel-only and match-gated on
 # a following `## Context`, so a rules-absent channel turn is byte-identical to before
 # and a typed (non-channel) prompt is untouched.
+# Task 2562 — the header now carries the owner attribution and the block carries a
+# do-not-infer line, both consumed by the same non-greedy body. The suffix is
+# optional: a session spawned before the upgrade keeps composing the bare header
+# until it is recycled, and this hook reads that turn at Stop time. This whole
+# program is inside a single-quoted python3 -c, which is why the emitted copy
+# carries no apostrophe.
 if is_channel:
-    inner = re.sub(r"^## Standing rules\n[\s\S]*?\n\n(?=## Context\n)", "", inner, count=1)
+    inner = re.sub(r"^## Standing rules(?: \(account owner\))?\n[\s\S]*?\n\n(?=## Context\n)", "", inner, count=1)
 
 # Task 805 — a channel-wrapped reframe turn (the ## Context / ## Instruction
 # sections of composeAdminContent) is directive-equivalent: the directive hook suppresses

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Real Agent ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:c2788a2fda2cab3890e93ca987a686c5115d06a836e1ebbc9da7782f3d827d34
+content-hash: sha256:9446dca1e3552e0818938966b34980a00be4d25d938f0d8189ba29bd57861de7
 brand: realagent-code
 product-name: Real Agent
 ---
@@ -6160,7 +6160,7 @@ 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`: the account owner's admin-scope preferences (resolve the seeded `AdminUser {role:'owner'}`, then select through that owner's `UserProfile` via `HAS_PREFERENCE`), a floor-filtered (`confidence >= 0.4`), confidence-ordered query that returns every such preference verbatim — no cap, no de-confliction, no candidate limit. Concision is enforced at write time by the `conversational-memory` skill (each stored value is a single minimal imperative) and by the write-time semantic reconcile (a same-subject write at or above `SAME_SUBJECT_COSINE` folds into the existing node rather than minting a duplicate), so the injected block stays small because each stored preference is short and non-redundant, not because injection truncates. A preference owned by a non-owner profile (an operator's, stranded on the operator's own profile while managing the account) is never injected; an account with no seeded owner injects nothing. `profile-read` exposes this same owner-scoped 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.
+**Inject the active rule-set every turn (channel gateways).** The one definition of "this account's active rules" is `@maxy/active-rules`: the account owner's admin-scope preferences (resolve the seeded `AdminUser {role:'owner'}`, then select through that owner's `UserProfile` via `HAS_PREFERENCE`), a floor-filtered (`confidence >= 0.4`), confidence-ordered query that returns every such preference verbatim — no cap, no de-confliction, no candidate limit. Concision is enforced at write time by the `conversational-memory` skill (each stored value is a single minimal imperative) and by the write-time semantic reconcile (a same-subject write at or above `SAME_SUBJECT_COSINE` folds into the existing node rather than minting a duplicate), so the injected block stays small because each stored preference is short and non-redundant, not because injection truncates. A preference owned by a non-owner profile (an operator's, stranded on the operator's own profile while managing the account) is never injected; an account with no seeded owner injects nothing. `profile-read` exposes this same owner-scoped 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 (account owner)` block above `## Context`, whose header and first line name the owner as the subject of the rules so a third-person rule about the owner is not read as a statement about the sender. 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`. 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). A sender has exactly one session: every inbound, real or scheduled, resolves to the deterministic `adminSessionIdFor(effectiveAccount, destination)`. An earlier change gave each firing its own salted seat so distrust could not accrete across firings, but the inbound hub keys on `senderId` and replaces its subscriber outright, so a seat's channel server attached under the sender's own key and swallowed the sender's REAL messages until it detached — splitting one conversation across two sessions that each denied what the other held. The seat is removed; the authoritative `agentPrompt`, this provenance marker, and the injected standing rules ground each firing without one. Self-cancel attribution is disarmed while that model beds in: the guard used to compare the cancelling turn's session id to a dispatcher stamp, which discriminated only because each firing ran its own seat, so with one session per sender it would report an autonomous loop on every operator cancel. It now always reports false — under-counting a real loop rather than inventing one — until the discriminator is rebuilt from the turn's own dispatched eventId. See `.docs/scheduling-agent-dispatch.md § Operator-provenance marker`, `§ Session model — one session per sender`, and `§ Self-cancel attribution — disarmed`.
 

package/payload/platform/plugins/admin/skills/whats-new/SKILL.md

@@ -9,6 +9,18 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-08-08 (0.1.577)
+
+- Telegram messages keep arriving after a quiet spell. The reader that carries them was attached only when a conversation started, so it died once the conversation went quiet and nothing said so or restarted it. This is the same fault fixed for WhatsApp in the previous release; a standing check now covers Telegram too.
+- Telegram now says who is writing. A message carried no sender, so a second person messaging the same assistant was answered as though they were the account owner, under the owner's own standing instructions.
+- The standing instructions attached to a turn are now labelled as such, rather than appearing as unmarked text.
+- The planner can now change a day, not just show one. It could display an allocated day and offer no way to alter it.
+- A webhook address ending in a slash is no longer rejected. The guard that admits it tested the path differently from the router that serves it, so the two could disagree on the same address.
+
+## 2026-08-08 (0.1.576)
+
+- Installing and upgrading no longer runs data conversions on your existing records. Five had accumulated, each added to repair a state that every install has long since passed, so all five did nothing but add work and risk to every upgrade. One of them stopped the install outright after reporting it had nothing to do. Any future conversion will be something you run deliberately, not part of an upgrade.
+
 ## 2026-08-08 (0.1.575)
 
 - **Reverses one change from 0.1.574.** An answer now stays on the channel you asked from, rather than also being copied to your other channels. The copy arrived as a reply with no question above it, because only the answer travelled and not what you had asked; a WhatsApp question turned up in Telegram as a bare statement. Being reachable on more than one device is already handled per channel, so the copy was removed rather than completed.