makes the work
The worker
present
Exported functions in state/lib/outbound.ts. Does the actual work. Whatever it produces is what gets checked next.
drop another
.md file to compare - side-by-side diff against outbound
outbound
Routes your outgoing messages to the right channel.
description: "Triggers on prompt mention of 'outbound'."What it does for you
Routes your outgoing messages to the right channel.
What it produces
A recent result, so you can see the kind of work it returns.
loading…
How to get it
These run inside the Snappy workspace. Want this working in your business? I set skills like this up with you, in one focused week.
For developers how this skill is built, graded, and how it runs
at a glance- the short version
actorExported functions in state/lib/outbound.ts.
auditorNone wired yet - eval is manual (Robert review).
eval modeshape
categoryChannels
stages2
dependspost
what's inside - the parts that make up a skill 3/4 present
A skill is just a few plain-text files. Only the main one is required. The rest are optional, added as the work needs them. This is what the skill is made of; how it runs is just below.
The skill
state/skills/outbound/SKILL.md
present
the skill itself, in plain text
The main file. It says what the skill is and lays out the steps in plain English.
Code
state/lib/outbound.ts
present
code the skill can run
Reusable code this skill can call when it needs to.
Scripts
state/bin/outbound/
not present
helper scripts
Optional. Added when a skill has a few commands to run.
Loader
state/skills/outbound/AGENTS.md
present
what the AI loads on the fly
Loaded automatically the moment this skill is needed. Kept short on purpose.
how it's graded - what counts as a good run 4 criteria · 4 deterministic
Each row is one thing a good run has to get right. deterministic means a quick check decides, pass or fail. judge means the AI reads the result and rates it. Grading each piece on its own (instead of one overall score) shows exactly where a run fell short, so the fix is obvious.
name
kind
check
calls_resolve_contact
deterministic
The skill calls the 'resolveContact' function from 'state/lib/outbound.ts' with 'resolveContact_input'.
calls_pick_channel
deterministic
The skill calls the 'pickChannel' function from 'state/lib/outbound.ts' with 'pickChannel_input'.
calls_send
deterministic
The skill calls the 'send' function from 'state/lib/outbound.ts' with 'send_input'.
logs_pending_eval_row
deterministic
A row is appended to 'state/log/pending-eval.ndjson' after the skill execution.
how it runs - the shared frame every skill uses 5/5 present
Every skill runs the same way. One part does the work, a separate part checks it, and a short loader hands the AI exactly what it needs for the job. Anything this skill doesn't use shows a one-line note saying why, on purpose, not by accident.
checks the work
The reviewer
present
None wired yet - eval is manual (Robert review).
A separate checker grades the work, so the part that made it can't approve its own work.
frame
learns
Self-correction
present
fixes itself
When a run hits a gap, the skill gets edited on the spot [FIXED] or queued for a bigger rewrite [LOGGED], so it keeps getting better.
tidies up
Background fixes
present
queued for rewrite
Bigger fixes that can't be made on the spot get queued and rewritten in the background later.
remembers
Run history
present
state/log/pending-eval.ndjson Every run is written down here, then reviewed by hand each week.
Critical rules
the things this skill must not get wrong
- Outbound is a SEND surface — apply > scope. Crossing to apply requires the skill page's requires: keys present in the payload (program.md loop rule).
- Every reader-facing outbound message MUST pass voice.checkTone() before send — actor (this lib) ≠ auditor (voice.ts)
- For LinkedIn-channel outbound, the round-trip eval is "an independent fetch from a different session sees the message" — not the write response. Channel libs implement this; do not skip.
- NEVER fan out parallel agent-browser writes for DM-channel outbound — serialize per program.md "no parallel agent-browser writes" rule
what it has learned - fixes written back in over time sample
When a run hits something this skill didn't handle, the fix gets written back into the skill so it doesn't happen again. FIXED means it was corrected on the spot. LOGGED means it's queued for a bigger rewrite. Either way, the skill gets a little better and never makes the same mistake twice.
- Loading feedback rows…
how the work flows- who makes it, who checks it
inputs
post
actor
Exported functions in state/lib/outbound.ts.
1
generator
invoke
actor = Exported functions in state/lib/outbound.ts.
import from `state/lib/outbound.ts` — `resolveContact()`, `pickChannel()`, `send()
auditor
None wired yet - eval is manual (Robert review).
2
data
eval log
`state/log/pending-eval.ndjson` (manual review until shape gate added)
SKILL.md- the skill, written out in plain English
outbound
Channel router for outbound messages.
Ported from kernel snappy-outbound in Phase 0.5. See state/lib/outbound.ts for the full API surface.
Steps
resolveContact()- seestate/lib/outbound.tspickChannel()- seestate/lib/outbound.tssend()- seestate/lib/outbound.ts
Eval
Actor: the exported functions in state/lib/outbound.ts. Auditor: none wired yet - eval is manual (Robert review). File a state/log/pending-eval.ndjson row on each run.
Score convention:
| Outcome | Score |
|---|---|
| Pass on first try | 1.0 |
| Failed first, auto-fix applied, re-check passed | 0.5 |
| Still failing or unrecoverable | 0.0 |
Gotchas
via the Phase 0.5 driver. Only these rewrites were applied: already in state/lib/)
realpathSync(process.argv[1])CLI guard wrapped in try/catch
- See the kernel SKILL.md for the original long-form guidance if you need it
(read-only reference at the kernel path above).
Graduation
This skill is prose. Graduate by defining a deterministic auditor and flipping eval: auto.
Rubric
criteria:
- name: calls_resolve_contact
kind: deterministic
check: "The skill calls the 'resolveContact' function from 'state/lib/outbound.ts' with 'resolveContact_input'."
- name: calls_pick_channel
kind: deterministic
check: "The skill calls the 'pickChannel' function from 'state/lib/outbound.ts' with 'pickChannel_input'."
- name: calls_send
kind: deterministic
check: "The skill calls the 'send' function from 'state/lib/outbound.ts' with 'send_input'."
- name: logs_pending_eval_row
kind: deterministic
check: "A row is appended to 'state/log/pending-eval.ndjson' after the skill execution."AGENTS.md- what the AI loads when this skill comes up
outbound - loader
Per-turn rules for the outbound skill. Full reference: state/skills/outbound/SKILL.md. Do not skip these.
Critical Rules
- Outbound is a SEND surface - apply > scope. Crossing to apply requires the skill page's
requires:keys present in the payload (program.md loop rule). - Every reader-facing outbound message MUST pass
voice.checkTone()before send - actor (this lib) ≠ auditor (voice.ts) - For LinkedIn-channel outbound, the round-trip eval is "an independent fetch from a different session sees the message" - not the write response. Channel libs implement this; do not skip.
- NEVER fan out parallel agent-browser writes for DM-channel outbound - serialize per program.md "no parallel agent-browser writes" rule
Commands
| ui dashboard | state/skills/outbound/resources/ui.openui | |invoke: import from state/lib/outbound.ts - resolveContact(), pickChannel(), send() |tone gate: import { checkTone } from "../lib/voice.ts" (run before send) |eval log: state/log/pending-eval.ndjson (manual review until shape gate added)
OpenUI Resource
- Skill-owned OpenUI Lang resource:
state/skills/outbound/resources/ui.openui. Read it before rendering or editing this skill's generated component surface. - Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
- System resources compose OpenUI primitives and inherit SnappyChat tokens. Use
ui_contract: brandedin SKILL.md only for deliberate platform or client visuals.
Known Pitfalls
- Phase 0.5 port from
snappy-outbound- mechanical surface, hard-won rules live in the channel libs (state/lib/linkedin.ts,state/lib/slack.ts,state/lib/email.ts,state/lib/whatsapp.ts,state/lib/telegram.ts) pickChannel()may resolve to a stale channel preference - verify the contact is actually reachable on the chosen channel before firing send
Self-Test
An agent reading this should correctly:
- [ ] Run
voice.checkTone()on any draft beforesend()fires? - [ ] Serialize browser-channel sends rather than parallelizing?
- [ ] Verify the receive-side via independent fetch instead of trusting the write response?
Self-report
If this loader fell short, append a line:
echo "[$(date -u +%FT%TZ)] outbound: <what was missing>" >> state/log/loader-feedback.log<!-- kernel-ok: historical attribution for the PID-loader pattern. -->
Self-correcting loader (PID feedback)
This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.
Before you finish, do two things:
1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.
- Default action: edit this file. Surgical. Add the missing line, table
row, or code example where it belongs. No restructuring.
- Only
LOGGEDis allowed when: the fix needs >10 lines, spans multiple
files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.
- "I didn't have time" / "it's minor" / "the next agent will figure it out"
are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.
- Concrete example of a valid P-fix: discover
agent-browser screenshot
takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.
- The goal: the next agent never has to leave the loader.
2. Log the result.
echo "[$(date -u +%FT%TZ)] outbound: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.logFIXED= you patched this loader inline (P-fix).LOGGED= too large for inline; the PostToolUse enqueue + Stop-hook drain
will rewrite the loader from scratch on next session-end.
Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.
api.ts- the code it can call
#!/usr/bin/env npx tsx
/**
* snappy-outbound/api.ts -- Channel router for outbound messages.
*
* One send() call. Picks slack/email/linkedin/telegram/whatsapp/imessage
* from contact.preferred_channel (+ fallback chain) and dispatches to the
* right channel skill's native send function. Returns the Cert shape that
* staged-action deliver hooks expect.
*
* Email is draft-only by policy (same as freshbooks). LinkedIn is manual-only.
* Everything else sends immediately — the caller is expected to gate that
* behind stagedAction's apply+payload check.
*
* Usage:
* npx tsx api.ts send <contact_id> "<body>" [--channel <ch>] [--subject <s>]
* npx tsx api.ts pick <contact_id>
*
* Module:
* import { send, pickChannel, resolveContact, type Channel, type Cert } from "./outbound.ts";
*/
import { env } from "./env.ts";
import { getContact } from "./knowledge.ts";
import { sendDm as slackSendDm, sendSlackMessage } from "./slack.ts";
import { createEmailDraft } from "./email.ts";
import { realpathSync } from "fs";
/**
* When SNAPPY_OUTBOUND_DRY_RUN=1 the router short-circuits every deliver:
* it still resolves the contact and picks the channel, but returns a
* synthetic ok:true Cert without touching any downstream skill. Used by
* recipe tests and by the nightly audit to verify routing without noise.
*/
const DRY_RUN = env("SNAPPY_OUTBOUND_DRY_RUN", false) === "1";
export type Channel = "slack" | "email" | "linkedin" | "telegram" | "whatsapp" | "imessage";
export type Cert = {
ok: boolean;
link?: string;
note?: string;
error?: string;
};
export type SendInput = {
contact_id?: number;
handle?: string; // bypass contact lookup, route directly
channel?: Channel;
body: string;
subject?: string; // email only
thread_id?: string; // slack only
};
export type ContactRecord = {
id: number;
name?: string;
email?: string;
phone?: string;
linkedin_url?: string;
preferred_channel?: string;
slack_member_id?: string;
telegram_chat_id?: string;
whatsapp_number?: string;
[k: string]: unknown;
};
export type ChannelChoice = {
channel: Channel;
reason: string;
handle: string;
};
const FALLBACK_ORDER: Channel[] = [
"slack",
"email",
"linkedin",
"telegram",
"imessage",
"whatsapp",
];
// ---- contact resolution ----
export async function resolveContact(contact_id: number): Promise<ContactRecord | null> {
try {
const c = await getContact(contact_id);
if (!c || typeof c !== "object") return null;
return c as ContactRecord;
} catch {
return null;
}
}
function handleFor(contact: ContactRecord, channel: Channel): string | null {
switch (channel) {
case "slack":
return (contact.slack_member_id as string) || null;
case "email":
return (contact.email as string) || null;
case "linkedin":
return (contact.linkedin_url as string) || null;
case "telegram":
return (contact.telegram_chat_id as string) || null;
case "whatsapp":
return (contact.whatsapp_number as string) || (contact.phone as string) || null;
case "imessage":
return (contact.phone as string) || null;
}
}
export function pickChannel(
contact: ContactRecord,
explicit?: Channel,
): ChannelChoice | null {
if (explicit) {
const h = handleFor(contact, explicit);
if (h) return { channel: explicit, reason: "explicit", handle: h };
return null;
}
const preferred = contact.preferred_channel as Channel | undefined;
if (preferred && FALLBACK_ORDER.includes(preferred)) {
const h = handleFor(contact, preferred);
if (h) return { channel: preferred, reason: "preferred_channel", handle: h };
}
for (const ch of FALLBACK_ORDER) {
const h = handleFor(contact, ch);
if (h) return { channel: ch, reason: "fallback", handle: h };
}
return null;
}
// ---- per-channel dispatch ----
async function deliverSlack(handle: string, body: string, thread_id?: string): Promise<Cert> {
try {
// handle starts with U → DM; starts with C → channel
if (handle.startsWith("C")) {
const r = await sendSlackMessage(handle, body, thread_id);
return { ok: true, note: `slack channel ${handle}`, link: (r as any)?.permalink };
}
const r = await slackSendDm(handle, body);
return { ok: true, note: `slack dm ${handle}`, link: (r as any)?.permalink };
} catch (e: any) {
return { ok: false, error: `slack send failed: ${e?.message || e}` };
}
}
async function deliverEmail(to: string, body: string, subject?: string): Promise<Cert> {
try {
const draft = await createEmailDraft(to, subject || "(no subject)", body);
return {
ok: true,
link: draft.gmailUrl,
note: `email draft created (human must send from Gmail UI)`,
};
} catch (e: any) {
return { ok: false, error: `email draft failed: ${e?.message || e}` };
}
}
async function deliverLinkedIn(profile_url: string): Promise<Cert> {
return {
ok: false,
link: profile_url,
note: "manual — LinkedIn DMs have no programmatic send path; open the profile and paste",
error: "linkedin:manual",
};
}
async function deliverTelegram(chat_id: string, body: string): Promise<Cert> {
try {
const mod = await import("./telegram.ts");
const r = await (mod as any).sendText(chat_id, body);
return { ok: true, note: `telegram ${chat_id}`, link: r?.permalink };
} catch (e: any) {
return { ok: false, error: `telegram send failed: ${e?.message || e}` };
}
}
async function deliverWhatsApp(to: string, body: string): Promise<Cert> {
try {
const mod = await import("./whatsapp.ts");
const r = await (mod as any).sendMessage(to, body);
return { ok: true, note: `whatsapp ${to}`, link: r?.permalink };
} catch (e: any) {
return { ok: false, error: `whatsapp send failed: ${e?.message || e}` };
}
}
async function deliverIMessage(to: string, body: string): Promise<Cert> {
try {
const mod = await import("./imessage.ts");
const r = (mod as any).sendIMessage(to, body);
return { ok: true, note: `imessage ${to}`, link: typeof r === "string" ? undefined : r?.permalink };
} catch (e: any) {
return { ok: false, error: `imessage send failed: ${e?.message || e}` };
}
}
// ---- public send ----
/**
* Route a message to a contact via the best available channel.
* Returns a Cert suitable for a staged-action deliver hook.
*/
export async function send(input: SendInput): Promise<Cert & { channel?: Channel }> {
// direct-handle path: skip contact lookup
if (input.handle && input.channel) {
const cert = await dispatch(input.channel, input.handle, input.body, input.subject, input.thread_id);
return { ...cert, channel: input.channel };
}
if (!input.contact_id) {
return { ok: false, error: "send: contact_id or (handle + channel) required" };
}
const contact = await resolveContact(input.contact_id);
if (!contact) {
return { ok: false, error: `contact ${input.contact_id} not found` };
}
const choice = pickChannel(contact, input.channel);
if (!choice) {
return {
ok: false,
error: "no reachable channel",
note: `contact ${input.contact_id} has no handle for any of ${FALLBACK_ORDER.join("/")}`,
};
}
const cert = await dispatch(choice.channel, choice.handle, input.body, input.subject, input.thread_id);
return { ...cert, channel: choice.channel, note: cert.note ? `${cert.note} (${choice.reason})` : choice.reason };
}
async function dispatch(
channel: Channel,
handle: string,
body: string,
subject?: string,
thread_id?: string,
): Promise<Cert> {
if (DRY_RUN) {
return { ok: true, note: `DRY_RUN: would ${channel} → ${handle} (${body.length} chars)` };
}
switch (channel) {
case "slack": return deliverSlack(handle, body, thread_id);
case "email": return deliverEmail(handle, body, subject);
case "linkedin": return deliverLinkedIn(handle);
case "telegram": return deliverTelegram(handle, body);
case "whatsapp": return deliverWhatsApp(handle, body);
case "imessage": return deliverIMessage(handle, body);
}
}
// ---- CLI ----
if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
(async () => {
const [, , cmd, ...args] = process.argv;
switch (cmd) {
case "send": {
const contact_id = Number(args[0]);
const body = args[1];
if (!contact_id || !body) {
console.error("Usage: api.ts send <contact_id> \"<body>\" [--channel <ch>] [--subject <s>]");
process.exit(1);
}
const chIdx = args.indexOf("--channel");
const channel = chIdx >= 0 ? (args[chIdx + 1] as Channel) : undefined;
const subjIdx = args.indexOf("--subject");
const subject = subjIdx >= 0 ? args[subjIdx + 1] : undefined;
const cert = await send({ contact_id, body, channel, subject });
console.log(JSON.stringify(cert, null, 2));
break;
}
case "pick": {
const contact_id = Number(args[0]);
if (!contact_id) { console.error("Usage: api.ts pick <contact_id>"); process.exit(1); }
const contact = await resolveContact(contact_id);
if (!contact) { console.log(JSON.stringify({ error: "not found" }, null, 2)); break; }
const choice = pickChannel(contact);
console.log(JSON.stringify({ contact: { id: contact.id, name: contact.name }, choice }, null, 2));
break;
}
default:
console.log("Usage: npx tsx api.ts [send <id> <body>|pick <id>]");
}
})();
}
scripts- helper scripts it can run
prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).
how we check it- the checks, plus the last 10 runs
rubric
shape
schema-shape check (no inline rubric)
recent
mean 1.00 · 10 runs
actor/auditor: unverifiable
deps
post
| timestamp | verb | score | primary_issue | artifact |
|---|---|---|---|---|
| 2026-04-25 04:11Z | - | 1.00 | - | - |
| 2026-04-21 15:58Z | - | 1.00 | - | - |
| 2026-04-21 15:56Z | - | 1.00 | - | - |
| 2026-04-21 03:53Z | - | 1.00 | - | - |
| 2026-04-25 04:11Z | - | 1.00 | - | - |
| 2026-04-21 15:58Z | - | 1.00 | - | - |
| 2026-04-21 15:56Z | - | 1.00 | - | - |
| 2026-04-21 03:53Z | - | 1.00 | - | - |
| 2026-04-25 04:11Z | - | 1.00 | - | - |
| 2026-04-21 15:58Z | - | 1.00 | - | - |