@foldspace_npm/harness 0.1.17 → 0.1.18

package/recipes/opportunities-at-risk/agent/views/brand.ts

@@ -0,0 +1,20 @@
+// Palette sampled from the production build this recipe came from (a dark CRM).
+// Re-sample these from the host page when that product's brand differs, and
+// record where each value came from in docs/app-profile.md.
+
+export const brand = {
+  surface: "#0E1729",
+  headerStart: "#1a2332",
+  border: "#344256",
+  text: "#E0E0E0",
+  textStrong: "#FFFFFF",
+  muted: "#94A3B8",
+  faint: "#6B7280",
+  accent: "#60A5FA",
+  money: "#34D399",
+  warn: "#FBBF24",
+  warnInk: "#78350F",
+  row: "rgba(255, 255, 255, 0.03)",
+  font: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+  radius: "8px",
+} as const;

package/recipes/opportunities-at-risk/fixtures/at-risk.empty.json

@@ -0,0 +1,4 @@
+{
+  "summary": { "dealCount": 0, "totalValue": 0, "avgDaysStalled": 0 },
+  "deals": []
+}

package/recipes/opportunities-at-risk/fixtures/at-risk.ok.json

@@ -0,0 +1,25 @@
+{
+  "summary": { "dealCount": 2, "totalValue": 30000, "avgDaysStalled": 15 },
+  "deals": [
+    {
+      "id": "opp_1",
+      "name": "Renewal",
+      "account": { "id": "acct_1", "name": "Northwind" },
+      "value": 18000,
+      "stage": "negotiation",
+      "closeDate": "2026-09-01T00:00:00.000Z",
+      "daysSinceUpdate": 21,
+      "risks": ["Stalled 21 days", "20 days past close date", "Low probability in late stage"]
+    },
+    {
+      "id": "opp_2",
+      "name": "Expansion",
+      "account": { "id": "acct_2", "name": "Contoso" },
+      "value": "12000",
+      "stage": "proposal",
+      "closeDate": null,
+      "daysSinceUpdate": 9,
+      "risks": ["1 critical case"]
+    }
+  ]
+}

package/recipes/opportunities-at-risk/fixtures/at-risk.unsigned.json

@@ -0,0 +1,3 @@
+{
+  "redirect": "/login"
+}

package/recipes/opportunities-at-risk/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Opportunities at risk",
+  "level": "L2",
+  "family": "show-a-list",
+  "kind": "action",
+  "action": "show_opportunities_at_risk",
+  "entry": "agent/actions/show_opportunities_at_risk.ts",
+  "outcome": "Every open opportunity the app flags as at risk, on one card: count, total value, and why each one is at risk",
+  "provenBy": 1
+}

package/recipes/prepare-for-a-meeting/README.md

