@method-ai-hq/sdk 0.0.0-stage → 0.14.3

package/dist/packages/sdk/examples/support-triage/sample-tickets.json

@@ -0,0 +1,5 @@
+[
+  {"id": "T-1042", "subject": "Charged twice this month", "body": "Hi, my card was charged $49 two times on October 3 for the Team plan. We only have one workspace. Please refund the second charge.", "queue": "new", "priority": "normal", "tags": [], "notes": []},
+  {"id": "T-1043", "subject": "Can't get in", "body": "Since this morning nothing works for me. I tried twice. Can someone look at it?", "queue": "new", "priority": "normal", "tags": [], "notes": []},
+  {"id": "T-1044", "subject": "Export to CSV fails", "body": "When I export the March report to CSV I get the error 'Export failed (code 502)'. Other reports export fine. Our quarterly review is tomorrow morning.", "queue": "new", "priority": "normal", "tags": [], "notes": []}
+]

package/dist/packages/sdk/examples/support-triage/set-ticket.mjs

@@ -0,0 +1,9 @@
+import {helpdesk, main, ticketPath} from './helpdesk.mjs';
+import {change} from './triage.mjs';
+
+// --team-only: the move after a person's answer. It sets the chosen team's queue and adds no note.
+const teamOnly = process.argv.includes('--team-only');
+await main(async input => {
+  const ticket = await helpdesk(input.helpdesk, ticketPath(input.ticket_id), {method: 'PATCH', body: change(input, teamOnly)});
+  return {[teamOnly ? 'moved' : 'updated']: {id: ticket.id, queue: ticket.queue, priority: ticket.priority}};
+});

package/dist/packages/sdk/examples/support-triage/support-triage.method

