@foldspace_npm/harness 0.1.11 → 0.1.13

package/recipes/find-by-name/README.md

@@ -0,0 +1,47 @@
+# Find by name — L2
+
+**The user says** "add it to the Maple Street project". **The agent needs** an id.
+
+**Proven by 3 production builds**, all the same shape: a name from the user's
+words → the app's own list → a ranked answer **back to the agent as data**. None
+of them draws a card. A resolver answers questions; it never asks one. When the
+user genuinely has to choose, that is a different action —
+[`pick-from-a-list`](../pick-from-a-list/).
+
+In Agent Studio: an action with key `find_project_id` and one optional string
+parameter `name` — *the name, or part of the name, the user said*.
+
+## What it returns
+
+| The user's words | The agent gets |
+|---|---|
+| no name ("how many projects do I have?") | the account's **count**, plus a small sample — never the whole account |
+| one clear match | that project, its match strength, and up to three alternatives |
+| several equally good matches | **all of them**, marked `ambiguous` — never a silent pick |
+| nothing matches | `success: false`, plus near-misses for a typo |
+| the account is empty | a count of zero — not an error |
+| signed out, no access, throttled, unreachable | `success: false` with the `reason` |
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/projects.ts` | Path, parameter names, envelope — from a captured response |
+| `agent/projects.ts` | What a summary carries, and which keys a user might name out loud |
+| `agent/actions/find_project_id.ts` | The entity. The logic rarely needs touching |
+
+## What those builds learned the hard way
+
+- **Hand back every tie.** Picking one of two equally good matches is how a
+  later action changes the wrong project.
+- **Count on the server.** Fetching every row to count them is the slowest thing
+  an agent can do, and it puts the whole account into the model's context.
+- **Return summaries, not rows.** Two of the three builds send ten raw fields
+  per row to the agent; the third sends three and is the one that scales.
+- **A missing session is not "no projects".** One build reports a missing token
+  as an empty list, and the agent cheerfully tells a signed-out user they have
+  none.
+- **Server search is usually a plain substring**, so a typo finds nothing. Try
+  the near-miss pass before saying no.
+- **Probe with a name a real record has.** A search that returns zero proves
+  nothing unless a matching record exists.

package/recipes/find-by-name/agent/actions/find_project_id.ts

@@ -0,0 +1,101 @@
+// Resolver: a name the user said → the id every other project action needs.
+//
+// It answers questions and never asks one. "How many projects do I have?" gets
+// a count, not a widget demanding a selection — asking is choose_project.
+
+import { listProjects } from "../api/projects";
+import { classify, MATCH_RANK, nearMatches, toSummary, type MatchType, type ProjectSummary } from "../projects";
+
+/** Enough for the agent to name a few projects without shipping the account. */
+const SAMPLE_SIZE = 25;
+
+/** Names are matched on the server, so a shortlist is all this has to rank. */
+const SHORTLIST = 50;
+
+const plural = (n: number) => (n === 1 ? "" : "s");
+
+export const find_project_id = {
+  execute: async (params: { name?: string }) => {
+    const query = typeof params?.name === "string" ? params.name.trim() : "";
+
+    // No name: a count question. Only a sample of rows comes back.
+    if (!query) {
+      const res = await listProjects({ pageSize: SAMPLE_SIZE });
+      if (!res.ok) return { success: false, error: res.error, reason: res.reason };
+
+      const { projects, total } = res.data;
+      if (total === 0) {
+        return { success: true, message: "This account has no projects yet.", data: { total: 0, projects: [] } };
+      }
+      const sample = projects.map(toSummary);
+      return {
+        success: true,
+        message:
+          `This account has ${total} project${plural(total)}.` +
+          (sample.length < total ? ` The first ${sample.length} are listed.` : ""),
+        data: { total, showing: sample.length, projects: sample },
+      };
+    }
+
+    // A name: let the server match it, then rank what comes back.
+    const res = await listProjects({ search: query, pageSize: SHORTLIST });
+    if (!res.ok) {
+      console.warn("[find_project_id]", res.status, res.reason, res.detail);
+      return { success: false, error: res.error, reason: res.reason };
+    }
+
+    const summaries = res.data.projects.map(toSummary);
+
+    if (summaries.length === 0) {
+      // Server search is a substring of the name, so a typo finds nothing.
+      // Near-misses give the agent something true to work with — but they are
+      // near-misses, not a resolution.
+      const wide = await listProjects({ pageSize: SHORTLIST });
+      const near = wide.ok ? nearMatches(wide.data.projects.map(toSummary), query, 5) : [];
+      return {
+        success: false,
+        error: `No project matching "${query}".`,
+        reason: "not_found" as const,
+        data: { query, total: res.data.total, nearMatches: near },
+      };
+    }
+
+    const ranked = summaries
+      .map((project) => ({ project, match: classify(project.name, query) }))
+      .filter((m): m is { project: ProjectSummary; match: MatchType } => m.match !== null)
+      .sort((a, b) => MATCH_RANK[a.match] - MATCH_RANK[b.match]);
+
+    // The server matched something the classifier does not recognise. Anything
+    // it cannot rank is still a real hit.
+    const best = ranked[0];
+    if (!best) {
+      return {
+        success: true,
+        message: `${summaries.length} project${plural(summaries.length)} match "${query}".`,
+        data: { query, ambiguous: summaries.length > 1, matches: summaries },
+      };
+    }
+
+    // Same-strength runners-up mean the name really was ambiguous. Hand them
+    // all back rather than silently picking one and changing the wrong project.
+    const ties = ranked.filter((m) => m.match === best.match);
+    if (ties.length > 1) {
+      return {
+        success: true,
+        message: `${ties.length} projects match "${query}".`,
+        data: { query, ambiguous: true, matches: ties.map((m) => m.project) },
+      };
+    }
+
+    return {
+      success: true,
+      message: `Matched project "${best.project.name}".`,
+      data: {
+        ambiguous: false,
+        matchType: best.match,
+        ...best.project,
+        alternatives: ranked.slice(1, 4).map((m) => m.project),
+      },
+    };
+  },
+};

package/recipes/find-by-name/agent/api/projects.ts

@@ -0,0 +1,36 @@
+// The app's own project list. Replace the path, the parameter names and the
+// envelope with what you OBSERVED — type only the keys you read.
+//
+// Prefer an endpoint that searches and counts on the server. One production
+// build started on an endpoint that returned the whole account in one response;
+// counting a thousand rows to answer "how many projects do I have?" is how a
+// lookup becomes the slowest thing the agent does.
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type Project = {
+  id: string;
+  name: string;
+  status?: string | null;
+  updatedAt?: string | null;
+};
+
+export type ProjectPage = {
+  projects: Project[];
+  /** Every project in the account, not just this page. */
+  total: number;
+};
+
+export async function listProjects(
+  options: { search?: string; pageSize?: number } = {},
+): Promise<ApiResult<ProjectPage>> {
+  const query = new URLSearchParams();
+  if (options.search) query.set("search", options.search);
+  query.set("pageSize", String(options.pageSize && options.pageSize > 0 ? options.pageSize : 25));
+
+  const res = await apiFetch<{ items?: Project[]; total?: number }>(`/__observe_me/projects?${query}`);
+  if (!res.ok) return res;
+
+  const rows = Array.isArray(res.data?.items) ? res.data.items : [];
+  return { ok: true, status: res.status, data: { projects: rows, total: res.data?.total ?? rows.length } };
+}

package/recipes/find-by-name/agent/projects.ts

@@ -0,0 +1,40 @@
+// Name matching shared by the action that RESOLVES a project and the one that
+// asks the user to PICK one. They must agree: a name the lookup calls ambiguous
+// has to produce the same shortlist when the user is shown it.
+
+import type { Project } from "./api/projects";
+import { rankBy } from "./utils";
+
+/** Only what the agent needs to talk about a project. Never the whole row. */
+export type ProjectSummary = {
+  projectId: string;
+  name: string;
+  status: string | null;
+};
+
+export function toSummary(project: Project): ProjectSummary {
+  return { projectId: project.id, name: project.name, status: project.status ?? null };
+}
+
+export type MatchType = "exact" | "starts_with" | "contains";
+
+export const MATCH_RANK: Record<MatchType, number> = { exact: 0, starts_with: 1, contains: 2 };
+
+export function classify(name: string, query: string): MatchType | null {
+  const a = name.trim().toLowerCase();
+  const b = query.trim().toLowerCase();
+  if (!b) return null;
+  if (a === b) return "exact";
+  if (a.startsWith(b)) return "starts_with";
+  if (a.includes(b)) return "contains";
+  return null;
+}
+
+/**
+ * Loose phrasing — a typo, a half-remembered word. Substring hits lead, the
+ * SDK's fuzzy match fills in behind; if the agent is not ready the substring
+ * pass stands alone. That is `rankBy`, which was lifted from this pattern.
+ */
+export function nearMatches(projects: ProjectSummary[], query: string, limit: number): ProjectSummary[] {
+  return rankBy(projects, query, { searchKeys: ["name", "status"], idOf: (p) => p.projectId, limit });
+}

package/recipes/find-by-name/fixtures/projects.all.json

@@ -0,0 +1,29 @@
+{
+  "items": [
+    {
+      "id": "p_101",
+      "name": "Maple Street",
+      "status": "Active",
+      "updatedAt": "2026-08-30T14:05:00Z"
+    },
+    {
+      "id": "p_102",
+      "name": "Harbor Street Office",
+      "status": "Draft",
+      "updatedAt": "2026-07-12T09:00:00Z"
+    },
+    {
+      "id": "p_103",
+      "name": "Maple Street Annex",
+      "status": "Closed",
+      "updatedAt": "2026-03-02T17:40:00Z"
+    },
+    {
+      "id": "p_104",
+      "name": "Harbor View",
+      "status": "Active",
+      "updatedAt": "2026-02-11T10:00:00Z"
+    }
+  ],
+  "total": 4
+}

package/recipes/find-by-name/fixtures/projects.empty-account.json

@@ -0,0 +1,4 @@
+{
+  "items": [],
+  "total": 0
+}

package/recipes/find-by-name/fixtures/projects.none.json

@@ -0,0 +1,4 @@
+{
+  "items": [],
+  "total": 4
+}

package/recipes/find-by-name/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Find by name",
+  "level": "L2",
+  "family": "find-and-show",
+  "kind": "action",
+  "action": "find_project_id",
+  "entry": "agent/actions/find_project_id.ts",
+  "outcome": "A name the user said becomes the id the next action needs",
+  "provenBy": 3
+}

package/recipes/pick-from-a-list/README.md

@@ -0,0 +1,44 @@
+# Pick from a list — L2
+
+**The agent needs** the user to choose a project. **The user sees** a clickable
+list, picks one, and the choice goes back to the agent.
+
+**Proven by 1 production build**, which split this from
+[`find-by-name`](../find-by-name/) on purpose: *asking is a decision the agent
+makes, not a side effect of looking something up.* A lookup that draws a widget
+puts a selection in front of someone who only asked a question.
+
+In Agent Studio: an action with key `choose_project`, optional string parameters
+`name` (narrow the list to what the user said) and `purpose` (shown above the
+list: "Which project for *the export*?").
+
+## What it does
+
+| Situation | What happens |
+|---|---|
+| Projects to choose from | the card; the agent **waits** (`awaitUserInput: true`) |
+| The name matched nothing | falls back to the whole list — an empty picker cannot be answered |
+| The account has no projects | **no card**; the result goes straight back |
+| The list could not be loaded | **no card**, `success: false` — never "no projects" for someone who has hundreds |
+| The user picks one | `chosenByUser: true` and the project |
+| "None of these" | what was offered, so the agent can ask what they meant |
+| Cancel | `cancelled: true` — and the card says so, so it is not left looking live |
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/projects.ts`, `agent/projects.ts` | Same as `find-by-name` — keep the two recipes on one copy so their shortlists agree |
+| `agent/actions/choose_project.ts` | The entity and the wording |
+| `agent/views/picker.ts` | What a row shows. Re-sample `brand.ts` from the host page |
+
+## What that build learned the hard way
+
+- **Only what is on screen goes back to the agent.** Returning the whole account
+  put every project name into the model's context on every ask.
+- **Say what is actually on screen.** "25 projects to choose from" is false when
+  the account holds a thousand.
+- **Styles go in `header`.** `host` lives inside the component's own frame.
+- **Grow into search later.** The production picker adds a search box that ranks
+  a locally held pool with the SDK's fuzzy match (up to ~500 rows), and falls
+  back to server search past that. Start without it.

