@foldspace_npm/harness 0.1.16 → 0.1.18

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 }),
+  });
+}

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

@@ -0,0 +1,133 @@
+import type { ContactDraft, ImportPayload } from "./api/contacts";
+
+export type ParsedContact = ContactDraft & {
+  valid: boolean;
+  reason: string | null;
+};
+
+export type ContactRow = {
+  name: string;
+  email: string;
+  reason: string | null;
+};
+
+export type ImportOutcome = {
+  created: number;
+  skipped: number;
+  rows: ContactRow[];
+};
+
+type Column = "firstName" | "lastName" | "email" | "phone" | "title" | "accountName";
+
+function splitCsvLine(line: string): string[] {
+  const values: string[] = [];
+  let current = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === '"') {
+      inQuotes = !inQuotes;
+    } else if (char === "," && !inQuotes) {
+      values.push(current.trim());
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  values.push(current.trim());
+  return values;
+}
+
+function columnOf(header: string): Column | null {
+  const normalized = header.replace(/['"]/g, "").trim().toLowerCase();
+  if (normalized.includes("first") && normalized.includes("name")) return "firstName";
+  if (normalized === "firstname" || normalized === "first_name") return "firstName";
+  if (normalized.includes("last") && normalized.includes("name")) return "lastName";
+  if (normalized === "lastname" || normalized === "last_name") return "lastName";
+  if (normalized.includes("email")) return "email";
+  if (normalized.includes("phone") || normalized.includes("mobile")) return "phone";
+  if (normalized.includes("title")) return "title";
+  if (normalized.includes("account") || normalized.includes("company")) return "accountName";
+  return null;
+}
+
+export function parseContactsCsv(csv: string): ParsedContact[] {
+  const lines = csv.trim().split(/\r?\n/).filter((line) => line.trim() !== "");
+  if (lines.length < 2) return [];
+
+  const columns = splitCsvLine(lines[0]).map(columnOf);
+  const contacts: ParsedContact[] = [];
+
+  for (const line of lines.slice(1)) {
+    const values = splitCsvLine(line);
+    const read = (column: Column) => {
+      const index = columns.indexOf(column);
+      return index >= 0 ? (values[index] ?? "").trim() : "";
+    };
+    const contact: ParsedContact = {
+      firstName: read("firstName"),
+      lastName: read("lastName"),
+      email: read("email"),
+      phone: read("phone") || null,
+      title: read("title") || null,
+      accountName: read("accountName") || null,
+      valid: true,
+      reason: null,
+    };
+    if (!contact.firstName || !contact.lastName) {
+      contact.valid = false;
+      contact.reason = "Missing name";
+    } else if (!contact.email) {
+      contact.valid = false;
+      contact.reason = "Missing email";
+    } else if (!contact.email.includes("@")) {
+      contact.valid = false;
+      contact.reason = "Invalid email";
+    }
+    contacts.push(contact);
+  }
+
+  return contacts;
+}
+
+export function contactName(contact: { firstName?: string; lastName?: string; name?: string | null }): string {
+  if (contact.name?.trim()) return contact.name.trim();
+  return `${contact.firstName ?? ""} ${contact.lastName ?? ""}`.trim();
+}
+
+export function outcomeFrom(parsed: ParsedContact[], server: ImportPayload): ImportOutcome {
+  const heldBack = parsed.filter((row) => !row.valid);
+  const serverSkipped = server.skippedContacts ?? [];
+  const rows: ContactRow[] = [
+    ...(server.createdContacts ?? []).map((row) => ({
+      name: row.name?.trim() || "Untitled",
+      email: row.email?.trim() || "",
+      reason: null,
+    })),
+    ...heldBack.map((row) => ({
+      name: contactName(row) || "Untitled",
+      email: row.email,
+      reason: row.reason,
+    })),
+    ...serverSkipped.map((row) => ({
+      name: row.name?.trim() || "Untitled",
+      email: row.email?.trim() || "",
+      reason: row.reason?.trim() || null,
+    })),
+  ];
+  const created = typeof server.created === "number" ? server.created : (server.createdContacts ?? []).length;
+  const skipped =
+    heldBack.length + (typeof server.skipped === "number" ? server.skipped : serverSkipped.length);
+  return { created, skipped, rows };
+}
+
+export function toDraft(contact: ParsedContact): ContactDraft {
+  return {
+    firstName: contact.firstName,
+    lastName: contact.lastName,
+    email: contact.email,
+    phone: contact.phone,
+    title: contact.title,
+    accountName: contact.accountName,
+  };
+}

package/recipes/upload-contacts/agent/views/brand.ts

@@ -0,0 +1,21 @@
+// 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.
+// Record where each value came from in docs/app-profile.md.
+
+export const brand = {
+  surface: "#0E1729",
+  border: "#344256",
+  text: "#E0E0E0",
+  textStrong: "#FFFFFF",
+  muted: "#94A3B8",
+  faint: "#64748B",
+  accent: "#60A5FA",
+  accentDeep: "#3B82F6",
+  ok: "#34D399",
+  warn: "#FBBF24",
+  bad: "#F87171",
+  tableHead: "#1E293B",
+  disabled: "#475569",
+  font: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+  radius: "8px",
+} as const;