@@ -0,0 +1,165 @@
+format: method/3.4
+name: Triage a support ticket
+goal: Read a new help desk ticket, choose its queue and priority, draft a first reply, and update the ticket. Ask a person when the team is unclear.
+run_data: device
+models:
+  writer: anthropic/claude-haiku-4.5
+secrets:
+  HELPDESK_TOKEN: API token for the help desk. read-ticket.mjs and set-ticket.mjs send it as a Bearer token.
+inputs:
+  ticket_id:
+    type: text
+    description: ID of the new ticket in the help desk, such as T-1042.
+environment:
+  helpdesk:
+    type: service
+    description: Help desk API. GET /tickets/ID reads a ticket; PATCH /tickets/ID sets its queue, priority, tags, and internal note.
+steps:
+  read:
+    name: Read the ticket
+    purpose: Reads the ticket from the help desk with HELPDESK_TOKEN and returns its id, subject, and text. Fails when the help desk does not return the ticket. Changes nothing.
+    in: {ticket_id: inputs.ticket_id, helpdesk: environment.helpdesk}
+    do: {kind: run, runtime: node, entrypoint: read-ticket.mjs}
+    out:
+      ticket: {type: record, fields: {id: text, subject: text, body: text}, description: The ticket as the help desk returned it.}
+
+  team:
+    name: Choose the team
+    in: {subject: ticket.subject, body: ticket.body}
+    do:
+      kind: classify
+      question: Which team should handle the main request in this support ticket?
+      options:
+        billing: Billing - invoices, charges, refunds, and plan changes.
+        technical: Technical - errors, outages, and problems using the product.
+        account: Account - sign-in, users, and access.
+        unclear: Unclear - the ticket does not say enough to choose, or no listed team fits.
+    out: team
+
+  refund:
+    name: Check for a refund request
+    in: {body: ticket.body}
+    do:
+      kind: classify
+      question: Does the customer ask for money back?
+      answer: yes_no
+    out: refund
+
+  urgency:
+    name: Score the urgency
+    in: {subject: ticket.subject, body: ticket.body}
+    do:
+      kind: classify
+      question: How urgent is this support ticket for the customer?
+      levels: [low, normal, high, urgent]
+    out: urgency
+
+  route:
+    name: Choose the queue and priority
+    purpose: Chooses the team's queue when the team is not unclear and its probability is at least 80%. Otherwise chooses the triage queue and marks the ticket for a person. The priority is the most likely urgency level. Adds the tag refund_request when the probability of a refund request is at least 50%. Returns the rule used. Changes nothing.
+    in: {team: team, refund: refund, urgency: urgency}
+    do: {kind: run, runtime: node, entrypoint: route.mjs}
+    out:
+      decision:
+        type: record
+        description: The queue, priority, and tags, whether a person must choose the team, and the rule used.
+        fields:
+          queue: text
+          priority: text
+          tags: {type: list, items: text}
+          needs_person: boolean
+          rule: text
+          reason: text
+
+  draft_reply:
+    name: Draft the first reply
+    in: {ticket: ticket}
+    do:
+      kind: call
+      model: writer
+      prompt: |
+        Write the first reply to this support ticket, for a support agent to check and send.
+        Thank the customer in one sentence. Then say in one or two sentences what happens next.
+        If the ticket does not say what is wrong, ask for the one detail that is missing.
+        Do not promise a refund, a date, or a fix. Sign it "The support team".
+
+        Subject: {{ticket.subject}}
+        {{ticket.body}}
+
+        Two replies that the team liked:
+
+        Ticket: "I was charged twice for October."
+        Reply: "Thank you for telling us about the double charge. Our billing team will check your October invoices and reply within one business day. The support team"
+
+        Ticket: "The export button does nothing."
+        Reply: "Thank you for the report. Which browser do you use, and does the export fail for every report or only for one? With that, our technical team can look into it. The support team"
+    out:
+      reply: {type: text, description: The reply draft for a support agent to check.}
+
+  update:
+    name: Update the ticket
+    purpose: Sets the ticket's queue, priority, and tags, and adds the reply draft as an internal note, with one PATCH request. A repeated request sets the same values, so a retry is safe. A ticket whose team is unclear goes to the triage queue.
+    in:
+      ticket_id: inputs.ticket_id
+      queue: decision.queue
+      priority: decision.priority
+      tags: decision.tags
+      note: reply
+      helpdesk: environment.helpdesk
+    do: {kind: run, runtime: node, entrypoint: set-ticket.mjs}
+    changes: [environment.helpdesk]
+    effects:
+      updated:
+        intent: The ticket has the chosen priority. The queue is not part of this effect, because the move step changes it after a person's answer.
+        in: {ticket_id: inputs.ticket_id, priority: decision.priority}
+        observe:
+          kind: http
+          path: /tickets/{inputs.ticket_id}
+          expect: {fields: {priority: "{inputs.priority}"}}
+    out:
+      updated: {type: record, fields: {id: text, queue: text, priority: text}, description: The queue and priority that the help desk returned.}
+
+  ask_person:
+    name: Ask a person for the team
+    when: decision.needs_person
+    after: update
+    in: {ticket: ticket, reason: decision.reason}
+    ask: |
+      Ticket {{ticket.id}} is in the triage queue: {{reason}}.
+      Subject: {{ticket.subject}}
+
+      Which team should handle it: billing, technical, or account?
+    out:
+      chosen_queue: {type: text, description: "billing, technical, or account"}
+
+  move:
+    name: Move the ticket to the chosen team
+    when: decision.needs_person
+    purpose: Rejects an answer that is not billing, technical, or account. Then sets that queue with one PATCH request and keeps the priority and tags. A repeated request sets the same values.
+    in:
+      ticket_id: inputs.ticket_id
+      queue: chosen_queue
+      priority: decision.priority
+      tags: decision.tags
+      helpdesk: environment.helpdesk
+    do: {kind: run, runtime: node, entrypoint: set-ticket.mjs, args: [--team-only]}
+    changes: [environment.helpdesk]
+    effects:
+      moved:
+        intent: The ticket is in the queue that the person chose.
+        in: {ticket_id: inputs.ticket_id, queue: chosen_queue}
+        observe:
+          kind: http
+          path: /tickets/{inputs.ticket_id}
+          expect: {fields: {queue: "{inputs.queue}"}}
+    out:
+      moved: {type: record, fields: {id: text, queue: text, priority: text}, description: The queue and priority that the help desk returned.}
+    accept:
+      unused_output: The receipt stays in the run record. The result cannot name it, because the step is skipped when the team is clear.
+result:
+  decision: decision
+  reply: reply
+  ticket: updated
+files:
+  - helpdesk.mjs
+  - triage.mjs