@@ -0,0 +1,27 @@
+# Prepare for a meeting — L2
+
+**The user says** "prepare me for this meeting". **The agent gets** a summary, plus the facts the summary was written from. There is no card.
+
+**Proven by 1 production build.**
+
+One request loads the meeting, the account, the opportunities, the open cases, and past notes. Counts and the pipeline total are computed in code. Those facts are passed to `runTask` as `data`. There is no `prompt`: the task agent's instructions are created in Agent Studio. The key in this recipe, `__observe_me_summary`, is a placeholder — replace it with the key you publish. ⚠️ Check `list_task_agents` first; if the MCP has no tool to create one, the task agent is created by hand in Agent Studio and this recipe waits for it.
+
+If `runTask` is missing or throws, `summary` is null and the message says a summary was not produced. The gathered facts still come back.
+
+A meeting with no account id and no account name is `signed_out`, not a pipeline of zero.
+
+In Agent Studio: an action with key `prepare_for_meeting` and one string parameter `meetingId`. Also a task agent whose key matches `TASK_KEY`.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/meetings.ts` | Mock path and envelope. Find a real API that returns a similar shape |
+| `agent/meetings.ts` | Which facts the summary needs. Totals stay computed here |
+| `agent/actions/prepare_for_meeting.ts` | `TASK_KEY`, after the task agent exists in Agent Studio |
+
+## What that build learned the hard way
+
+- **The task agent receives facts, not instructions.** `prompt` in `data` is a second instruction channel. The wording belongs on the task agent.
+- **Keep the facts when the summary fails.** A task-agent outage is not a lost meeting.
+- **Add the pipeline in code** before it is handed to the task agent, so the summary is not asked to do the arithmetic.

package/recipes/prepare-for-a-meeting/agent/actions/prepare_for_meeting.ts

@@ -0,0 +1,70 @@
+// Gather the meeting, then ask the task agent to summarise it. `data` is facts
+// only. The task agent's instructions live in Agent Studio, under the key below.
+// If the task agent does not answer, the facts still come back and summary is null.
+
+import { getMeetingPrep } from "../api/meetings";
+import { belongsToSignedInUser, toPrep, type MeetingPrep } from "../meetings";
+import { getAgent } from "../utils";
+
+/** Replace with the task-agent key created in Agent Studio. */
+const TASK_KEY = "__observe_me_summary";
+
+type PrepResult = {
+  success: boolean;
+  summary?: string | null;
+  message?: string;
+  error?: string;
+  reason?: string;
+  data?: MeetingPrep;
+};
+
+function readSummary(taskResult: unknown): string | null {
+  if (typeof taskResult === "string") return taskResult.trim() || null;
+  if (!taskResult || typeof taskResult !== "object") return null;
+  const record = taskResult as { summary?: unknown; result?: unknown };
+  if (typeof record.summary === "string" && record.summary.trim()) return record.summary.trim();
+  const inner = record.result;
+  if (typeof inner === "string") return inner.trim() || null;
+  if (inner && typeof inner === "object" && typeof (inner as { summary?: unknown }).summary === "string") {
+    return (inner as { summary: string }).summary.trim() || null;
+  }
+  return null;
+}
+
+export const prepare_for_meeting = {
+  execute: async (params: { meetingId?: string }): Promise<PrepResult> => {
+    const meetingId = typeof params?.meetingId === "string" ? params.meetingId.trim() : "";
+    if (!meetingId) {
+      return { success: false, error: "meetingId was not provided.", reason: "config" };
+    }
+
+    const res = await getMeetingPrep(meetingId);
+    if (!res.ok) {
+      console.warn("[prepare_for_meeting]", res.status, res.reason, res.detail);
+      return { success: false, error: res.error, reason: res.reason };
+    }
+    if (!belongsToSignedInUser(res.data)) {
+      return { success: false, error: "Not signed in.", reason: "signed_out" };
+    }
+
+    const facts = toPrep(res.data);
+    const agent = getAgent();
+    if (!agent || typeof agent.runTask !== "function") {
+      return { success: true, summary: null, message: "A summary was not produced.", data: facts };
+    }
+
+    try {
+      const taskResult = await agent.runTask({ taskKey: TASK_KEY, data: facts });
+      const summary = readSummary(taskResult);
+      return {
+        success: true,
+        summary,
+        message: summary ? "A meeting summary was produced." : "A summary was not produced.",
+        data: facts,
+      };
+    } catch (error) {
+      console.warn("[prepare_for_meeting]", error);
+      return { success: true, summary: null, message: "A summary was not produced.", data: facts };
+    }
+  },
+};

package/recipes/prepare-for-a-meeting/agent/api/meetings.ts

@@ -0,0 +1,24 @@
+// Mock API. This path is not a real product. Find an API that returns a similar
+// shape — the meeting, its account, opportunities, open cases, and past notes —
+// and replace the path and the envelope with what you observed. `__observe_me`
+// cannot succeed until you do.
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type PrepPayload = {
+  meeting?: {
+    id?: string | null;
+    title?: string | null;
+    startTime?: string | null;
+    attendees?: string[] | null;
+    notes?: { content?: string | null }[] | null;
+  } | null;
+  account?: { id?: string | null; name?: string | null; industry?: string | null } | null;
+  opportunities?: { name?: string | null; value?: number | null; stage?: string | null }[] | null;
+  openCases?: { title?: string | null; priority?: string | null }[] | null;
+  pastMeetings?: { title?: string | null; notes?: string | null }[] | null;
+};
+
+export async function getMeetingPrep(meetingId: string): Promise<ApiResult<PrepPayload>> {
+  return apiFetch<PrepPayload>(`/__observe_me/meetings/${encodeURIComponent(meetingId)}/prep`);
+}

package/recipes/prepare-for-a-meeting/agent/meetings.ts

@@ -0,0 +1,66 @@
+// Counts and the pipeline total are computed here. The task agent receives facts, not a prompt.
+
+import type { PrepPayload } from "./api/meetings";
+
+export type MeetingPrep = {
+  meeting: {
+    id: string;
+    title: string;
+    startTime: string | null;
+    attendees: string[];
+    notes: string[];
+  };
+  account: { id: string; name: string; industry: string | null };
+  metrics: { openOpportunities: number; pipelineValue: number; openCases: number };
+  opportunities: { name: string; value: number; stage: string | null }[];
+  openCases: { title: string; priority: string | null }[];
+  pastMeetings: { title: string; notes: string | null }[];
+};
+
+export function belongsToSignedInUser(payload: PrepPayload): boolean {
+  const id = payload.account?.id;
+  const name = payload.account?.name;
+  return typeof id === "string" && id.trim() !== "" && typeof name === "string" && name.trim() !== "";
+}
+
+export function toPrep(payload: PrepPayload): MeetingPrep {
+  const meeting = payload.meeting ?? {};
+  const account = payload.account ?? {};
+  const opportunities = (payload.opportunities ?? []).map((row) => ({
+    name: row.name?.trim() || "Untitled",
+    value: typeof row.value === "number" && Number.isFinite(row.value) ? row.value : 0,
+    stage: row.stage?.trim() || null,
+  }));
+  const openCases = (payload.openCases ?? []).map((row) => ({
+    title: row.title?.trim() || "Untitled",
+    priority: row.priority?.trim() || null,
+  }));
+
+  return {
+    meeting: {
+      id: meeting.id?.trim() || "",
+      title: meeting.title?.trim() || "Untitled",
+      startTime: meeting.startTime?.trim() || null,
+      attendees: (meeting.attendees ?? []).filter((name): name is string => typeof name === "string" && name.trim() !== ""),
+      notes: (meeting.notes ?? [])
+        .map((note) => note.content?.trim() || "")
+        .filter((content) => content !== ""),
+    },
+    account: {
+      id: String(account.id),
+      name: String(account.name).trim(),
+      industry: account.industry?.trim() || null,
+    },
+    metrics: {
+      openOpportunities: opportunities.length,
+      pipelineValue: opportunities.reduce((sum, row) => sum + row.value, 0),
+      openCases: openCases.length,
+    },
+    opportunities,
+    openCases,
+    pastMeetings: (payload.pastMeetings ?? []).map((row) => ({
+      title: row.title?.trim() || "Untitled",
+      notes: row.notes?.trim() || null,
+    })),
+  };
+}

package/recipes/prepare-for-a-meeting/fixtures/prep.ok.json

@@ -0,0 +1,24 @@
+{
+  "meeting": {
+    "id": "mtg_1",
+    "title": "Quarterly review",
+    "startTime": "2026-09-22T15:00:00Z",
+    "attendees": ["Dana Reyes"],
+    "notes": [{ "content": "Send the renewal numbers." }]
+  },
+  "account": {
+    "id": "acct_1",
+    "name": "Northwind",
+    "industry": "Logistics"
+  },
+  "opportunities": [
+    { "id": "opp_1", "name": "Renewal", "value": 12000, "stage": "proposal" },
+    { "id": "opp_2", "name": "Expansion", "value": 6000, "stage": "qualified" }
+  ],
+  "openCases": [
+    { "id": "case_1", "title": "Billing question", "priority": "high" }
+  ],
+  "pastMeetings": [
+    { "id": "mtg_0", "title": "Intro", "notes": "They asked about onboarding." }
+  ]
+}

package/recipes/prepare-for-a-meeting/fixtures/prep.unsigned.json

@@ -0,0 +1,9 @@
+{
+  "meeting": { "id": "mtg_1", "title": "Quarterly review" },
+  "account": { "id": null, "name": null },
+  "opportunities": [
+    { "id": "opp_1", "name": "Renewal", "value": 18000, "stage": "proposal" }
+  ],
+  "openCases": [],
+  "pastMeetings": []
+}

package/recipes/prepare-for-a-meeting/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Prepare for a meeting",
+  "level": "L2",
+  "family": "task-agent",
+  "kind": "action",
+  "action": "prepare_for_meeting",
+  "entry": "agent/actions/prepare_for_meeting.ts",
+  "outcome": "Meeting facts are gathered, then a task agent writes the summary",
+  "provenBy": 1
+}

package/recipes/update-meeting-notes/README.md

@@ -0,0 +1,22 @@
+# Update meeting notes — L4
+
+**The user says** "add this to the meeting notes". **The agent gets** the new note id. There is no card.
+
+**Proven by 1 production build.**
+
+A missing `meetingId` or empty notes fails and names the field that was absent. A missing meeting comes back as `not_found`. The saved result is the note id and the meeting id.
+
+In Agent Studio: an action with key `update_meeting_notes` and string parameters `meetingId`, `notes`, and optional `author`.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/meetings.ts` | Mock path and body. Find a real API that saves a note and returns its id |
+| `agent/actions/update_meeting_notes.ts` | The field names, if the product calls them something else |
+
+## What that build learned the hard way
+
+- **Return the id the server created.** "Saved" without an id is not something the next action can use.
+- **Name the missing field.** An empty notes string and a missing meeting are different failures.
+- **This is a live write.** Ask before publishing an edit to an action that already has users.

