feat: implement the six showcase proactive agents

.gitignore

@@ -1 +1,2 @@
 .DS_Store
+node_modules/

README.md

@@ -4,5 +4,33 @@
 
 **Agent Workforce.**
 ---
-A collection of proactive agents
+A collection of proactive agents. Each folder is a deployable agent — a typed
+`persona.ts` (what it listens to + how it runs) and an `agent.ts` handler (what
+it does). The persona compiles to `persona.json`; deploy with
+`agentworkforce deploy ./<agent>/persona.json --mode cloud`.
 
+## The agents
+
+| Agent | Fires on | What it does |
+| --- | --- | --- |
+| [**granola**](granola/) | a new Granola note (Nango sync → `file.created`) | Detects prospect calls, files a Linear issue with the ask, and opens a GitHub PR implementing it. |
+| [**hn-monitor**](hn-monitor/) | schedule (2×/day) | Scans Hacker News for your topics and posts a digest to Slack. |
+| [**linear**](linear/) | Linear `issue.create` (labelled) / `comment.create` | Implements the issue and opens a GitHub PR; comments the PR link back. |
+| [**review**](review/) | GitHub PR opened / updated / reviewed / CI finished | Reviews the PR, fixes the issues it (and other bots) find, resolves failing CI and merge conflicts, DMs you when it's ready, and merges once you approve. |
+| [**spotify-releases**](spotify-releases/) | schedule (daily) | Checks for new releases from artists you follow and DMs them to you. |
+| [**vendor-monitor**](vendor-monitor/) | schedule (weekday mornings) | Watches the vendors in your stack for new releases and posts changes to your team channel. |
+
+## How they're built
+
+- **Typed authoring.** Personas use `definePersona` from `@agentworkforce/persona-kit`, so `integrations.<provider>.triggers[].on` autocompletes the provider's real events and is linted at deploy.
+- **Integrations are VFS-backed.** Agents read/write providers (Slack, Linear, GitHub, Gmail/Google-Mail, Granola…) through the Relayfile VFS and the typed `ctx` clients — no direct API calls or tokens to manage.
+- **Repos are materialized, not cloned.** For agents that touch code, the cloud materializes the GitHub repo into the sandbox (`ctx.sandbox.cwd`) via Relayfile, so handlers never run `git clone` — they just hand the work to the coding agent (`ctx.harness.run`).
+
+## Run one locally
+
+```sh
+npm install
+npm run typecheck                                   # tsc over every agent
+agentworkforce persona compile ./hn-monitor/persona.ts
+agentworkforce deploy ./hn-monitor/persona.json --mode cloud --input SLACK_CHANNEL=C0123ABCD
+```

granola/agent.ts