package/dist/packages/sdk/examples/support-triage/triage.mjs

@@ -0,0 +1,38 @@
+// The rules of support-triage.method: the routing rule and the ticket change. No requests; the tests import them.
+export const TEAM_THRESHOLD = 0.8;
+export const REFUND_THRESHOLD = 0.5;
+export const TEAMS = ['billing', 'technical', 'account'];
+export const PRIORITIES = ['low', 'normal', 'high', 'urgent'];
+
+const probability = value => Number.isFinite(value) && value >= 0 && value <= 1;
+
+/** Chooses the queue, priority, and tags from the three classifier results. */
+export function route(team, refund, urgency) {
+  const options = [...TEAMS, 'unclear'];
+  if (!options.includes(team?.choice) || !options.every(id => probability(team.probabilities?.[id])))
+    throw Error('Expected a team choice with one probability per option.');
+  if (typeof refund?.answer !== 'boolean' || !probability(refund.probability))
+    throw Error('Expected a yes or no (true or false) refund answer with the probability of yes.');
+  if (!PRIORITIES.includes(urgency?.level)) throw Error('Expected an urgency level.');
+
+  const chosen = team.probabilities[team.choice];
+  const base = {priority: urgency.level, tags: refund.probability >= REFUND_THRESHOLD ? ['refund_request'] : []};
+  const percent = `${Math.round(chosen * 100)}% probability`;
+  if (team.choice === 'unclear')
+    return {...base, queue: 'triage', needs_person: true, rule: 'team_unclear', reason: 'the classifier could not choose a team'};
+  if (chosen < TEAM_THRESHOLD)
+    return {...base, queue: 'triage', needs_person: true, rule: 'team_below_threshold', reason: `the classifier chose ${team.choice} with only ${percent}`};
+  return {...base, queue: team.choice, needs_person: false, rule: 'team_meets_threshold', reason: `the classifier chose ${team.choice} with ${percent}`};
+}
+
+/** The PATCH body. After a person's answer (teamOnly), the queue must be a team and no note is added. */
+export function change({queue, priority, tags, note}, teamOnly = false) {
+  const queues = teamOnly ? TEAMS : [...TEAMS, 'triage'];
+  const target = teamOnly ? String(queue ?? '').trim().toLowerCase() : queue;
+  if (!queues.includes(target)) throw Error(`The queue must be one of ${queues.join(', ')}, not "${queue}".`);
+  if (!PRIORITIES.includes(priority)) throw Error(`Unknown priority "${priority}".`);
+  if (!Array.isArray(tags) || tags.some(tag => typeof tag !== 'string')) throw Error('Expected a list of tags.');
+  if (teamOnly) return {queue: target, priority, tags};
+  if (typeof note !== 'string') throw Error('Expected the reply draft as the note.');
+  return {queue: target, priority, tags, internal_note: note};
+}