package/recipes/update-meeting-notes/agent/actions/update_meeting_notes.ts

@@ -0,0 +1,36 @@
+// A write, with no card. The result is what was saved: the note id and the
+// meeting id. A missing field is named. A missing meeting is not_found.
+
+import { saveMeetingNote } from "../api/meetings";
+
+export const update_meeting_notes = {
+  execute: async (params: { meetingId?: string; notes?: string; author?: string }) => {
+    const meetingId = typeof params?.meetingId === "string" ? params.meetingId.trim() : "";
+    const notes = typeof params?.notes === "string" ? params.notes.trim() : "";
+    const author = typeof params?.author === "string" ? params.author.trim() : "";
+
+    if (!meetingId) {
+      return { success: false, error: "meetingId was not provided.", reason: "config" };
+    }
+    if (!notes) {
+      return { success: false, error: "notes were not provided.", reason: "config" };
+    }
+
+    const res = await saveMeetingNote(meetingId, notes, author || undefined);
+    if (!res.ok) {
+      console.warn("[update_meeting_notes]", res.status, res.reason, res.detail);
+      return { success: false, error: res.error, reason: res.reason };
+    }
+
+    const noteId = res.data.note?.id?.trim() || "";
+    if (!noteId) {
+      return { success: false, error: "The note was not saved.", reason: "server" };
+    }
+
+    return {
+      success: true,
+      message: "A note was saved.",
+      data: { noteId, meetingId },
+    };
+  },
+};