@@ -0,0 +1,127 @@
+/**
+ * granola-prospect handler.
+ *
+ *   a new Granola note syncs in (storage `file.created` at /granola/notes/…)
+ *     → read the note's transcript from the VFS
+ *     → ask the model "is this a prospect call, and what did they ask for?"
+ *     → if yes: file a Linear issue, then have the coding agent open a PR for it
+ */
+import { handler, type WorkforceCtx } from '@agentworkforce/runtime';
+
+interface Ask {
+  isProspect: boolean;
+  title: string;
+  summary: string;
+}
+
+export default handler(async (ctx, event) => {
+  // Notes arrive via the Nango sync as storage events; the clock isn't one.
+  if (event.source === 'cron') return;
+
+  const notePath = readNotePath(event.payload);
+  if (!notePath || !notePath.includes('/granola/notes/')) return; // ignore folders/other writes
+  if (!ctx.linear) throw new Error('granola-prospect requires the linear integration');
+
+  const transcript = await readNote(ctx, notePath);
+  if (!transcript) return;
+
+  const ask = await classify(ctx, transcript);
+  if (!ask.isProspect) {
+    ctx.log('info', 'granola-prospect.not-a-prospect', {});
+    return;
+  }
+
+  const teamId = await resolveTeamId(ctx);
+  const issue = await ctx.linear.createIssue({ teamId, title: ask.title, description: ask.summary });
+  ctx.log('info', 'granola-prospect.issue-created', { url: issue.url });
+
+  // The cloud materializes the github repo into the sandbox (ctx.sandbox.cwd)
+  // via relayfile — no clone, no gh/git. The GitHub integration opens the PR.
+  const run = await ctx.harness.run({
+    cwd: ctx.sandbox.cwd,
+    prompt: `A prospect asked for the following. Comprehensively implement it (every change needed to fully address the ask), then open a GitHub pull request with your changes — the GitHub integration opens it, do not use git or the \`gh\` CLI. Put the PR URL on the last line.\n\nLinear issue: ${issue.url}\n\n${ask.summary}`
+  });
+
+  const prUrl = run.output.match(/https?:\/\/\S*\/pull\/\d+/g)?.pop();
+  if (prUrl) await ctx.linear.comment(issue.id, `:rocket: Implementation PR: ${prUrl}`);
+});
+
+/** A storage `file.created` event carries the VFS path of the file that landed. */
+function readNotePath(payload: unknown): string | undefined {
+  const p = payload as { path?: string; relayfilePath?: string; data?: { path?: string } } | null;
+  return p?.path ?? p?.relayfilePath ?? p?.data?.path;
+}
+
+/** Read the synced note JSON and pull out its transcript / content text. */
+async function readNote(ctx: WorkforceCtx, path: string): Promise<string | undefined> {
+  try {
+    const note = JSON.parse(await ctx.files.read(path)) as {
+      transcript?: string;
+      content?: string;
+      summary?: string;
+    };
+    return note.transcript ?? note.content ?? note.summary;
+  } catch {
+    return undefined;
+  }
+}
+
+async function classify(ctx: WorkforceCtx, transcript: string): Promise<Ask> {
+  const prompt = [
+    'Read this meeting transcript. Decide if it is a sales/prospect call where the',
+    'prospect asked for a feature or change. Reply with JSON only:',
+    '{"isProspect": boolean, "title": "short issue title", "summary": "what they asked for"}',
+    '',
+    transcript.slice(0, 8000)
+  ].join('\n');
+  try {
+    // Models often wrap JSON in ```json fences — strip them before parsing.
+    const raw = (await ctx.llm.complete(prompt, { maxTokens: 400 })).replace(/```json\s*|```/g, '').trim();
+    return JSON.parse(raw) as Ask;
+  } catch {
+    return { isProspect: false, title: '', summary: '' };
+  }
+}
+
+/**
+ * Which Linear team to file under. An explicit LINEAR_TEAM_ID wins; otherwise
+ * we auto-pick when the `fetch-teams` sync shows exactly one team, and block
+ * (with a helpful list) when it's ambiguous.
+ */
+async function resolveTeamId(ctx: WorkforceCtx): Promise<string> {
+  const configured = input(ctx, 'LINEAR_TEAM_ID');
+  if (configured) return configured;
+
+  const teams = await listLinearTeams(ctx);
+  if (teams.length === 1) return teams[0].id;
+
+  const found = teams.length ? ` Teams: ${teams.map((t) => `${t.name} (${t.id})`).join(', ')}.` : '';
+  throw new Error(
+    `Can't pick a Linear team automatically — found ${teams.length}. Set LINEAR_TEAM_ID.${found}`
+  );
+}
+
+/** Linear teams the `fetch-teams` sync materialized at /linear/teams/*.json. */
+async function listLinearTeams(ctx: WorkforceCtx): Promise<Array<{ id: string; name: string }>> {
+  const root = process.env.RELAYFILE_MOUNT_ROOT?.replace(/\/$/, '') ?? '';
+  const { output } = await ctx.sandbox.exec(
+    `find ${root}/linear/teams -maxdepth 1 -name '*.json' -not -name '_index.json' 2>/dev/null || true`
+  );
+  const teams: Array<{ id: string; name: string }> = [];
+  for (const file of output.split('\n').map((l) => l.trim()).filter(Boolean)) {
+    try {
+      const t = JSON.parse(await ctx.files.read(file)) as { id?: string; name?: string };
+      if (t.id) teams.push({ id: t.id, name: t.name ?? t.id });
+    } catch {
+      /* skip unreadable entries */
+    }
+  }
+  return teams;
+}
+
+// ── tiny helpers ────────────────────────────────────────────────────────────
+function input(ctx: WorkforceCtx, name: string): string | undefined {
+  const spec = ctx.persona.inputSpecs?.[name];
+  const v = process.env[spec?.env ?? name] ?? ctx.persona.inputs?.[name] ?? spec?.default;
+  return v && v.trim() ? v : undefined;
+}