package/dist/packages/sdk/examples/support-triage/triage.test.mjs

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {execFile} from 'node:child_process';
+import {readFileSync} from 'node:fs';
+import {promisify} from 'node:util';
+import {fileURLToPath} from 'node:url';
+import {route, change} from './triage.mjs';
+import {startHelpdesk} from './fake-helpdesk.mjs';
+
+const team = (choice, p) => ({choice, probabilities: {billing: 0, technical: 0, account: 0, unclear: 0, [choice]: p}});
+const no = {answer: false, probability: 0.1};
+const normal = {level: 'normal', score: 1, probabilities: {low: 0, normal: 1, high: 0, urgent: 0}};
+
+test('a clear team at the threshold gets its own queue', () => {
+  const decision = route(team('billing', 0.8), no, normal);
+  assert.deepEqual(decision, {priority: 'normal', tags: [], queue: 'billing', needs_person: false, rule: 'team_meets_threshold', reason: 'the classifier chose billing with 80% probability'});
+});
+test('a team below the threshold goes to triage for a person', () => {
+  const decision = route(team('technical', 0.79), no, normal);
+  assert.equal(decision.queue, 'triage');
+  assert.equal(decision.needs_person, true);
+  assert.equal(decision.rule, 'team_below_threshold');
+});
+test('unclear always goes to triage, whatever its probability', () => {
+  const decision = route(team('unclear', 1), no, normal);
+  assert.equal(decision.rule, 'team_unclear');
+  assert.equal(decision.needs_person, true);
+});
+test('a refund probability of at least 50% adds the tag, and urgency sets the priority', () => {
+  const decision = route(team('billing', 0.95), {answer: true, probability: 0.5}, {...normal, level: 'urgent'});
+  assert.deepEqual(decision.tags, ['refund_request']);
+  assert.equal(decision.priority, 'urgent');
+  assert.deepEqual(route(team('billing', 0.95), {answer: false, probability: 0.49}, normal).tags, []);
+});
+test('invalid classifier results are refused', () => {
+  assert.throws(() => route({choice: 'sales', probabilities: {}}, no, normal));
+  assert.throws(() => route(team('billing', 0.9), {answer: 'yes', probability: 0.5}, normal));
+  assert.throws(() => route(team('billing', 0.9), no, {level: 'critical'}));
+});
+test('the move after a person accepts only a team and adds no note', () => {
+  assert.deepEqual(change({queue: ' Account ', priority: 'high', tags: []}, true), {queue: 'account', priority: 'high', tags: []});
+  assert.throws(() => change({queue: 'triage', priority: 'high', tags: []}, true), /must be one of billing, technical, account/);
+  assert.throws(() => change({queue: 'billing', priority: 'high', tags: []}), /reply draft/);
+});
+
+const run = promisify(execFile);
+const script = (name, input, args = [], token = 'test-token') => {
+  const child = run(process.execPath, [fileURLToPath(new URL(name, import.meta.url)), ...args], {env: {...process.env, HELPDESK_TOKEN: token}});
+  child.child.stdin.end(JSON.stringify(input));
+  return child.then(({stdout}) => JSON.parse(stdout));
+};
+
+test('the scripts read and change a ticket with the token, and a repeat sets the same values', async t => {
+  const tickets = JSON.parse(readFileSync(new URL('./sample-tickets.json', import.meta.url), 'utf8'));
+  const desk = await startHelpdesk({token: 'test-token', tickets});
+  t.after(() => desk.close());
+  const read = await script('read-ticket.mjs', {ticket_id: 'T-1042', helpdesk: desk.url});
+  assert.equal(read.ticket.subject, 'Charged twice this month');
+  const input = {ticket_id: 'T-1042', helpdesk: desk.url, queue: 'billing', priority: 'high', tags: ['refund_request'], note: 'Draft reply'};
+  const first = await script('set-ticket.mjs', input), second = await script('set-ticket.mjs', input);
+  assert.deepEqual(first, {updated: {id: 'T-1042', queue: 'billing', priority: 'high'}});
+  assert.deepEqual(second, first);
+  assert.deepEqual(desk.store.get('T-1042').notes, ['Draft reply']);
+  const moved = await script('set-ticket.mjs', {...input, queue: 'account'}, ['--team-only']);
+  assert.deepEqual(moved, {moved: {id: 'T-1042', queue: 'account', priority: 'high'}});
+  await assert.rejects(script('set-ticket.mjs', input, [], 'wrong-token'), /401/);
+  await assert.rejects(script('read-ticket.mjs', {ticket_id: 'T-9999', helpdesk: desk.url}), /404/);
+});