package/recipes/pick-from-a-list/agent/actions/choose_project.ts

@@ -0,0 +1,161 @@
+// Asks the user which project to work with, and waits for the answer.
+//
+// This exists so that asking is a decision the agent makes, not a side effect of
+// looking something up. find_project_id answers questions and must never put a
+// widget in front of someone who only asked one.
+
+import { listProjects } from "../api/projects";
+import { toSummary, type ProjectSummary } from "../projects";
+import { mountProjectPicker } from "../views/picker";
+
+/** One screen of projects. */
+const PAGE_SIZE = 25;
+
+type ChooseProjectData = {
+  askable: boolean;
+  query?: string | null;
+  purpose?: string | null;
+  narrowed?: boolean;
+  matched?: number;
+  total?: number;
+  projects?: ProjectSummary[];
+};
+
+type ChooseProjectResult = {
+  success: boolean;
+  message?: string;
+  error?: string;
+  reason?: string;
+  data?: ChooseProjectData;
+};
+
+export const choose_project = {
+  execute: async (params: { name?: string; purpose?: string }): Promise<ChooseProjectResult> => {
+    const query = typeof params?.name === "string" ? params.name.trim() : "";
+    const purpose = typeof params?.purpose === "string" ? params.purpose.trim() : "";
+
+    const res = await listProjects({ search: query, pageSize: PAGE_SIZE });
+    if (!res.ok) {
+      console.warn("[choose_project]", res.status, res.reason, res.detail);
+      return { success: false, error: res.error, reason: res.reason, data: { askable: false } };
+    }
+
+    let { projects, total } = res.data;
+    let narrowed = Boolean(query);
+
+    // A name that matches nothing falls back to the whole list rather than
+    // showing an empty picker the user cannot answer.
+    if (projects.length === 0 && query) {
+      const all = await listProjects({ pageSize: PAGE_SIZE });
+      if (all.ok) {
+        projects = all.data.projects;
+        total = all.data.total;
+        narrowed = false;
+      }
+    }
+
+    if (total === 0) {
+      return {
+        success: true,
+        message: "This account has no projects yet, so there is none to pick.",
+        data: { askable: false, total: 0, projects: [] },
+      };
+    }
+
+    // Rows empty while the account is not: the fallback failed. "No projects"
+    // here would be a lie repeated to someone who has hundreds.
+    if (projects.length === 0) {
+      return {
+        success: false,
+        error: "The project list could not be loaded just now.",
+        data: { askable: false, total },
+      };
+    }
+
+    // Only what is on screen goes back to the agent — never the whole account.
+    const shown = projects.map(toSummary);
+    return {
+      success: true,
+      message: `A list of ${shown.length} project${shown.length === 1 ? "" : "s"} is on screen and the user is choosing one.`,
+      data: {
+        askable: true,
+        query: query || null,
+        purpose: purpose || null,
+        narrowed,
+        matched: shown.length,
+        total,
+        projects: shown,
+      },
+    };
+  },
+
+  awaitUserInput: true,
+
+  // `result` is what execute RETURNED, not the action's params.
+  render: (
+    result: ChooseProjectResult | undefined,
+    host: HTMLElement,
+    header: HTMLElement,
+    callback: (value: unknown, disableOnSubmit?: boolean) => void,
+  ) => {
+    const data = result?.data;
+    const projects = data?.projects ?? [];
+
+    // Nothing to ask about — hand the result back rather than showing an empty
+    // card the user cannot answer.
+    if (!result || result.success === false || data?.askable === false || projects.length === 0) {
+      callback(result, true);
+      return;
+    }
+
+    const total = data?.total ?? projects.length;
+    const showing = projects.length;
+    // Say what is actually on screen.
+    const subtitle =
+      data?.narrowed && data.query
+        ? `${showing} project${showing === 1 ? "" : "s"} match "${data.query}".`
+        : showing < total
+          ? `Showing ${showing} of ${total}.`
+          : `${total} project${total === 1 ? "" : "s"} to choose from.`;
+
+    mountProjectPicker(host, header, {
+      title: data?.purpose ? `Which project for ${data.purpose}?` : "Which project?",
+      subtitle,
+      projects,
+      onSubmit: (choice, offered) => {
+        if (choice.kind === "project") {
+          callback(
+            {
+              success: true,
+              message: `The user chose the project "${choice.project.name}".`,
+              data: { ...choice.project, chosenByUser: true },
+            },
+            true,
+          );
+          return;
+        }
+        if (choice.kind === "cancel") {
+          callback(
+            {
+              success: true,
+              message: "The user closed the list without choosing a project.",
+              data: { chosenByUser: false, cancelled: true },
+            },
+            true,
+          );
+          return;
+        }
+        // The list did not hold what they wanted. Say what was offered, so the
+        // next question can be about what they meant.
+        callback(
+          {
+            success: true,
+            message: "The user rejected every project on the list.",
+            data: { chosenByUser: false, offered: offered.map((p) => p.name) },
+          },
+          true,
+        );
+      },
+    });
+  },
+};