granola/persona.ts

@@ -0,0 +1,48 @@
+import { definePersona } from '@agentworkforce/persona-kit';
+
+/**
+ * Granola Agent — when a Granola meeting recording lands, detects prospect
+ * calls, files a Linear issue with what they asked for, and opens a GitHub PR
+ * implementing it.
+ */
+export default definePersona({
+  id: 'granola-prospect',
+  intent: 'relay-orchestrator',
+  tags: ['discovery', 'implementation'],
+  description: 'When a Granola recording lands, detects prospect calls, files a Linear issue with the ask, and opens a GitHub PR implementing it.',
+  cloud: true,
+  useSubscription: true,
+
+  integrations: {
+    // Granola has no realtime webhook yet, so notes arrive via the Nango
+    // `granola-relay:fetch-notes` sync, which writes each note to the VFS at
+    // /granola/notes/<id>.json and fires a storage `file.created` event.
+    granola: { triggers: [{ on: 'file.created' }] },
+    linear: {},
+    // The cloud materializes this repo into the sandbox (ctx.sandbox.cwd) via
+    // relayfile — the agent never clones it.
+    github: { scope: { repo: 'your-org/your-repo' } }
+  },
+
+  inputs: {
+    // Optional: auto-resolved from the `fetch-teams` sync when there's exactly
+    // one Linear team. Only needed to disambiguate when you have several.
+    LINEAR_TEAM_ID: {
+      description: 'Linear team to file prospect issues under (only needed if you have multiple teams).',
+      env: 'LINEAR_TEAM_ID',
+      optional: true
+    }
+  },
+
+  harness: 'claude',
+  model: 'claude-sonnet-4-6',
+  systemPrompt: 'Turn prospect asks from meeting transcripts into a Linear issue and a small implementing PR.',
+  harnessSettings: {
+    reasoning: 'high',
+    timeoutSeconds: 1800,
+    sandboxMode: 'workspace-write',
+    workspaceWriteNetworkAccess: true
+  },
+
+  onEvent: './agent.ts'
+});

hn-monitor/agent.ts