package/dist/packages/sdk/observers/mail.delivery/fetch.mjs

@@ -0,0 +1,87 @@
+// Read delivery reports about one message from an IMAP mailbox. Read-only: EXAMINE and BODY.PEEK.
+import tls from 'node:tls';
+import net from 'node:net';
+import { readFileSync } from 'node:fs';
+
+const input = JSON.parse(readFileSync(0, 'utf8'));
+const args = process.argv.slice(2);
+const name = args[args.indexOf('--connection') + 1];
+const connections = JSON.parse(process.env.METHOD_ENVIRONMENT ?? '{}');
+if (!name || !connections[name]) throw Error(`Observer connection ${name} is not configured`);
+const url = new URL(connections[name]);
+const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+if (url.protocol !== 'imaps:' && !(url.protocol === 'imap:' && local)) throw Error('Use an imaps:// mailbox URL');
+const password = process.env.MAIL_OBSERVER_PASSWORD;
+if (!password) throw Error('MAIL_OBSERVER_PASSWORD is not set');
+const mailbox = decodeURIComponent(url.pathname.slice(1) || 'INBOX');
+const port = Number(url.port || (url.protocol === 'imaps:' ? 993 : 143));
+const socket = url.protocol === 'imaps:' ? tls.connect({ host: url.hostname, port, servername: url.hostname }) : net.connect({ host: url.hostname, port });
+socket.setTimeout(30_000, () => socket.destroy(Error('IMAP timeout')));
+
+// A small reader for IMAP lines and {n} literals.
+let buffer = Buffer.alloc(0), waiting = null, failure;
+socket.on('data', chunk => { buffer = Buffer.concat([buffer, chunk]); waiting?.(); });
+socket.on('error', error => { failure = error; waiting?.(); });
+socket.on('close', () => { failure ??= Error('IMAP connection closed'); waiting?.(); });
+const more = () => new Promise((resolve, reject) => {
+  if (failure) return reject(failure);
+  waiting = () => { waiting = null; if (buffer.length) resolve(); else reject(failure); };
+});
+async function line() {
+  for (;;) {
+    const end = buffer.indexOf('\r\n');
+    if (end >= 0) {
+      let text = buffer.subarray(0, end).toString('utf8'); buffer = buffer.subarray(end + 2);
+      const literal = /\{(\d+)\}$/.exec(text);
+      if (literal) {
+        const size = Number(literal[1]);
+        while (buffer.length < size) await more();
+        text += '\n' + buffer.subarray(0, size).toString('utf8'); buffer = buffer.subarray(size);
+        text += await line();
+      }
+      return text;
+    }
+    await more();
+  }
+}
+let tag = 0;
+async function command(text) {
+  const id = `m${++tag}`;
+  socket.write(`${id} ${text}\r\n`);
+  const untagged = [];
+  for (;;) {
+    const response = await line();
+    if (response.startsWith(`${id} `)) {
+      if (!/^\S+ OK/i.test(response)) throw Error(`IMAP ${text.split(' ')[0]} failed: ${response.slice(id.length + 1, 200)}`);
+      return untagged;
+    }
+    untagged.push(response);
+  }
+}
+const quote = value => '"' + String(value).replace(/["\\]/g, m => '\\' + m) + '"';
+const since = new Date(Date.now() - 7 * 86_400_000);
+const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const sinceText = `${since.getUTCDate()}-${months[since.getUTCMonth()]}-${since.getUTCFullYear()}`;
+
+const greeting = await line();
+if (!/^\* (OK|PREAUTH)/i.test(greeting)) throw Error('Unexpected IMAP greeting');
+await command(`LOGIN ${quote(decodeURIComponent(url.username))} ${quote(password)}`);
+await command(`EXAMINE ${quote(mailbox)}`);
+const search = await command(`UID SEARCH SINCE ${sinceText} OR TEXT ${quote(input.token)} OR FROM "mailer-daemon" FROM "postmaster"`);
+const uids = search.flatMap(text => /^\* SEARCH/i.test(text) ? text.slice(8).trim().split(/\s+/).filter(Boolean) : []).slice(-50);
+const recipient = String(input.inputs?.to ?? '').toLowerCase();
+const observations = [];
+for (const uid of uids) {
+  const parts = (await command(`UID FETCH ${uid} (BODY.PEEK[HEADER.FIELDS (FROM SUBJECT DATE)] BODY.PEEK[TEXT]<0.65536>)`)).join('\n');
+  const header = key => (new RegExp(`^${key}:\\s*(.*)$`, 'im').exec(parts)?.[1] ?? '').trim();
+  const lower = parts.toLowerCase();
+  // Keep only what the judge needs; never the message text.
+  observations.push({ source: 'imap', ref: `${mailbox}/uid:${uid}`, data: {
+    from: header('From'), subject: header('Subject'), date: header('Date'),
+    action: (/^action:\s*(\w+)/im.exec(parts)?.[1] ?? '').toLowerCase(), status: /^status:\s*([245]\.\d{1,3}\.\d{1,3})/im.exec(parts)?.[1] ?? '',
+    mentions_token: lower.includes(String(input.token).toLowerCase()), mentions_recipient: !!recipient && lower.includes(recipient),
+  } });
+}
+await command('LOGOUT').catch(() => {});
+socket.end();
+console.log(JSON.stringify({ observations }));

package/dist/packages/sdk/observers/mail.delivery/fixtures/bounce-by-recipient.json

@@ -0,0 +1 @@
+{"inputs":{"to":"dana@vendor.example"},"observations":[{"source":"imap","ref":"INBOX/uid:8","data":{"from":"postmaster@vendor.example","subject":"Undeliverable: Morning summary","date":"","action":"","status":"","mentions_token":false,"mentions_recipient":true}}],"expect":"contradicted"}

package/dist/packages/sdk/observers/mail.delivery/fixtures/bounce.json

@@ -0,0 +1 @@
+{"inputs":{"to":"dana@vendor.example"},"observations":[{"source":"imap","ref":"INBOX/uid:7","data":{"from":"Mail Delivery Subsystem <mailer-daemon@googlemail.com>","subject":"Delivery Status Notification (Failure)","date":"","action":"failed","status":"5.1.1","mentions_token":true,"mentions_recipient":true}}],"expect":"contradicted"}

package/dist/packages/sdk/observers/mail.delivery/fixtures/delayed.json

@@ -0,0 +1 @@
+{"inputs":{"to":"dana@vendor.example"},"observations":[{"source":"imap","ref":"INBOX/uid:9","data":{"from":"Mail Delivery Subsystem <mailer-daemon@googlemail.com>","subject":"Delivery Status Notification (Delay)","date":"","action":"delayed","status":"4.4.7","mentions_token":true,"mentions_recipient":true}}],"expect":"no_evidence"}

package/dist/packages/sdk/observers/mail.delivery/fixtures/delivered.json

@@ -0,0 +1 @@
+{"inputs":{"to":"dana@vendor.example"},"observations":[{"source":"imap","ref":"INBOX/uid:11","data":{"from":"postmaster@sender.example","subject":"Delivery Status Notification (Success)","date":"","action":"delivered","status":"2.0.0","mentions_token":true,"mentions_recipient":true}}],"expect":"confirmed"}

package/dist/packages/sdk/observers/mail.delivery/fixtures/empty.json

@@ -0,0 +1 @@
+{"inputs":{"to":"dana@vendor.example"},"observations":[],"expect":"no_evidence"}

package/dist/packages/sdk/observers/mail.delivery/fixtures/other-message.json

@@ -0,0 +1 @@
+{"inputs":{"to":"dana@vendor.example"},"observations":[{"source":"imap","ref":"INBOX/uid:10","data":{"from":"Mail Delivery Subsystem <mailer-daemon@googlemail.com>","subject":"Delivery Status Notification (Failure)","date":"","action":"failed","status":"5.1.1","mentions_token":false,"mentions_recipient":false}}],"expect":"no_evidence"}

package/dist/packages/sdk/observers/mail.delivery/judge.mjs

@@ -0,0 +1,13 @@
+// Decide what the delivery reports show. Deterministic: no network, no model.
+import { readFileSync } from 'node:fs';
+const { token, observations } = JSON.parse(readFileSync(0, 'utf8'));
+const daemon = /mailer-daemon|postmaster|mail delivery (sub)?system/i;
+const failedSubject = /undeliver|delivery status notification \(failure\)|mail delivery failed|returned mail|delivery has failed|could not be delivered|couldn't be delivered|not delivered|delivery failure/i;
+// A report is about this message when it names its token, or names the recipient and comes from a mail system.
+const relevant = observations.filter(o => o.data?.mentions_token || (o.data?.mentions_recipient && daemon.test(o.data?.from ?? '')));
+const failed = relevant.find(o => o.data.action === 'failed' || /^5\./.test(o.data.status) || (o.data.action !== 'delayed' && !/^4\./.test(o.data.status) && failedSubject.test(o.data.subject ?? '')));
+const delivered = relevant.find(o => o.data.action === 'delivered' && o.data.mentions_token);
+const out = failed ? { verdict: 'contradicted', reason: `Delivery failed${failed.data.status ? ` (${failed.data.status})` : ''}: ${failed.data.subject}`, evidence: [failed.ref] }
+  : delivered ? { verdict: 'confirmed', reason: 'A delivery report names this message as delivered.', evidence: [delivered.ref] }
+  : { verdict: 'no_evidence', reason: relevant.length ? `Only delay reports so far (${relevant.length}).` : `No delivery report names ${token} or the recipient.`, evidence: relevant.map(o => o.ref) };
+console.log(JSON.stringify(out));

package/dist/packages/sdk/observers/mail.delivery/observer.json

@@ -0,0 +1,14 @@
+{
+  "description": "Searches the mailbox that receives bounces for delivery reports about one sent message. Uses IMAP EXAMINE and BODY.PEEK, so it does not change the mailbox or mark mail as read.",
+  "connection": { "name": "bounce_mailbox", "type": "service", "description": "IMAP mailbox that receives delivery reports for the sending address, as imaps://USER@HOST:993/INBOX. Used only to read." },
+  "needs": "A runtime profile mail_observer whose env lists MAIL_OBSERVER_PASSWORD (an app password for the bounce mailbox), and the bounce_mailbox connection URL in runtime.json.",
+  "inputs": [{ "alias": "to", "description": "The recipient address of the sent message, for example inputs.ap_lead." }],
+  "effect": {
+    "intent": "The recipient's mail server accepts the message and does not return it.",
+    "observe_runtime": "mail_observer",
+    "args": ["--connection", "{connection}"],
+    "schedule": { "first": "2m", "then": ["15m", "1h", "6h", "1d", "2d"], "horizon": "5d" },
+    "confirm": "unrefuted_at_horizon"
+  },
+  "setup": "In runtime.json, add runtimes.mail_observer = {\"command\": \"node\", \"version\": \"22\", \"env\": [\"MAIL_OBSERVER_PASSWORD\"]} and environment.bounce_mailbox = \"imaps://USER@HOST:993/INBOX\". Set MAIL_OBSERVER_PASSWORD wherever method run and method observe run. Use an app password with read access only where the provider allows it. The send step must put METHOD_OPERATION_ID in the message, for example Message-ID: <TOKEN@your-domain>; without it the observer can match bounces only by recipient address. Schedule method observe --pending, for example hourly, so bounces that arrive after the run reach it."
+}