package/recipes/pick-from-a-list/agent/api/projects.ts

@@ -0,0 +1,36 @@
+// The app's own project list. Replace the path, the parameter names and the
+// envelope with what you OBSERVED — type only the keys you read.
+//
+// Prefer an endpoint that searches and counts on the server. One production
+// build started on an endpoint that returned the whole account in one response;
+// counting a thousand rows to answer "how many projects do I have?" is how a
+// lookup becomes the slowest thing the agent does.
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type Project = {
+  id: string;
+  name: string;
+  status?: string | null;
+  updatedAt?: string | null;
+};
+
+export type ProjectPage = {
+  projects: Project[];
+  /** Every project in the account, not just this page. */
+  total: number;
+};
+
+export async function listProjects(
+  options: { search?: string; pageSize?: number } = {},
+): Promise<ApiResult<ProjectPage>> {
+  const query = new URLSearchParams();
+  if (options.search) query.set("search", options.search);
+  query.set("pageSize", String(options.pageSize && options.pageSize > 0 ? options.pageSize : 25));
+
+  const res = await apiFetch<{ items?: Project[]; total?: number }>(`/__observe_me/projects?${query}`);
+  if (!res.ok) return res;
+
+  const rows = Array.isArray(res.data?.items) ? res.data.items : [];
+  return { ok: true, status: res.status, data: { projects: rows, total: res.data?.total ?? rows.length } };
+}