@@ -0,0 +1,81 @@
+/**
+ * hn-monitor handler.
+ *
+ *   fetch the HN front page
+ *     → keep stories whose title matches one of your TOPICS
+ *     → drop ones already posted (durable memory)
+ *     → summarize with ctx.llm
+ *     → post to Slack
+ */
+import { handler, type WorkforceCtx } from '@agentworkforce/runtime';
+
+interface Story {
+  id: number;
+  title: string;
+  url: string;
+  points: number;
+}
+
+export default handler(async (ctx, event) => {
+  if (event.source !== 'cron') return;
+  if (!ctx.slack) throw new Error('hn-monitor requires the slack integration');
+
+  const channel = input(ctx, 'SLACK_CHANNEL');
+  if (!channel) throw new Error('SLACK_CHANNEL is required');
+  const topics = list(input(ctx, 'TOPICS')).map((t) => t.toLowerCase());
+
+  const stories = await fetchFrontPage();
+  const matches = stories.filter((s) => topics.some((t) => s.title.toLowerCase().includes(t)));
+
+  const seen = await loadSeen(ctx);
+  const fresh = matches.filter((s) => !seen.includes(s.id));
+  if (fresh.length === 0) {
+    ctx.log('info', 'hn-monitor.nothing-new', { matched: matches.length });
+    return;
+  }
+
+  await ctx.slack.post(channel, await summarize(ctx, fresh));
+  await saveSeen(ctx, [...seen, ...fresh.map((s) => s.id)].slice(-200));
+});
+
+/** Top ~30 front-page stories via the public HN Algolia API. */
+async function fetchFrontPage(): Promise<Story[]> {
+  const res = await fetch('https://hn.algolia.com/api/v1/search?tags=front_page&hitsPerPage=30');
+  const data = (await res.json()) as { hits: Array<{ objectID: string; title: string; url: string | null; points: number }> };
+  return data.hits.map((h) => ({
+    id: Number(h.objectID),
+    title: h.title,
+    url: h.url ?? `https://news.ycombinator.com/item?id=${h.objectID}`,
+    points: h.points
+  }));
+}
+
+async function summarize(ctx: WorkforceCtx, stories: Story[]): Promise<string> {
+  const lines = stories.map((s) => `- ${s.title} (${s.points} pts) ${s.url}`).join('\n');
+  const digest = await ctx.llm.complete(
+    `Write a tight Slack digest (mrkdwn, one bullet per story, lead with why it matters):\n\n${lines}`,
+    { maxTokens: 500 }
+  );
+  return `:newspaper: *Hacker News* — ${stories.length} new match(es)\n${digest.trim()}`;
+}
+
+// ── tiny helpers ────────────────────────────────────────────────────────────
+function list(raw: string | undefined): string[] {
+  return (raw ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+function input(ctx: WorkforceCtx, name: string): string | undefined {
+  const spec = ctx.persona.inputSpecs?.[name];
+  const v = process.env[spec?.env ?? name] ?? ctx.persona.inputs?.[name] ?? spec?.default;
+  return v && v.trim() ? v : undefined;
+}
+async function loadSeen(ctx: WorkforceCtx): Promise<number[]> {
+  const [item] = await ctx.memory.recall('hn-monitor seen', { tags: ['hn-monitor:seen'], limit: 1 });
+  try {
+    return item ? (JSON.parse(item.content) as number[]) : [];
+  } catch {
+    return [];
+  }
+}
+async function saveSeen(ctx: WorkforceCtx, ids: number[]): Promise<void> {
+  await ctx.memory.save(JSON.stringify(ids), { tags: ['hn-monitor:seen'], scope: 'workspace' });
+}

hn-monitor/persona.ts

@@ -0,0 +1,38 @@
+import { definePersona } from '@agentworkforce/persona-kit';
+
+/**
+ * Hacker News Monitor — scans HN a few times a day for the topics you care
+ * about and posts a short digest to Slack.
+ */
+export default definePersona({
+  id: 'hn-monitor',
+  intent: 'relay-orchestrator',
+  tags: ['discovery'],
+  description: 'Scans Hacker News a few times a day for topics you care about and posts a summary to Slack.',
+  cloud: true,
+
+  // Runs on a clock (09:00 & 17:00), not an event. No triggers needed.
+  schedules: [{ name: 'scan', cron: '0 9,17 * * *', tz: 'America/New_York' }],
+
+  // `slack` gives the handler the ctx.slack client to post the digest.
+  integrations: { slack: {} },
+
+  inputs: {
+    TOPICS: {
+      description: 'Comma-separated keywords to watch for (matched against story titles).',
+      env: 'TOPICS',
+      default: 'agents,ai,typescript,developer tools'
+    },
+    SLACK_CHANNEL: { description: 'Slack channel id to post the digest to.', env: 'SLACK_CHANNEL' }
+  },
+
+  // ctx.llm uses this model to summarize the matching stories.
+  harness: 'claude',
+  model: 'claude-haiku-4-5-20251001',
+  systemPrompt: 'Summarize Hacker News stories into a short, skimmable Slack digest.',
+  harnessSettings: { reasoning: 'low', timeoutSeconds: 120 },
+
+  memory: { enabled: true, scopes: ['workspace'], ttlDays: 7 },
+
+  onEvent: './agent.ts'
+});