package/recipes/update-meeting-notes/agent/api/meetings.ts

@@ -0,0 +1,22 @@
+// Mock API. This path is not a real product. Find an API that saves a note on a
+// meeting and returns the new note id, then replace the path and the envelope
+// with what you observed. `__observe_me` cannot succeed until you do.
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type NotePayload = {
+  note?: { id?: string | null } | null;
+};
+
+export async function saveMeetingNote(
+  meetingId: string,
+  content: string,
+  author?: string,
+): Promise<ApiResult<NotePayload>> {
+  const body: { content: string; author?: string } = { content };
+  if (author) body.author = author;
+  return apiFetch<NotePayload>(`/__observe_me/meetings/${encodeURIComponent(meetingId)}/notes`, {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+}

package/recipes/update-meeting-notes/fixtures/note.ok.json

@@ -0,0 +1,3 @@
+{
+  "note": { "id": "note_9" }
+}

package/recipes/update-meeting-notes/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Update meeting notes",
+  "level": "L4",
+  "family": "write",
+  "kind": "action",
+  "action": "update_meeting_notes",
+  "entry": "agent/actions/update_meeting_notes.ts",
+  "outcome": "A note is saved on a meeting and the new note id comes back",
+  "provenBy": 1
+}

package/recipes/upload-contacts/README.md

@@ -0,0 +1,25 @@
+# Upload contacts — L4
+
+**The user says** "upload these contacts". **The user sees** the import card: a drop zone, a review table, then the result. Nothing is written until they choose Import. Done finishes the card.
+
+**Proven by 1 production build.**
+
+`awaitUserInput` is set, so the agent is paused until `callback` runs. Cancel, an empty file, a failed import, and a finished import each call `callback`. The callback states what happened: created, skipped, and a reason on each skipped row.
+
+In Agent Studio: an action with key `upload_contacts` and no parameters. The file comes from the card, not from the model.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/contacts.ts` | Mock import path. Find a real API that accepts a list of contacts and returns created and skipped rows |
+| `agent/contacts.ts` | The columns the file actually has |
+| `agent/views/uploader.ts` | The card. `brand.ts` is the live import card; re-sample it when the host brand differs |
+
+## What that build learned the hard way
+
+- **Preview before the write.** Choosing a file is not a request to create records. The write runs when they choose Import.
+- **Invalid rows stay out of the request.** They are reported as skipped, with the reason, and the valid rows are what get posted.
+- **Every path calls `callback`.** Cancel and an empty file included. Leaving the card up without calling it holds the conversation.
+- **A failed import is not "Created 0".** Draw the failure and return its `reason`.
+- **"View Contacts" only works where the app listens.** The build's single-page app routed on a message the card posts; other apps do not. ⚠️ Keep the button only if you wire that message, or open the list with a navigation route.

package/recipes/upload-contacts/agent/actions/upload_contacts.ts

@@ -0,0 +1,77 @@
+// The agent waits while the user picks a file, reviews the rows, and imports.
+// Calling callback is mandatory on every finished path. The write happens only
+// after Import. Done is what finishes the card.
+
+import type { ImportOutcome } from "../contacts";
+import { renderFailure, type ApiFailure, type FailureReason } from "../utils";
+import { mountContactUpload } from "../views/uploader";
+
+type UploadResult = {
+  success: boolean;
+  message?: string;
+  error?: string;
+  reason?: FailureReason;
+  data?: { cancelled?: boolean; created?: number; skipped?: number; rows?: ImportOutcome["rows"] };
+};
+
+function done(outcome: ImportOutcome): UploadResult {
+  return {
+    success: true,
+    message: `Created ${outcome.created}. Skipped ${outcome.skipped}.`,
+    data: { cancelled: false, created: outcome.created, skipped: outcome.skipped, rows: outcome.rows },
+  };
+}
+
+export const upload_contacts = {
+  execute: async (): Promise<UploadResult> => {
+    return { success: true, message: "A contact upload is on screen.", data: { cancelled: false } };
+  },
+
+  awaitUserInput: true,
+
+  render: (
+    result: UploadResult | undefined,
+    host: HTMLElement,
+    header: HTMLElement,
+    callback: (value: unknown, disableOnSubmit?: boolean) => void,
+  ) => {
+    if (!result?.success) {
+      renderFailure(host, {
+        ok: false,
+        status: 0,
+        error: result?.error ?? "The upload could not be opened.",
+        reason: result?.reason ?? "server",
+      });
+      callback(result, true);
+      return;
+    }
+
+    mountContactUpload(host, header, {
+      onCancel: () => {
+        callback(
+          { success: true, message: "The user closed the upload.", data: { cancelled: true } },
+          true,
+        );
+      },
+      onEmpty: () => {
+        callback(
+          {
+            success: true,
+            message: "The file had no contacts.",
+            data: { cancelled: false, created: 0, skipped: 0, rows: [] },
+          },
+          true,
+        );
+      },
+      onDone: (outcome) => {
+        callback(done(outcome), true);
+      },
+      onFailed: (failure: ApiFailure) => {
+        callback(
+          { success: false, error: failure.error, reason: failure.reason, data: { cancelled: false } },
+          true,
+        );
+      },
+    });
+  },
+};

package/recipes/upload-contacts/agent/api/contacts.ts

@@ -0,0 +1,29 @@
+// Mock API. This path is not a real product. Find an API that accepts a list of
+// contacts and returns how many were created and which rows were skipped, then
+// replace the path and the envelope with what you observed. `__observe_me`
+// cannot succeed until you do.
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type ContactDraft = {
+  firstName: string;
+  lastName: string;
+  email: string;
+  phone: string | null;
+  title: string | null;
+  accountName: string | null;
+};
+
+export type ImportPayload = {
+  created?: number;
+  skipped?: number;
+  createdContacts?: { name?: string | null; email?: string | null }[] | null;
+  skippedContacts?: { name?: string | null; email?: string | null; reason?: string | null }[] | null;
+};
+
+export async function importContacts(contacts: ContactDraft[]): Promise<ApiResult<ImportPayload>> {
+  return apiFetch<ImportPayload>("/__observe_me/contacts/import", {
+    method: "POST",
+    body: JSON.stringify({ contacts }),
+  });
+}