package/recipes/pick-from-a-list/agent/projects.ts

@@ -0,0 +1,40 @@
+// Name matching shared by the action that RESOLVES a project and the one that
+// asks the user to PICK one. They must agree: a name the lookup calls ambiguous
+// has to produce the same shortlist when the user is shown it.
+
+import type { Project } from "./api/projects";
+import { rankBy } from "./utils";
+
+/** Only what the agent needs to talk about a project. Never the whole row. */
+export type ProjectSummary = {
+  projectId: string;
+  name: string;
+  status: string | null;
+};
+
+export function toSummary(project: Project): ProjectSummary {
+  return { projectId: project.id, name: project.name, status: project.status ?? null };
+}
+
+export type MatchType = "exact" | "starts_with" | "contains";
+
+export const MATCH_RANK: Record<MatchType, number> = { exact: 0, starts_with: 1, contains: 2 };
+
+export function classify(name: string, query: string): MatchType | null {
+  const a = name.trim().toLowerCase();
+  const b = query.trim().toLowerCase();
+  if (!b) return null;
+  if (a === b) return "exact";
+  if (a.startsWith(b)) return "starts_with";
+  if (a.includes(b)) return "contains";
+  return null;
+}
+
+/**
+ * Loose phrasing — a typo, a half-remembered word. Substring hits lead, the
+ * SDK's fuzzy match fills in behind; if the agent is not ready the substring
+ * pass stands alone. That is `rankBy`, which was lifted from this pattern.
+ */
+export function nearMatches(projects: ProjectSummary[], query: string, limit: number): ProjectSummary[] {
+  return rankBy(projects, query, { searchKeys: ["name", "status"], idOf: (p) => p.projectId, limit });
+}

package/recipes/pick-from-a-list/agent/views/brand.ts

@@ -0,0 +1,14 @@
+// Neutral placeholders. SAMPLE the real values from computed styles on the host
+// page and record where each came from in docs/app-profile.md. Never edit by eye.
+
+export const brand = {
+  text: "rgb(17, 24, 39)",
+  muted: "rgb(107, 114, 128)",
+  primary: "rgb(37, 99, 235)",
+  border: "rgb(229, 231, 235)",
+  tint: "rgb(243, 244, 246)",
+  surface: "rgb(255, 255, 255)",
+  radius: "8px",
+  size: { base: "14px", small: "12px" },
+  font: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+} as const;