From ef7a296f06d5053c919af52956550a1d04f0f36d Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Wed, 4 Nov 2026 07:34:49 -0700 Subject: [PATCH 1/4] feat(skills): ship the reply-adapter skills in the package and install them from it The five reply-adapter skills now live in this package under skills/, at the CLI's own version. install and update copy them from the installed package into every detected assistant, Claude Code and Codex included, with no network and no git. The old reply-adapter plugin an earlier version installed is removed through the host's own CLI once the copy is in place. list and remove still act on what earlier versions installed, under the old pack names too; asking install or update for those names is a usage error naming where they now ship. --- .gitattributes | 2 + package.json | 1 + scripts/smoke-hosts.mjs | 82 +- skills/reply-adapter/reply-api/SKILL.md | 231 ++ skills/reply-adapter/reply-auth/SKILL.md | 111 + skills/reply-adapter/reply-cli/SKILL.md | 178 + skills/reply-adapter/reply-mcp/SKILL.md | 115 + .../reply-operations-mapping/SKILL.md | 469 +++ .../reply-operations-mapping/fulfilment.yaml | 2986 +++++++++++++++++ .../references/fulfilment.md | 872 +++++ .../references/mapping-01-discovery.md | 35 + .../references/mapping-02-contacts.md | 46 + .../references/mapping-03-audiences.md | 39 + .../references/mapping-04-import.md | 28 + .../references/mapping-05-campaigns.md | 49 + .../references/mapping-06-steps.md | 41 + .../references/mapping-07-messages.md | 28 + .../references/mapping-08-enrollment.md | 30 + .../references/mapping-09-conversations.md | 32 + .../references/mapping-10-tasks.md | 35 + .../references/mapping-11-meetings.md | 40 + .../references/mapping-12-signals.md | 33 + .../references/mapping-13-inbound.md | 34 + .../references/mapping-14-privacy.md | 46 + .../references/mapping-15-sending.md | 57 + .../references/mapping-16-social.md | 36 + .../references/mapping-17-oversight.md | 55 + .../references/mapping-18-team.md | 38 + .../references/mapping-19-accounts.md | 35 + .../references/mapping-20-measurement.md | 33 + .../references/mapping-21-introspection.md | 38 + src/__tests__/skills/adapter-flat.test.ts | 283 +- src/__tests__/skills/adapter-native.test.ts | 376 --- src/__tests__/skills/hosts.test.ts | 51 +- src/__tests__/skills/journal.test.ts | 16 +- src/__tests__/skills/orchestrate.test.ts | 196 +- src/__tests__/skills/package-pack.test.ts | 343 ++ src/__tests__/skills/packs.test.ts | 169 +- src/__tests__/skills/plugins.test.ts | 109 + src/__tests__/skills/report.test.ts | 47 +- src/commands/skills.ts | 27 +- src/skills/adapter-flat.ts | 259 +- src/skills/adapter-native.ts | 422 --- src/skills/detect.ts | 10 +- src/skills/hosts.ts | 38 +- src/skills/journal.ts | 11 +- src/skills/orchestrate.ts | 201 +- src/skills/packs.ts | 208 +- src/skills/plugins.ts | 79 + src/skills/report.ts | 90 +- src/skills/types.ts | 91 +- 51 files changed, 7039 insertions(+), 1842 deletions(-) create mode 100644 .gitattributes create mode 100644 skills/reply-adapter/reply-api/SKILL.md create mode 100644 skills/reply-adapter/reply-auth/SKILL.md create mode 100644 skills/reply-adapter/reply-cli/SKILL.md create mode 100644 skills/reply-adapter/reply-mcp/SKILL.md create mode 100644 skills/reply-adapter/reply-operations-mapping/SKILL.md create mode 100644 skills/reply-adapter/reply-operations-mapping/fulfilment.yaml create mode 100644 skills/reply-adapter/reply-operations-mapping/references/fulfilment.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-01-discovery.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-02-contacts.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-03-audiences.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-04-import.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-05-campaigns.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-06-steps.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-07-messages.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-08-enrollment.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-09-conversations.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-10-tasks.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-11-meetings.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-12-signals.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-13-inbound.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-14-privacy.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-15-sending.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-16-social.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-17-oversight.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-18-team.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-19-accounts.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-20-measurement.md create mode 100644 skills/reply-adapter/reply-operations-mapping/references/mapping-21-introspection.md delete mode 100644 src/__tests__/skills/adapter-native.test.ts create mode 100644 src/__tests__/skills/package-pack.test.ts create mode 100644 src/__tests__/skills/plugins.test.ts delete mode 100644 src/skills/adapter-native.ts create mode 100644 src/skills/plugins.ts diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..e75cd1b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# The skills ship in the package as they are written: the same bytes from every checkout. +skills/** text eol=lf diff --git a/package.json b/package.json index 8c81044..4c175b7 100644 --- a/package.json +++ b/package.json @@ -30,6 +30,7 @@ }, "files": [ "dist", + "skills", "README.md" ], "devDependencies": { diff --git a/scripts/smoke-hosts.mjs b/scripts/smoke-hosts.mjs index 85e5052..ebfed20 100644 --- a/scripts/smoke-hosts.mjs +++ b/scripts/smoke-hosts.mjs @@ -1,17 +1,17 @@ // Verifies `reply skills install` end to end, against real and simulated assistants. // -// Not part of `npm test`: it clones from GitHub, and exercising a native host for -// real needs that assistant installed on the machine. It is safe to run on a -// working machine because: -// - Native hosts (Claude Code, Codex) are pointed at throwaway config directories -// via CLAUDE_CONFIG_DIR and CODEX_HOME. They are only *genuinely* exercised -// (real binary resolved from the real PATH) when really installed — otherwise -// they still appear in the report with status 'skipped'. -// - Flat-directory hosts (Cursor, Gemini CLI, GitHub Copilot) are always +// Not part of `npm test`: reaching the plugin CLI of Claude Code or Codex for +// real needs that assistant installed on the machine. Every host receives the +// skills as files copied from this package. It is safe to run on a working +// machine because: +// - Claude Code and Codex are pointed at throwaway config directories via +// CLAUDE_CONFIG_DIR and CODEX_HOME. Their plugin CLI, asked only about the +// plugins an earlier version installed, is reached only when the real binary +// resolves from the real PATH; without it they are reported 'skipped'. +// - The other hosts (Cursor, Antigravity, GitHub Copilot, Windsurf) are always // *simulated* inside the sandbox below, regardless of what is really on this -// machine. That is deliberate: it is the only way the flat-directory install -// path gets exercised at all, on any machine. Do not read a flat host's 'ok' -// status here as evidence that assistant is really installed. +// machine. Do not read their 'ok' status here as evidence that assistant is +// really installed. // - Both rely on HOME/USERPROFILE being redirected to the sandbox. That is not // assumed: before anything mutating runs, a child process given the exact same // env is asked what os.homedir() resolves to, and the run aborts without @@ -98,6 +98,7 @@ const real_reply_config_dir = ()=>{ const snapshot_state = ()=>{ const real_home = os.homedir(); const paths_to_check = [ + path.join(real_home, '.claude', 'skills'), path.join(real_home, '.copilot'), path.join(real_home, '.copilot', 'skills'), path.join(real_home, '.cursor'), @@ -241,19 +242,17 @@ try { const installed = JSON.parse(cli('skills', 'install', '--json')); console.log(`hosts: ${installed.hosts.map(h=>`${h.host}=${h.status}`).join(' ') || '(none detected)'}`); - // Flat hosts are always simulated (see header), so `installed.hosts` - // is never actually empty on any machine with git on PATH — the - // brief's original "no assistant at all" exit is dead code below. - // What is real and worth reporting is whether a *native* host (the - // only kind that is only exercised when genuinely installed) was - // actually present: status 'skipped' means its config directory - // marker existed but the real binary could not be resolved from - // the real PATH, i.e. it is not really installed here. - const native_ids = new Set(['claude-code', 'codex']); - const native_present = installed.hosts.some(h=>native_ids.has(h.host) && h.status !== 'skipped'); - console.log(native_present - ? '✓ at least one native assistant (Claude Code/Codex) is really installed and was exercised for real' - : 'ℹ no native assistant (Claude Code, Codex) is really installed on this machine — only the always-simulated flat hosts were exercised'); + // The simulated hosts (see header) mean `installed.hosts` is never + // empty in practice. What is real and worth reporting is whether + // Claude Code or Codex, detected only when the real binary resolves, + // was actually present: status 'skipped' means its config directory + // marker existed but the binary could not be resolved from the real + // PATH, i.e. it is not really installed here. + const cli_hosts = new Set(['claude-code', 'codex']); + const cli_present = installed.hosts.some(h=>cli_hosts.has(h.host) && h.status !== 'skipped'); + console.log(cli_present + ? '✓ Claude Code or Codex is really installed and was exercised for real' + : 'ℹ neither Claude Code nor Codex is really installed on this machine — only the simulated hosts were exercised'); if (!installed.hosts.length) { @@ -267,9 +266,9 @@ try { { fail('no host reported ok'); } - if (installed.resolved.join(',') !== 'ai-sdr-core,reply-adapter,agentic-runtime') + if (installed.resolved.join(',') !== 'reply-adapter') { - fail(`unexpected resolve order: ${installed.resolved.join(',')}`); + fail(`unexpected packs: ${installed.resolved.join(',')}`); } // Idempotency: the second run must change nothing. @@ -280,20 +279,27 @@ try { fail(`re-install was not idempotent: ${actions.join(',')}`); } - // Selective install pulls the core. - cli('skills', 'remove', '--json'); - const selective = JSON.parse(cli('skills', 'install', 'adapter', '--json')); - if (selective.resolved.join(',') !== 'ai-sdr-core,reply-adapter') - { - fail(`selective install did not pull the core: ${selective.resolved.join(',')}`); + // A pack this CLI no longer ships is refused as a usage error. + try { + cli('skills', 'install', 'core', '--json'); + fail('installing a pack this CLI no longer ships was allowed'); + } catch (e) { + if (e.status === 2) + { + console.log('✓ a pack this CLI no longer ships is refused with exit 2'); + } + else + { + fail(`installing a pack this CLI no longer ships exited ${e.status}, not 2`); + } } - // Removing the core alone must be refused. - try { - cli('skills', 'remove', 'core', '--json'); - fail('removing the core while the adapter is installed was allowed'); - } catch { - console.log('✓ removing a needed dependency is refused'); + // Remove with no pack takes everything away again. + const removed = JSON.parse(cli('skills', 'remove', '--json')); + const left = removed.hosts.flatMap(h=>(h.packs ?? []).filter(p=>p.action !== 'removed')); + if (left.length) + { + fail(`remove left packs behind: ${left.map(p=>`${p.name}=${p.action}`).join(',')}`); } } } diff --git a/skills/reply-adapter/reply-api/SKILL.md b/skills/reply-adapter/reply-api/SKILL.md new file mode 100644 index 0000000..ca68e30 --- /dev/null +++ b/skills/reply-adapter/reply-api/SKILL.md @@ -0,0 +1,231 @@ +--- +name: reply-api +description: > + Work with the Reply.io API v3 correctly: discover endpoints through the machine-readable + docs, respect scopes and rate limits, handle problem+json errors and background jobs. + Use before calling any non-trivial v3 endpoint, when choosing an endpoint for a task, + or when an API call fails and needs interpretation. +metadata: + version: 1.5.0 + pack: reply-adapter + category: execution + maturity: reviewed + status: active + owner: skills-maintainers + tags: [api, docs, errors, rate-limits] + tools: [reply-cli, reply-mcp] + api: [introduction, authentication, rate-limits] + relations: + depends-on: [reply-cli] + recommends: [reply-auth, reply-operations-mapping] +--- + +# Working with Reply API v3 + +## Purpose + +API v3 (`https://api.reply.io/v3`) is the full execution surface of Reply — contacts, sequences, +inbox, channels, tasks, schedules, reports, webhooks and the AI-SDR cluster. The docs are built +for agents: this skill teaches the discovery-first workflow that avoids invented endpoints and +malformed bodies. + +## When to use / when NOT to use + +- Use whenever a task needs an endpoint you haven't verified in this session, or an error needs + interpreting. +- Do NOT guess endpoint paths or body shapes from memory — verify against the docs first. + +## Prerequisites + +A working credential (`reply auth whoami` succeeds) with the scopes the target endpoints require. + +## Execution guidance + +### Discovery-first workflow (always) + +1. **Fetch the index once per session:** `https://docs.reply.io/llms.txt` — every endpoint with + its doc URL and required scope, one line each. +2. **Fetch the endpoint's doc page as raw markdown** by requesting its URL with the `.md` suffix + (e.g. `https://docs.reply.io/api-reference/sequences/list-all-sequences.md`) — exact path, + parameters, body schema, response examples. +3. **Call it:** `reply api `. + +Known-stable anchors you may use without re-checking: `GET /v3/whoami` (identity; no scope), +`GET /v3/whoami/team-users` (accessible teams), `GET /v3/background-jobs/{id}`, +`GET /v3/sequences/{id}/stats` and `GET /v3/sequences/stats` (stricter rate limits). +The full OpenAPI 3.1 spec exists at `https://docs.reply.io/api-reference/bundled.yaml` — prefer +per-page `.md` fetches; the spec is large. + +### Conventions + +- REST, plural nouns: `GET` read, `POST` create, `PATCH` update, `DELETE` remove; JSON bodies. +- **Errors** are RFC 9457 `application/problem+json` with a stable `code` slug + (`.`, e.g. `webHook.invalidEvent`). Validation 400s add an `errors[]` array + with JSON Pointers to the offending fields — read them, fix, retry once. +- **Async:** long operations return `202 Accepted` + `Location: /v3/background-jobs/{id}`. + Poll that endpoint until it completes; report the job result, not the 202. +- **Change feed:** `GET /v3/inbox/threads/changes` lists the inbox threads that changed, oldest + first, a page at a time from an opaque `cursor` or a `since` moment, and holds the last 30 days + only; from reply-cli 0.17.0 it is `reply inbox changes`. Keep the cursor it hands back, even on an + empty page, and pass it unchanged. A cursor or moment older than the window is refused (CLI code + `inbox.cursor_expired`), and so is a cursor the feed never issued or one ahead of its clock (CLI + code `inbox.cursor_refused`): read again from a moment inside the window. An account whose Reply + has no feed yet answers a bare 404 — page through the inbox threads instead. +- **Rate limits:** 100 req/min and 3000 req/hour per user; reporting and sequence-stats endpoints + are stricter. On 429 the CLI already retried honoring `Retry-After` — if it still fails, wait + and reduce concurrency (sequential calls for bulk work). +- **Direct sends** (from reply-cli 0.17.0): `--send-after ` takes a moment with its offset + and sends it as UTC, and Reply holds the send until then. `--idempotency-key ` goes as the + `Idempotency-Key` header: the same request repeated under it answers the send Reply took rather + than sending again; `idempotency_key.in_use` says the first send under it is still being made + (wait and repeat), and `idempotency_key.reused` that it was taken for another request, whose send + the error's `details` names. The answer carries the send's `reference` and `state`, and its + `send_after` where one was given; take each field only when the answer gives it, and read a + `send_after` of null as no moment given. `reply direct-send get ` reads the send and + `reply direct-send cancel ` cancels one still held. Nothing lists the pending sends: a + harness that keeps the reference reads and cancels by it. + - **State:** `sent` means it went. `failed` and `cancelled` are final: Reply will not send it, + and neither a repeat under the key nor a read changes that. Any other state — `queued`, + `sending`, `waitingForSchedule`, or one this skill does not name — means Reply took the send + and it has not gone yet. Every such send can still be cancelled except a `sending` one, which + Reply is already sending. + - **Text:** where the answer carries `rendered_subject` and `rendered_body`, they are the + message as sent — the subject rendered, the body rendered with the account's signature and + the tracking applied. Reply keeps no other rendered copy. + - **Templates:** the text of an email, a LinkedIn message and an InMail is read as a template + in Reply's own syntax and filled in for the contact. A send Reply makes within the call is + filled in before anything goes, and one Reply cannot fill is refused with nothing sent, under a code reply-cli + gives it: on an email, from reply-cli 0.17.2, a code of the contact's for variables missing, whose + `details.missing_variables` lists the names, or one for a rendering that failed; on LinkedIn, + `linkedin.missing_variables`. A send + held for a later moment or a schedule, or one that goes now which Reply queues behind the + account's other sends, is filled in when it goes, so a name Reply cannot fill + then is not refused at the send: the send ends `failed`. On an email its `failure_code` is + `contact.missingVariables`, with the names under `missing_variables`, or `contact.renderingFailed`, + as reply-cli 0.17.2 prints them; on LinkedIn it carries no `failure_code`, and Reply's sentence is + its `failure_reason`. On LinkedIn Reply fills the sending account's + `SendingLinkedIn.SenderFirstName` and `SendingLinkedIn.SenderName`, and has no variable for + its last name or its address; the text goes as written, and Reply converts it from HTML to text + after filling it in. A LinkedIn message's or InMail's length is the length after the text is filled in (`linkedin.message_too_long`). A connection request's note + and a voice message's script are never filled in: either holding `{{` is refused, + `linkedin.missing_variables`, so write them as final text. + - **Read and cancel:** `reply direct-send get ` answers the send's `state`, `channel` + and `send_after`, and, as they apply, `sent_at` and `message_id` once it went, `failure_reason` + where it failed and `cancelled_at` where it was cancelled. `reply direct-send cancel + ` answers the same record, cancelled. A cancel of a send already cancelled answers + it again, so a cancel whose answer was lost is safe to repeat. A send that went, or that Reply + is already sending, answers `direct_send.already_sent`, and one that failed + `direct_send.already_failed`: nothing changed, so report it as gone or failed, never as + cancelled. `direct_send.not_found` says Reply holds no send under the reference, and + `direct_send.not_owned` that it holds one for an account this one is not; neither is repeated. + A failed send carries Reply's `failure_code`: `directSend.dispatchWindowMissed` is `failed` - + "Nothing went out; sending again is safe" - while `directSend.dispatchInterrupted` is to be + read as `unknown`, not `failed`: it may have gone out - "check before sending again" - so read + the person's thread before any new send. + - **A lost answer:** where an earlier try returned a `reference`, read it first with `reply + direct-send get ` (from reply-cli 0.17.0), and let its state decide; repeat only + when the read says nothing of the send. Reply keeps a key for a day, so a repeat goes under + the same key only within 23 hours of the first try. Past that, or where the account's Reply + has no direct-send route (a bare 404 on the read), the key no longer settles a repeat: send + nothing, and leave whether the first try went to a person to check at Reply. Only a lost + answer is repeated: a timeout, a dropped connection, a CLI that died, an exit 0 whose answer + was cut off or could not be read, or a 5xx. A send Reply answered with a failure, a 4xx, is + never repeated, under the key or otherwise: Reply keeps no key for it, so a repeat would be a + new send. `idempotency_key.in_use` and a rate limit are the two 4xx that sent nothing, and + are waited out as their own rows say. +- **Schedules** are the account's sending windows: a time zone — the schedule's own, or the + recipient's where `use_recipient_time_zone` is true — the active ranges of each weekday, whether + holidays are skipped, and the windows of a sequence's later steps. `reply schedule list` (from + reply-cli 0.16.0) lists them with their `id`. Reading one, creating one and deleting one go + through `reply api`, on the pages of the `schedules` group in `llms.txt`: reply-cli 0.17.0 has no + command of its own for them. A schedule is shared, so a change or a delete reaches every sequence + that uses it. Its `reply_status` is Reply's word for the first use it finds — a campaign template, + a sequence of yours or a team member's, or a default — and a delete is only for one nothing uses. + - **On a direct send** (from reply-cli 0.17.0), `--schedule-id ` names a schedule from + `reply schedule list`, on email only: Reply refuses it on every LinkedIn route. Reply then + holds the send until the schedule's first opening at or after `--send-after`, or after now + where no moment is given. The answer's `state` says Reply holds the send, and it names no + moment: Reply estimates one only where the schedule opens within 30 days, and reply-cli does + not pass the estimate. + - **A schedule or a moment.** A moment is one exact instant somebody chose. A schedule serves + better where the right time is the person's working hours in their own time zone, where + holidays should be skipped, or where nobody will be awake to time each send: Reply works out + the next opening for each person. With both, the send goes at the schedule's first opening at + or after the moment. + - **A provider object.** Where the runtime carrying the work passes the reserved `provider` key + inside the operation's arguments, `args.provider`, `message.send` by email reads + `{"schedule_id": ""}` and nothing else: the schedule's `id` from `reply schedule list`, + written as a string of its digits. Any other shape or another key is refused before anything is + sent, with a message that names the shape; write the object in that shape and ask again. + Reply refuses a schedule on every LinkedIn direct send in this version (scheduleId is not + supported for LinkedIn sends in this version, a 400 on each LinkedIn route), so a schedule on + a LinkedIn message is refused before any call. + +### Endpoint availability (GA / Beta / Coming soon) + +The docs mark endpoints as **Beta** (shape may change) or **Coming soon** (not callable yet) — +much of the AI-SDR cluster (autopilot, pending approvals, enrichment, Live Data) carries such +marks. Check the endpoint's doc page; if it's Coming soon, say so honestly — never improvise a +replacement with unrelated endpoints. + +Not every account's Reply has every route yet. A bare 404 — no `code` of Reply's own — on a +direct send, `direct-send get` or `direct-send cancel` means the account's Reply does not have the +route, not that an identifier is wrong; from reply-cli 0.17.0 the CLI passes it through as +`reply.refused` with status 404 and no Reply code. Say the capability is not there yet; never +retry it as a stale identifier. + +## Validation + +For writes: re-read the entity (`GET`) and verify the change. For bulk/async: poll the background +job to terminal state and reconcile counts (created/updated/skipped/failed). + +## Reporting + +Record endpoint paths used, entity IDs created/modified, background-job IDs and final counts. + +## Failure modes + +| Signal | Meaning | Action | +|---|---|---| +| 400 + `errors[]` | invalid body/params | fix per JSON Pointer, retry once | +| 401 empty body | bad/expired credential | fix auth (`reply auth login`) | +| 403 `insufficient_scope` | key lacks the endpoint's scope | tell the user which scope is missing; don't retry | +| 403/401 `TEAM_REQUIRED`·`TEAM_NOT_ACCESSIBLE`·`USER_REQUIRED`·`USER_NOT_FOUND` | team/user resolution | see reply-auth skill | +| 404 | wrong/stale ID | re-list the entity, re-resolve the ID — don't invent IDs | +| 429 | rate limit | respect `Retry-After`; go sequential | +| 5xx | transient | already retried; wait, retry once, then report the API may be down | + +## Safety + +Read endpoints are safe. Treat every POST/PATCH/DELETE as a live mutation subject to the calling +skill's confirmation rules — especially anything that sends messages or starts sequences. + +## Related skills + +- `reply-cli` — the execution command (`reply api`). +- `reply-auth` — scopes model and team/org resolution. + +## Changelog + +- 1.5.0 (2026-10-30): *Conventions* says how a direct send's text is filled in as a template: + on an email, a LinkedIn message and an InMail; a send that goes now refused by reply-cli 0.17.2's + three codes, with the names Reply lists; a held send filled in when it goes and failed then; the + LinkedIn sender's two names, the text as written and the length after it is filled in; and a + connection request's note and a voice message's script never filled in. +- 1.4.0 (2026-10-29): *Conventions* names the schedules: `reply schedule list` (from reply-cli + 0.16.0), reading, creating and deleting one through `reply api`, and that a schedule is shared; + `--schedule-id` on a direct send by email (from reply-cli 0.17.0), the first opening at or after + the moment where both are given, when a schedule serves better than a moment, and the provider + object a `message.send` reads where the runtime keeps one. +- 1.3.0 (2026-10-29): *Conventions* names the direct sends' `--send-after` and `--idempotency-key`, + the two `idempotency_key.*` codes and `reply direct-send get` and `cancel`, from reply-cli + 0.17.0, and what a send's answer says: its fields only when given, its state (`sent`, final + `failed` and `cancelled`, anything else held), its rendered text as sent, what a read and a + cancel answer, a failed send's two codes, a cancel's two refusals and a second cancel a + success, and a lost answer read + back by reference first and repeated under the key within 23 hours; *Endpoint availability* + says what a bare 404 on those routes means. +- 1.2.0 (2026-10-29): the inbox change feed, `GET /v3/inbox/threads/changes`, and its window. +- 1.1.0 (2026-07-30): moved into the `reply-adapter` pack; category `technical` → `execution`; + `auth-and-keys` renamed `reply-auth`. +- 1.0.0 (2026-07-27): initial version against docs.reply.io (v3, July 2026). diff --git a/skills/reply-adapter/reply-auth/SKILL.md b/skills/reply-adapter/reply-auth/SKILL.md new file mode 100644 index 0000000..fb1a0fe --- /dev/null +++ b/skills/reply-adapter/reply-auth/SKILL.md @@ -0,0 +1,111 @@ +--- +name: reply-auth +description: > + Reply.io credentials in depth: API key types (personal, Team, Organization), the scopes + model (domain:verb), acting-user headers, and team/organization resolution errors + (TEAM_REQUIRED, USER_REQUIRED and friends). Use when choosing or creating a key for an + agent, resolving 401/403 auth errors, or working across multiple teams. +metadata: + version: 1.1.0 + pack: reply-adapter + category: execution + maturity: reviewed + status: active + owner: skills-maintainers + tags: [auth, keys, scopes, teams, security] + tools: [reply-cli, reply-mcp] + api: [authentication, user-account] + relations: + recommends: [reply-cli, reply-mcp, approval-boundaries] +--- + +# Auth, keys & scopes + +## Purpose + +Every toolkit surface authenticates with the same `Authorization: Bearer` header — an API key or +an OAuth token. What differs is the key's **type** (who it can act as) and its **scopes** (what it +may call). Getting these right is the difference between a safely-bounded agent and a 403 loop. + +## When to use / when NOT to use + +- Use when provisioning an agent's credential, debugging 401/403, or acting across teams/orgs. +- For interactive personal use, `reply auth login` (OAuth) is simpler — see `reply-cli`. + +## Prerequisites + +Access to Reply → **Settings → API Key** (personal), or owner/admin rights for Team/Org keys. + +## Execution guidance + +### Key types + +| Type | Acts as | Notes | +|---|---|---| +| Personal | you | scoped; the right choice for agents and MCP | +| Team | any user in one workspace | owner-created; add `X-User-Id` or `X-User-Email` to impersonate; defaults to the owner | +| Organization | any user in any org workspace | **always** requires an acting user: `X-USER-ID`, or `X-User-Email` + `X-TEAM-ID`; multiple keys, named/rotated independently | + +Resolved-user permissions always apply — no key grants more than the user it acts as. +MCP accepts personal keys/OAuth only (no Team/Org keys). + +### Scopes (`domain:verb`) + +Verbs: `read`, `write` (create/update/delete), `operate` (runtime actions: push to sequence, +start/pause, reply). `write` and `operate` each satisfy `read`; they do NOT include each other. +Wildcards: `contacts:*` (any verb in a domain), `*:*` (everything). Domains: settings, contacts, +sequences, channels, inbox, tasks, reporting (read-only), webhooks, ai-sdr, other. +Every endpoint's doc page states its minimal scope; llms.txt shows it per line. + +**Least privilege for agents:** grant only what the workflow needs, e.g. inbox triage = +`inbox:read` + `inbox:operate`; analytics = `reporting:read` + `sequences:read`. A 403 with +`insufficient_scope` mid-workflow means the key is missing one of these — the response never +lists granted scopes, so check the key in Settings. + +### Team / organization resolution + +A credential that can access more than one team must resolve to exactly one before team-scoped +work runs. Codes you will meet (problem+json): + +| Code | Status | Meaning | Fix | +|---|---|---|---| +| `TEAM_REQUIRED` | 403 | multiple teams, none specified; payload lists accessible teams | pin one: `reply team use ` / `--team-id` / `X-TEAM-ID` | +| `TEAM_NOT_ACCESSIBLE` | 403 | specified team isn't yours | pick from `reply team list` | +| `USER_REQUIRED` | 403 | org key without acting user | pass `--user-id` or `--user-email` (+ team id) | +| `USER_NOT_FOUND` | 401 | acting user doesn't exist | verify the id/email | + +Plain invalid/expired key = **empty-body 401** with `WWW-Authenticate: Bearer` (no JSON) — that's +an auth failure, not a resolution failure. + +## Validation + +`reply api /v3/whoami` confirms identity; `reply api /v3/whoami/team-users` lists teams the +credential can act in. Verify both before long workflows. + +## Reporting + +When a workflow required scope or team changes, record which key/scopes/team were used — future +runs depend on it. + +## Failure modes + +Covered above; one addition — key revoked mid-run: every call turns empty-401. Stop, tell the +user, never retry in a loop. + +## Safety + +- Never commit keys, print them in logs, or store them in the workspace; the CLI store and host + secret managers are the only homes. Rotate on any suspicion of exposure. +- For unattended agents (daemon, schedulers) prefer narrowly-scoped personal keys and treat + `operate` scopes as the dangerous tier — they send real messages. + +## Related skills + +- `reply-cli` — where credentials live locally and how precedence works. +- `reply-mcp` — auth specifics of the MCP connection. + +## Changelog + +- 1.1.0 (2026-07-30): renamed `auth-and-keys` → `reply-auth` (the knowledge is Reply-specific, + so it carries the provider prefix); moved into the `reply-adapter` pack. +- 1.0.0 (2026-07-27): initial version per docs.reply.io authentication guide. diff --git a/skills/reply-adapter/reply-cli/SKILL.md b/skills/reply-adapter/reply-cli/SKILL.md new file mode 100644 index 0000000..25814d9 --- /dev/null +++ b/skills/reply-adapter/reply-cli/SKILL.md @@ -0,0 +1,178 @@ +--- +name: reply-cli +description: > + Operate Reply.io from the terminal with the reply CLI: sign in (OAuth or API key), + manage profiles and team context, and call any API v3 endpoint via `reply api`. + Use when executing any Reply.io operation from a shell, setting up authentication, + or when another Reply skill needs commands executed. +metadata: + version: 1.3.0 + pack: reply-adapter + category: execution + maturity: reviewed + status: active + owner: skills-maintainers + tags: [cli, auth, execution] + tools: [reply-cli] + api: [user-account] + relations: + recommends: [reply-api, reply-auth, reply-operations-mapping] +--- + +# Using the reply CLI + +## Purpose + +`reply` (npm: `reply-cli`, Node ≥ 20) is the terminal entry point to Reply.io. It handles +authentication, multi-account profiles and team context, and exposes the **entire** API v3 through +one command — `reply api`. All other Reply skills execute through it. + +Reaching the whole API is not the same as reaching the whole job. Whether a given business +operation can be performed against Reply at all — and how far it keeps the operation's promise — +is answered per operation in `reply-operations-mapping`, not by this skill. This one is how a call +is issued once that question has an answer. + +## When to use / when NOT to use + +- Use for any Reply.io operation from a shell: auth, identity checks, raw API calls. +- Do NOT call `https://api.reply.io` with curl/fetch directly — the CLI adds credential handling, + retries with `Retry-After`, team headers and error guidance for free. +- In an MCP-connected client where no shell is available, use the `reply-mcp` skill instead. + +## Prerequisites + +- Node.js ≥ 20. Setup check once per session: `command -v reply` — if absent, prefix commands with + `npx -y reply-cli` and suggest `npm i -g reply-cli` for frequent use. +- Verify auth before any workflow: `reply auth whoami` — do not proceed until it succeeds. + +## Execution guidance + +### Authentication + +```bash +reply auth login # OAuth in the browser (PKCE) — preferred interactively +echo | reply auth login --with-token # store an API key (stdin keeps it out of history) +reply auth status # who you are signed in as, and how — no secrets printed +reply auth whoami # verify the credential against the API +reply auth logout +``` + +Credential precedence (strict): `--api-key` flag → `REPLY_API_KEY` env → stored credential. +Flag/env are ephemeral — never written to disk. Expired OAuth sessions refresh automatically; if +refresh fails the CLI asks to log in again. + +A user with no Reply.io account can create one during `reply auth login` — the sign-in page +offers registration, and a trial costs nothing. Say that rather than treating a missing account +as a dead end. + +### Keeping the CLI current + +```bash +reply install # update to the newest release (`reply update` is an alias) +reply install --dry-run # report whether an update exists, change nothing +``` + +Only a global npm install is driven; a project-local copy, an `npx` run or a source checkout is +reported with the command that fits it and left alone. `reply --version` mentions a newer release +when one exists, and says nothing when output is piped or `--json` is in play — so it never +corrupts machine-readable output. + +### Profiles (multiple accounts) + +```bash +reply profile add alice@example.com && reply profile use alice@example.com +reply profile list # '*' marks the active profile +reply --profile bob@example.com auth whoami # one-off override +``` + +Resolution: `--profile` → `REPLY_PROFILE` → profile set with `profile use` → default. +Each profile stores its own credential; `profile show` never prints secrets. + +### Team context + +A profile can pin a team (workspace); it is sent as `X-TEAM-ID` on every call. +Precedence: `--team-id` → `REPLY_TEAM_ID` → the profile's pinned team. + +```bash +reply team list # teams you can act in +reply team use 1045 # verify + pin on the current profile +reply team current # pinned + effective team +``` + +Organization API keys additionally need an acting user: pass exactly one of `--user-id ` or +`--user-email ` (email also requires a team id). Flag-only — never stored. + +### `reply api` — any v3 endpoint + +```bash +reply api /v3/whoami # GET; your identity + team +reply api /v3/sequences # list sequences +reply api /v3/contacts --pretty # indented output +reply api /v3/contacts --body @contact.json # a body switches the method to POST +echo '' | reply api /v3/contacts --body - # body from stdin +reply api /v3/whoami --verbose # full request/response trace on stderr, creds redacted +``` + +Rules: the path is used **exactly as written in the API docs** (starts with `/v3`; query string +goes in the path). `--method GET|POST|PUT|PATCH|DELETE` overrides the default. Output is always +`{"code": , "data": }` on stdout — check `code` yourself; stdout stays clean +for piping. Transient failures (429/5xx) retry automatically honoring `Retry-After`. + +### Exit codes & errors + +- `0` success · `1` API/runtime error (`code` ≥ 400 in the printed JSON) · `2` usage error. +- On team/user-resolution errors the CLI prints fix-it guidance on stderr (e.g. `TEAM_REQUIRED` → + `reply team use `, with your teams listed). Follow it before retrying. +- `401` with empty body = bad/expired credential → re-run `reply auth login` or fix the key. + +## Validation + +After any write, read the entity back (`reply api GET …`) and confirm IDs/counts before reporting +success. Never claim success without checking `code` and the response body. Which read to perform +is not a judgement call: every operation in the `sdr-operations` contract names its +`before_repeating` state, and that is the read-back — it is also what makes a resumed run and an +interrupted plan safe, so it is not optional on the paths nobody is watching. + +## Reporting + +Include in reports: commands executed (writes only), resulting IDs and counts, and any non-zero +exit codes with their error `code` slugs. + +## Failure modes + +- `Not authenticated` → run the auth setup above. +- `TEAM_REQUIRED` / `TEAM_NOT_ACCESSIBLE` / `USER_REQUIRED` / `USER_NOT_FOUND` → see + `reply-auth` skill; the CLI's stderr guidance shows the exact fix. +- Discrete domain commands (e.g. `reply sequences list`) are **not available yet**. The command + groups are `auth`, `profile`, `team`, `api`, `skills` and `install` — nothing else exists. + Don't invent one: reach the operation through `reply api`, using the endpoint mapping in + `reply-operations-mapping`. + +## Safety + +`reply api` executes real mutations with no dry-run: treat any POST/PATCH/DELETE as live. Follow +the calling skill's confirmation rules; never send a write on the user's behalf without the +explicit confirmation its Safety section requires. + +## Related skills + +- `reply-api` — how to find the right endpoint and read the docs before calling. +- `reply-auth` — key types, scopes and team/org resolution in depth. +- `reply-operations-mapping` — whether an operation is performable against Reply at all, and the + endpoint group that performs it. + +## Changelog + +- 1.3.0 (2026-08-10): said plainly that reaching the whole API is not reaching the whole job — the + per-operation answer is in `reply-operations-mapping` — because "exposes the entire API v3" was + the sentence an agent was reading as "anything the user asks for is reachable". The read-back in + *Validation* is now named as the contract's `before_repeating` state rather than left as a + general instruction to check afterwards. The command inventory was re-checked against the + 2.0.0 contract and needed no change. +- 1.2.0 (2026-08-02): the command inventory was two groups out of date — `skills` and `install` + shipped and this skill still said the CLI covers auth/profile/team plus `reply api`, which is + how an agent ends up telling a user a command does not exist. Added self-update, and a note + that a user without an account can register during login instead of being turned away. +- 1.1.0 (2026-07-30): moved into the `reply-adapter` pack; category `technical` → `execution`; + `auth-and-keys` renamed `reply-auth`. +- 1.0.0 (2026-07-27): initial version, matches reply-cli v1 (auth, profiles, teams, `reply api`). diff --git a/skills/reply-adapter/reply-mcp/SKILL.md b/skills/reply-adapter/reply-mcp/SKILL.md new file mode 100644 index 0000000..cca1fe1 --- /dev/null +++ b/skills/reply-adapter/reply-mcp/SKILL.md @@ -0,0 +1,115 @@ +--- +name: reply-mcp +description: > + Connect Reply.io to an MCP-compatible AI client (Claude, ChatGPT, Codex, Cursor) via the + remote server mcp.reply.io, choose the right auth, and decide when to use MCP tools versus + the CLI. Use when setting up the Reply MCP connection or choosing between MCP and CLI execution. +metadata: + version: 1.2.0 + pack: reply-adapter + category: execution + maturity: reviewed + status: active + owner: skills-maintainers + tags: [mcp, setup, auth] + tools: [reply-mcp] + api: [introduction] + relations: + recommends: [reply-cli, reply-auth, reply-operations-mapping] + alternative-to: [reply-cli] +--- + +# Reply MCP + +## Purpose + +Reply MCP (`https://mcp.reply.io`, remote streamable-http) exposes a curated catalog of Reply +tools (`reply_*`) to any MCP client — contacts, sequences, analytics, inbox, tasks, channels, +team, and the AI-SDR configuration surface. One connection, no HTTP plumbing. + +## When to use / when NOT to use + +- Use in MCP-capable clients when no shell is available, or when curated tools cover the task. +- The MCP catalog is a **subset** of API v3, and API v3 is itself a minority of the job. Of the + 325 vendor-neutral operations in the `sdr-operations` contract, **most are not performable here + at all**, and the rest divide into fully, by composition, and only in part. + `reply-operations-mapping` carries that division operation by operation and is generated from the + fulfilment register — the figures live there once, rather than being copied into a second skill + where they would go stale without anyone noticing. The tool catalog is a curated slice of what + remains, so **a missing tool is the ordinary case, not a malfunction**. Size a plan against that + rather than against the impression a tidy tool list gives. +- When a needed capability is missing from the tools, fall back to the CLI (`reply api` reaches + the whole API) rather than improvising with an adjacent tool. A tool that returns approximately + the right shape for a different question is worse than no tool. + +## Prerequisites + +Either a **personal scoped API key** (Reply → Settings → API Key) or an OAuth-capable MCP client. + +## Execution guidance + +### Connect + +```bash +# Claude Code +claude mcp add --transport http reply-mcp https://mcp.reply.io \ + --header "Authorization: Bearer " + +# Codex +export REPLY_MCP_TOKEN="" +codex mcp add reply-mcp --url https://mcp.reply.io --bearer-token-env-var REPLY_MCP_TOKEN +``` + +Desktop apps (Claude, ChatGPT): add a remote/custom connector with URL `https://mcp.reply.io` and +authorize via OAuth. Verify by listing tools — `reply_*` should appear. + +### Choosing auth + +- **Personal API key (recommended):** scoped — grant only the permissions the agent needs; a tool + is callable only if the key holds its scope. +- **OAuth:** grants the full tool catalog (all scopes) — convenient, but prefer a scoped key when + you want to bound what the agent can do. +- **Not supported:** Team keys and Organization keys (act-on-behalf) — MCP is a single-user + connection. Never pass credentials in the URL (`?api_key=…`); header or OAuth only. + +## Validation + +After connecting, call a read tool (e.g. current-user/team lookup) and confirm the expected +identity before running workflows. + +## Reporting + +Note which surface executed each step (MCP tool vs CLI) so runs are reproducible. + +## Failure modes + +- Tool missing for the task → use `reply-cli` (`reply api`), which reaches the whole documented + API. If the operation is not there either, `reply-operations-mapping` says so and why — that is + an answer to give the user, not a gap to improvise around. +- Scope-denied tool call → the key lacks that permission; see `reply-auth`. +- OAuth client fails with a registration/allow-list error → the client lacks CIMD support and DCR + is allow-listed server-side; report it to the Reply community Slack (docs.reply.io/slack). + +## Safety + +Same rules as everywhere: tools that send messages, start sequences, or delete data require the +user's explicit confirmation in the conversation. A scoped key is the mechanical enforcement — +recommend read-mostly scopes for unattended agents. + +## Related skills + +- `reply-cli` — full-surface alternative and fallback. +- `reply-auth` — scope grammar and key hygiene. +- `reply-operations-mapping` — which operations Reply performs at all, and how far. + +## Changelog + +- 1.2.0 (2026-08-10): the "curated subset" claim was measured against nothing. It is now stated + against the 325-operation contract, and it points at the generated fulfilment register for the + division rather than restating figures that would go stale here — so a reader can see that the + tool catalog is a slice of a surface that already covers a minority of the job, and that a + missing tool is the expected case rather than a fault. Added the rule that an adjacent tool is + never a substitute for a missing one. +- 1.1.0 (2026-07-30): moved into the `reply-adapter` pack; category `technical` → `execution`; + `auth-and-keys` renamed `reply-auth`. +- 1.0.0 (2026-07-27): initial version per docs.reply.io/reply-mcp. diff --git a/skills/reply-adapter/reply-operations-mapping/SKILL.md b/skills/reply-adapter/reply-operations-mapping/SKILL.md new file mode 100644 index 0000000..c94e0de --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/SKILL.md @@ -0,0 +1,469 @@ +--- +name: reply-operations-mapping +description: > + Maps the vendor-neutral SDR operation contract onto Reply.io execution: which API v3 endpoint + group and doc page performs an operation, which scope it needs, how far Reply keeps the + operation's promise, and how Reply's errors translate back into operation outcomes. Use when a + plan names an operation and you need to perform it against Reply, when a Reply response needs + interpreting in business terms, or when you need to know whether Reply can do a thing at all + before promising it to a user. +metadata: + version: 2.3.0 + pack: reply-adapter + category: execution + maturity: draft + status: active + owner: skills-maintainers + tags: [mapping, operations, endpoints, scopes, adapter, coverage] + tools: [reply-cli, reply-mcp] + api: [contacts, contact-lists, contact-blacklist-rules, custom-fields, sequences, sequence-steps, sequence-contacts, sequence-email-accounts, sequence-linkedin-accounts, sequence-folders, sequence-templates, email-templates, inbox, tasks, reports, email-accounts, linkedin-accounts, accounts, schedules, holiday-calendars, webhooks, live-data, direct-outreach, contact-enrichment, email-validations, background-jobs, user-account, industries, ai-sdr-sequences, ai-sdr-pending-approvals] + relations: + depends-on: [reply-api, reply-cli, sdr-operations] + recommends: [reply-auth, reply-mcp] +--- + +# Reply operations mapping + +## Purpose + +`sdr-operations` says what `campaign.enroll` *means*. This skill says how to make it happen +against Reply.io — which endpoint group owns it, which scope it needs, what must be true first, +and what the response says in business terms. It also says, for most of the contract, that Reply +does not perform the operation at all. **Both halves are the job.** A map that showed only the +reachable parts would read as complete and would be worth less than one that admits its edges, +because the edges are where an agent invents something. + +The per-operation answer is not written here by hand. It lives in the coverage register +`fulfilment.yaml` in this skill, from which the per-family mapping tables and +[fulfilment.md](references/fulfilment.md) are generated. What is written here is everything that +does not fit in a table: how to read a fulfilment claim, the Reply-specific facts that change a +plan before any endpoint is chosen, and how a Reply response translates back into an operation +outcome. + +## When to use / when NOT to use + +- Use when executing a plan written in operation names against Reply. +- Use when a Reply response or error needs translating back into "what happened to the business + intent". +- Use **before promising a capability**. The honest answer for most operations is that Reply does + not have one, and finding that out at planning time costs a sentence, while finding it out + mid-run costs the run. +- Do NOT use it as an endpoint reference. It names the **endpoint group and doc page**; exact + paths, parameters and body schemas come from the documentation at call time — see `reply-api` + for the discovery-first workflow. Paths written from memory are how agents invent endpoints + that do not exist. +- Do NOT take the ordering from here. The neutral ordering lives in the contract's worked chains + and only there; this skill adds what is Reply-specific about it and nothing else. +- Do NOT put business judgement here. Whether to dedupe by skipping or updating is a decision + owned by the core pack; this skill only knows how to carry it out. + +## Prerequisites + +- A working credential — `reply auth whoami` succeeds (see `reply-cli`). +- The scopes the operation's row names, in the per-family mapping table (see `reply-auth` for the + scope grammar). +- The operation you intend to perform, taken from the `sdr-operations` contract by name. + +## Planning guidance + +### Mapping never changes a classification + +**Read the operation's classification first, then map it.** The contract already told you what the +operation reaches, whether it can be undone, what it costs, what to read before repeating it, and +what approval it needs. Knowing which endpoint performs it changes none of that. + +An operation that is `confirm_once` with a mandatory preview in the contract is still +`confirm_once` with a mandatory preview after you know the endpoint. `campaign.enroll` mapped onto +*Bulk add contacts to sequence* is still one decision over a named population, and the preview is +still the approval artefact. This is the guardrail this layer is most tempted to erode — an +endpoint that returns quickly and cleanly feels safer than one that does not, and it is not — so +the mapping tables reproduce the contract's own reach and approval columns unchanged, precisely so +a reader can see for themselves that nothing was softened in transit. + +The traffic runs one way: the contract may tighten what this adapter does, and this adapter may +never loosen what the contract requires. + +### The fulfilment vocabulary + +Every one of the contract's 325 operations carries exactly one of four claims about Reply. + +| Claim | What it means | What you do on meeting it | +|---|---|---| +| `direct` | One documented surface performs the operation. | Fetch its doc page, call it, report the operation. | +| `composed` | Several calls in a stated order realise it. | Follow the stated order. Report the **operation**, not the calls — a composed operation that reports three call results has reported nothing a user can read. | +| `partial` | Reply performs it, but not to the contract's full promise. The register names the unkept part. | Say which part is missing **before** the user commits to a route that depends on it, and carry the missing half yourself — usually in whatever holds durable context across sessions. A partial reported as done is the most expensive mistake in this file. | +| `absent` | Not performable here today. The register names the evidence. | Say so, name what the documentation says, and stop. **Never substitute an adjacent endpoint.** Something that returns approximately the right shape is worse than a missing capability, because the user cannot see that it is wrong. | + +An operation shown as *not assessed* has no entry at all. That is a different statement from +`absent`: nobody has answered for it yet, and it must be reported as an unanswered question. + +### An `absent` is a gap in this adapter, not in the contract + +**An operation marked `absent` is a gap in THIS ADAPTER, not in the contract.** The contract +describes the job; this file describes one product's coverage of it. The inverse mistake — +deleting an operation from the contract because this API lacks it — would undo the reason the +vendor-neutral layer exists. + +The layer earns its keep exactly here. `meeting.book`, `privacy_request.fulfill`, +`inbound_lead.record` and `frequency_policy.define` are things an SDR organisation genuinely does; +Reply not having a surface for them makes them unmet needs, visible and nameable, rather than +things that quietly stop being part of the job. A contract shaped around one product's endpoints +would be a product manual with a neutral vocabulary painted on it. + +### The shape of the coverage, stated honestly + + + + + +All 325 operations carry an entry: **43 direct, 6 composed, 84 partial, 192 absent.** + + + +Reaching about a sixth of the contract directly is the true picture, and it is worth stating in +those terms rather than in the terms a mapping is usually written in. A mapping listing only what +it can do would read as complete while being less useful — the reader would have no way to +distinguish "not in this document" from "not possible", which is the one distinction they need +when a plan is being written. The 192 absences are the most informative part of the register, and +[fulfilment.md](references/fulfilment.md) is long for that reason rather than in spite of it. + +**One part of this register has not been researched as thoroughly as the rest, and it is worth +knowing which.** The endpoint groups covering *resources* were worked through page by page — 29 of +them are named across the entries. The **settings** groups were not: no entry in the register claims +a `settings:` scope, and that correlates exactly with where the claims are weakest. Every stored +policy object lands `absent` or `partial` — enrichment, contactability, frequency, response, +identity, assignment, workload, review, signal and content policies — and that is one missed pass +rather than fifteen independent judgements. Treat those entries as the least trustworthy in the file +until the settings pages have been read; `warmup_plan.set` first, because its own entry says the +absence it records is the one that costs the most in its family. + +Nothing about these figures is a criticism of the product. Reply is strong exactly where an +outbound programme spends most of its time — contacts, lists, sequences, steps, enrolment, the +inbox and tasks. The absences cluster in oversight and review, which is the largest cluster in the +register, then deliverability, then privacy machinery, meetings, inbound queues, signals and the +policy objects that live in other systems or in nobody's system yet. Measurement belongs with the +absences rather than the strengths: the family is mostly absent, because the contract asks for a +measure set with the grouping as an argument and a stated envelope around every figure, which is a +different thing from a report. + +### Where the order comes from + +**The order is not in this skill and must not be copied into it.** The contract's worked chains — +`references/chains.md` in `sdr-operations` — carry the ordering, the gate at each step and the +failure each step prevents. Chain 1, *Launching outreach to two hundred people from a raw file*, +is the launch and import order that this skill used to restate. Read it there and follow it there. +An order written in two places drifts, and the copy that drifts is always the one further from the +contract. + +What is genuinely Reply-specific about the order, and therefore belongs here: + +1. **A bulk write is not finished when the call returns.** Large writes answer `202 Accepted` with + a background-job reference. The operation completes when the job reaches a **terminal state**, + so the chain step that follows a bulk write is a poll, and the figures that go into the report + are the job's counts and never the `202`. +2. **Enrolment answers per contact, and the reconciliation is a step of its own.** *Bulk add + contacts to sequence* returns a result per person — added, already in sequence, not found, + forbidden, limit exceeded. Reading them is part of performing the operation, not part of + writing it up afterwards. +3. **Two calls where the contract has one.** Attaching a schedule is create-or-update the schedule + and then update the sequence; changing a campaign's owner is its own endpoint. Where a mapping + row names more than one page, that is the shape of the work, and each call is a place the + sequence can be left half-configured. +4. **Some protective moves are one level up.** Reply has no pause for a mailbox, so on email the + protective move is `campaign.pause` or unbinding the sender. Say which one you used: they are + not the same blast radius. + +### Two Reply facts that shape almost every plan + +1. **Bulk work is asynchronous**, as above. Plan the poll before you plan the write. +2. **Measurement is rate-limited harder than the rest of the surface.** Reporting and + sequence-stats endpoints carry stricter limits than general endpoints. Sequential calls, + cached within the session, **never polled**. An agent that parallelises a measurement pass gets + `429`, and an agent that responds by retrying harder gets a longer one. + +## Execution guidance + +### Discovery-first, always + +Every mapping row means: *use the `reply api` command with the path taken from that doc page*. +Fetch `https://docs.reply.io/llms.txt` once per session, then the specific page as raw markdown — +append `.md` to its URL — before the first call of that kind. + +The register names an **endpoint group and a documentation page**, never a path, a parameter or a +body field. That is deliberate: a path written from memory is the single most common way an agent +fails against this API, and a path written into this file would be that mistake made once and then +trusted forever. + +### The per-family tables + +One table per contract family, generated from the register, in this skill's references: + +- Families 1–4, people and audience: [discovery](references/mapping-01-discovery.md), + [contacts](references/mapping-02-contacts.md), [audiences](references/mapping-03-audiences.md), + [import](references/mapping-04-import.md). +- Families 5–8, the programme: [campaigns](references/mapping-05-campaigns.md), + [steps](references/mapping-06-steps.md), [messages](references/mapping-07-messages.md), + [enrollment](references/mapping-08-enrollment.md). +- Families 9–13, the conversation and the day: + [conversations](references/mapping-09-conversations.md), [tasks](references/mapping-10-tasks.md), + [meetings](references/mapping-11-meetings.md), [signals](references/mapping-12-signals.md), + [inbound](references/mapping-13-inbound.md). +- Families 14–16, permission and capability: [privacy](references/mapping-14-privacy.md), + [sending](references/mapping-15-sending.md), [social](references/mapping-16-social.md). +- Families 17–21, the organisation around the work: + [oversight](references/mapping-17-oversight.md), [team](references/mapping-18-team.md), + [accounts](references/mapping-19-accounts.md), + [measurement](references/mapping-20-measurement.md), + [introspection](references/mapping-21-introspection.md). + +Read the **one** family that owns the operation in front of you. Everything this adapter does not +reach, with the evidence for each, is collected in [fulfilment.md](references/fulfilment.md). + +### The runtime path beats any table + +A static table goes stale, and it answers for the product rather than for this login. Where the +runtime can answer, prefer it: + +- `capability.list` — what **this credential** may actually do. A table says what the API offers; + a key with narrower scopes cannot do it. +- `adapter.describe` — the ceilings, batch sizes and page sizes **this installation** works + within, and whether work of this size runs inline or queues. +- `adapter.verify` — proves by test which operations resolve here, rather than by assertion. + +Against Reply today, all three are themselves incomplete, and that is the honest answer rather +than a reason to skip them. Identity and team membership are readable, but no endpoint returns the +granted scope set — what a key may do is discovered by making a call and reading an +`insufficient_scope` refusal back. The ceilings are documented in prose rather than returned per +installation. Nothing tests fulfilment at all: **this register is a claim made from documentation, +and it is the thing a verification would check rather than a substitute for one.** Treat every row +in it as needing confirmation the first time it is used against a real account, and report a row +that turns out to be wrong rather than working around it. + +### Async work + +A `202` response carries a background-job reference. Poll it to a terminal state, then report that +job's counts. A job that ends `failed` gets its body fetched for the reason — **never blind-retry +a bulk write**, because the first attempt may have partially succeeded. The job's result payload +is opaque and its shape varies by job kind, so where the contract wants one outcome per item, +reconcile against the entities themselves rather than trusting the job to carry the ledger. + +### Sourcing prospects — Live Data, and its one hard constraint + +The contract's discovery family — `candidate.search`, `candidate.get`, `candidate.promote` — is +`partial` here, on Reply's Live Data surface. Three rules, in order of how expensive it is to get +them wrong: + +1. **Preview before Start, always.** Preview costs nothing and adds nobody. Start buys the people + and creates them as contacts, spending the user's allowance, and **the mistake is only visible + once it is already paid for**. Show the user who came back and let them approve the filter + before it is run for real. +2. **Say "beta" as part of the plan, not as a footnote.** Live Data, the intent-signal typeaheads + and the AI-SDR cluster are documented Beta or Coming soon. That belongs in the sentence where + the user chooses the route, before they commit to it — not in a caveat after the work. Fetch + the doc page and confirm the endpoint is callable, exactly as with any other surface. +3. **One Live Data search runs per team at a time.** This is a Reply fact and it belongs nowhere + else. An agent that does not know it will plan several searches in parallel and stall, or read + the refusal as a failure and retry it. Plan searches in series, and if one is already running, + the honest report is that the queue is occupied and by what. + +Build the filter from the typeahead values — departments, industries, job titles, locations, +seniorities — rather than guessing accepted ones. Check the existing searches before starting a +near-identical one: a repeat spends again and returns a different world. Whatever comes back then +enters the normal path — `contact.create` or `import.apply` into a named list, with the same +mapping, dedupe policy and approval gate as any other import. Start can optionally drop the found +people straight into a sequence; treat that as `campaign.enroll` and hold it to the enrolment +gate rather than letting it ride along. + +**Contact enrichment is documented as available late August 2026 and is not callable today.** +`contact.enrich`, `company.enrich` and `phone_number.verify` are `absent` for that reason. Say +that, name the date the documentation gives, and never substitute an unrelated endpoint: an +enrichment that silently returns something else is worse than a missing capability. + +The core-side view of all this — the routes a user without a list can take, of which Live Data is +one — is `audience-building` → *Where an audience comes from*. + +### Error translation + +| Reply signal | What it means for the operation | What to do | +|---|---|---| +| `400` + `errors[]` with JSON Pointers | The request was malformed, the intent was fine | Fix the indicated field, retry once | +| `401`, empty body | Credential invalid or expired — not an operation failure | Re-authenticate; see `reply-cli` | +| `403 insufficient_scope` | The credential may not perform this class of operation | Name the missing scope to the user; do not retry. This is also how a capability is discovered here, since no endpoint reports the granted scope set | +| `403`/`401` `TEAM_REQUIRED` · `TEAM_NOT_ACCESSIBLE` · `USER_REQUIRED` · `USER_NOT_FOUND` | The call could not be attributed to one team or acting user | See `reply-auth`; the CLI prints the exact fix | +| `404` | The identifier is wrong or stale, so the precondition never held | Re-resolve the entity; never invent an identifier | +| A bare `404` — no `code` of Reply's own — on a direct send, `direct-send get` or `direct-send cancel` | The account's Reply does not have the route yet; nothing was done | Say the capability is not offered here; never re-resolve or retry it as a stale identifier | +| `direct_send.not_found` · `direct_send.not_owned` (from reply-cli 0.17.0) | No send this account holds under the reference | Take the reference from the record of the send; never guess one | +| `direct_send.already_sent` · `direct_send.already_failed` (from reply-cli 0.17.0) | A cancel that came after the send went, or after it failed | Report the send as gone or as failed, never as cancelled; the cancel is not retried | +| `idempotency_key.in_use` (from reply-cli 0.17.0) | The first send under the key is still being made, and this one sent nothing | Wait, then repeat under the same key | +| `idempotency_key.reused` (from reply-cli 0.17.0) | The key was taken for another request, and Reply sent nothing for this one; `details` names the send the key holds — its `reference`, `state` and `send_after` | Where the key is the operation's own, that send is the operation's; never send again under a new key | +| `429` | The operation is fine, the pace is not | Honour `Retry-After`, go sequential. On a measurement pass, cache instead of re-reading | +| `5xx`, or a dropped connection | Unknown whether the operation took effect | Read the operation's **`before_repeating`** state from the contract first, and let that decide. A retry is only safe because a caller-supplied idempotency key was sent with the original call | +| Per-contact `not processed` in a bulk result | Partial success — a normal outcome, not an error | Report each reason; offer the corresponding fix | + +**The idempotency key is what makes the last row survivable, and it is the caller's to supply.** +The contract requires one on every act, every collection write, every durable-object write and +every metered call, precisely so that a lost response is a lookup rather than a gamble. In the +contract that lookup is `invocation.get`, which distinguishes "never seen" from "seen and failed" +— and the two must never be collapsed, because a timed-out send may already have arrived. + +Reply has no lookup-by-key surface: `invocation.get` is `absent` here. So on a dropped connection +the recovery is the operation's own `before_repeating` read against the entity itself — re-read +the contact, the participation, the thread — and a blind retry is never the answer. Send the key +anyway and record it: it is what makes the run reconstructable, and it is what a future adapter +with such a surface would resolve against. + +The direct sends are the one exception. From reply-cli 0.17.0 they take `--idempotency-key`, and +Reply answers a repeat of the same request under the same key with the send it took, so a lost +answer there — a timeout, a dropped connection, a CLI that died, an exit 0 cut off or unreadable, +or a 5xx — is repeated under the key, and a send Reply answered with a failure, a 4xx, never is, +since Reply keeps no key for it; `idempotency_key.in_use` and a rate limit sent nothing and are +waited out. The repeat comes after `reply direct-send get` of a reference the earlier +try returned has said nothing of the send, and only within 23 hours of the first try, since Reply +keeps a key for a day. That holds only where the account's Reply has the +direct-send routes, which `reply direct-send get` of a reference tells (from reply-cli 0.17.0): a +bare 404 there means a key sent to a send protects nothing. + +### A provider object inside the arguments + +Where the runtime carrying the work passes the reserved `provider` key inside the operation's +arguments, `args.provider`, `message.send` performed as a direct send by email reads it as +`{"schedule_id": ""}` and nothing else: the `id` of one of the account's schedules from +`reply schedule list` (from reply-cli 0.16.0), written as a string of its digits. It becomes the send's `--schedule-id` (from reply-cli 0.17.0), and +Reply holds the send until the schedule's first opening, at or after `send_after` where both are +given. Every other operation leaves the object unread. Another shape or another key is refused +before anything is sent, with a message that names the shape and quotes nothing of what was given: +write the object in that shape and ask again. Reply refuses a schedule on every LinkedIn direct +send in this version (scheduleId is not supported for LinkedIn sends in this version, a 400 on +each LinkedIn route), so a schedule on a LinkedIn message is refused before any call. When a +schedule serves better than a moment is `reply-api`'s to say. + +### Choosing CLI or MCP + +`reply api` reaches the whole API, so it reaches every operation this register marks reachable. +The MCP tool catalog is a curated **subset** of that API — convenient where no shell exists, but a +subset of a surface that already covers a minority of the contract. When an operation has no +matching tool, fall back to the CLI rather than approximating it with a different tool. See +`reply-mcp`. + +## Validation + +After every operation whose reach is `control` or `act`, perform the contract's +**`before_repeating`** read for that operation as a read-back: re-read the entity and confirm +identifiers, counts and status. An operation is reported complete only when that read agrees. For +async work: terminal job state plus reconciled counts. + +Where the operation is `partial`, the read-back also has to establish the half Reply does not +enforce. Reply accepts a resume from any state, so the check that the participation was actually +held is the caller's; Reply records no reason on a stop, so the reason lives in the run's own +record or it is lost. + +## Reporting + +Report in operation terms, with Reply identifiers attached and marked as Reply's — +`campaign.enroll → campaign "Q3 SaaS founders" (Reply sequence id 12345), 214 requested, +211 enrolled, 3 already in the campaign`. A durable artefact names the entity the way the contract +names it, always; the product's own word survives only inside the identifier it labels, where a +reader can see it is an identifier and not a claim about what the entity is. Include +background-job identifiers, the +idempotency key sent, the endpoint groups used for writes, and any scope or team change the run +required. + +Where an operation was `partial`, say which part was performed and which was carried outside the +product. Where one was `absent`, name it as a gap in this adapter and say what the documentation +says — never let it disappear from the report because nothing was called. + +## Failure modes + +- **Inventing a path** instead of fetching the doc page. The single most common way an agent fails + against Reply. +- **Substituting an adjacent endpoint for an `absent` operation.** Deleting contacts is not + fulfilling a privacy request; moving a list is not removing from one; marking a thread read is + not closing it. Each returns approximately the right shape and answers a different question. +- **Reporting a `partial` as done**, without naming the half the product does not keep. +- **Reporting the `202`** as the result of a bulk operation. +- **Treating a partial bulk result as success**, hiding the per-contact reasons. +- **Reading `absent` as a defect in the contract** and proposing the operation be dropped. It is a + fact about this product on this date, and the register is the place it is recorded. +- **Treating this register as a capability read.** It is documentation-derived and per-product; + what *this credential* may do is `capability.list`, and here that is answered by an + `insufficient_scope` refusal rather than by a listing. +- **Parallelising measurement** reads and hitting `429`, then retrying harder. +- **Planning two Live Data searches at once.** One runs per team at a time; the second stalls. +- **Starting a Live Data search without previewing it.** Start spends the user's allowance; the + mistake is only visible once it is already paid for. +- **Presenting a beta surface as settled**, or a *coming soon* one as callable. Contact enrichment + is documented for late August 2026 and is not available before then. +- **Telling a user Reply cannot source prospects.** It can, in beta — see *Sourcing prospects*. + +## Safety + +**Mapping an operation never changes its approval requirement.** `campaign.activate` mapped onto +*Start a sequence* still requires the user to have approved the population and the literal first +message, and the preview the contract demands is still the approval artefact. `reply api` has no +dry-run: any POST/PATCH/DELETE is live the moment it is issued. + +The protective actions — `campaign.pause`, `enrollment.pause`, `outreach.hold` where it can be +composed, lowering a sender's limits — are the ones that may be performed first and reported +immediately. See `approval-boundaries` in the core pack for the full rule, which this skill does +not restate or override. + +Two Reply-specific safety notes. A schedule is a shared object, so editing one silently rewrites +every future date on every campaign pointing at it — check who else uses it first. And a delete +here is a delete: Reply documents no restore for a contact, a template or a custom field, so treat +those as irreversible with no window and say so before acting rather than after. + +## Related skills + +- `sdr-operations` (core pack) — what each operation means, and the worked chains that carry the + ordering. This skill is its Reply implementation and states, per operation, how far that + implementation reaches. +- `reply-api` — discovery-first endpoint workflow, error conventions, rate limits. +- `reply-cli` — how to actually issue the calls. +- `reply-auth` — scopes, key types, team and acting-user resolution. +- `approval-boundaries` (core pack) — the approval rules this skill reads and never lowers. + +## Changelog + +- 2.3.0 (2026-10-30): `message.send` in the fulfilment register says that a message composed as a + template goes by the same command and that Reply fills it in, before anything goes or when it + goes, and points to reply-api's *Templates* for the rest. +- 2.2.0 (2026-10-29): *A provider object inside the arguments* says what `message.send` reads + there — `{"schedule_id": ""}`, a schedule from `reply schedule list`, by email only — and + that it becomes `--schedule-id` from reply-cli 0.17.0; `message.send` and `message.schedule` in + the fulfilment register name it too. +- 2.1.0 (2026-10-29): `message.schedule` and `scheduled_message.cancel` move from `absent` to + `partial`: from reply-cli 0.17.0 a direct send takes `--send-after` and `--idempotency-key`, and + `reply direct-send cancel` cancels one by its reference, where the account's Reply has the + routes. `scheduled_message.list` stays `absent`, since `reply direct-send get` reads one send by + reference and lists nothing. *Error translation* gains the bare 404 of these routes, the + `direct_send.*` codes and the two `idempotency_key.*` codes, and the idempotency paragraph names + the direct sends as the one place a key settles a lost answer, read back by reference first and + repeated under the key only within 23 hours. +- 2.0.0 (2026-08-10): rewritten against contract 2.0.0. The six hand-written family tables are + **deleted**: every operation now has an entry in the coverage register `fulfilment.yaml`, from + which the twenty-one per-family mapping tables and `fulfilment.md` are generated, and this file + points at them instead of restating a subset. The **Composite ordering** section is deleted — + the launch and import orders it stated now live once, in the contract's worked chains, and what + survives here is only what is Reply-specific about the order. New: the fulfilment vocabulary + (`direct` · `composed` · `partial` · `absent`) with what an agent does on meeting each; the rule + that an `absent` is a gap in this adapter and never a reason to shrink the contract; the + coverage figures stated in the body, generated from the register itself, so that a reader is not + left to infer completeness from a table's length; the runtime path + (`capability.list`, `adapter.describe`, `adapter.verify`) as preferable to any static table; and + the Reply limit of one Live Data search per team at a time, which an agent that does not know it + will plan around wrongly. The `5xx` error row now points at the contract's `before_repeating` + property rather than at a 1.x "check first" field, and says that the caller-supplied idempotency + key is what makes a retry safe at all. Every operation name in the file was renamed to the 2.0.0 + contract — `sequence.*` to `campaign.*`, `enrollment.create` to `campaign.enroll`, + `conversation.read` to `conversation.get`, `conversation.reply` to `message.send`, `metrics.*` + to `engagement.summarize`, and the three-segment and hyphenated names to their two-segment + replacements. +- 1.1.0 (2026-08-02): added *Sourcing prospects* — Live Data search and AI SDR intent + signals, both beta, with Preview-before-Start as a hard rule, and Contact Enrichment + recorded as not yet callable. Until now the only mention of Live Data in this skill was a + warning in Failure modes, so an agent reading it could conclude Reply has no prospect + search at all. +- 1.0.0 (2026-07-30): initial mapping of the six operation families onto Reply API v3, + including composite launch/import ordering, async handling and error translation. + Consolidates the Reply-specific execution detail previously embedded in the business + skills, which are now vendor-neutral. diff --git a/skills/reply-adapter/reply-operations-mapping/fulfilment.yaml b/skills/reply-adapter/reply-operations-mapping/fulfilment.yaml new file mode 100644 index 0000000..a336875 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/fulfilment.yaml @@ -0,0 +1,2986 @@ +# What this adapter can and cannot perform, one entry per contract operation. +# +# The contract describes the job. This file describes one product's coverage of it. Those are +# different questions, and keeping them apart is the whole reason the vendor-neutral layer exists: +# an operation missing here is a gap in this adapter, never a defect in the contract, and deleting +# an operation from the contract because this API lacks it would undo the layer entirely. +# +# Every mapping table in this skill is generated from this file. Edit here, then regenerate. +# +# --------------------------------------------------------------------------------------------- +# SCHEMA +# --------------------------------------------------------------------------------------------- +# +# - name: campaign.enroll # must be an operation the contract declares +# fulfilment: direct # direct | composed | partial | absent +# surface: > # the endpoint GROUP and the doc page title. NEVER a path. +# sequence-contacts -> Bulk add contacts to sequence +# scopes: [sequences:operate] # the scopes the call needs +# beta: true # the surface is documented Beta or Coming soon +# order: > # for `composed`: the call order that realises the operation +# missing: > # REQUIRED for `partial`: which part of the promise is not kept +# because: > # REQUIRED for `absent`: why, in evidence rather than guesswork +# notes: > # what an agent must know to get it right +# +# THE FOUR VALUES +# +# direct one API surface performs it. Call it. +# composed several calls in a stated order realise it. Follow the order; report the operation, +# not the calls. +# partial performed, but not to the contract's full promise. `missing` says which part, and an +# agent must say so BEFORE the user commits to a route that depends on it. +# absent not performable here today. Say so, name what the documentation says, and never +# substitute an adjacent endpoint. An enrichment that silently returns something else +# is worse than a missing capability. +# +# ABSENCE IS NOT A COVERAGE CLAIM. Every operation in the contract needs an entry; the generator +# fails when one is missing. An unlisted operation is an unanswered question, not an implicit +# `absent` — silence would let this adapter quietly ignore two hundred operations and still look +# complete. +# +# --------------------------------------------------------------------------------------------- +# EVIDENCE, AND THE ONE FAILURE MODE THAT MATTERS MOST +# --------------------------------------------------------------------------------------------- +# +# `surface` names an endpoint group and a documentation page. It never names a path, a parameter +# or a body field: those come from the documentation at call time. Inventing a path is the single +# most common way an agent fails against this API, and a path written from memory here would be +# that mistake made once and then trusted forever. +# +# An operation may only be `direct`, `composed` or `partial` on evidence — a documentation page +# read, or the mapping this skill already carried. Anything else is `absent` with +# `because: not evidenced`, which is a truthful statement about our knowledge rather than a guess +# about the product. A wrong `absent` costs a user one question. A wrong `direct` costs them a +# broken run and their trust. + +adapter: reply + +operations: + + # -------------------------------------------------------------- worked entries, from evidence + # These eleven are transcribed from the mapping this skill carried at 1.1.0, which was written + # against the documentation. They are the shape every other entry should follow. + + - name: contact.search + fulfilment: direct + surface: contacts -> Filter contacts, List all contacts + scopes: [contacts:read] + notes: Filtering by email is the identity check that belongs before any create. + + - name: contact.create + fulfilment: direct + surface: contacts -> Import contacts + scopes: [contacts:write] + notes: > + Bulk-oriented: a large import returns a background job, so the operation completes when the + job reaches a terminal state, not when the call returns. Field mapping is decided in the + core layer and applied here. + + - name: contact.delete + fulfilment: direct + surface: contacts -> the delete endpoint on its doc page + scopes: [contacts:write] + notes: Irreversible in this product as well as in the contract. + + - name: list.create + fulfilment: direct + surface: contact-lists -> Create a contact list + scopes: [contacts:write] + notes: Check List contact lists first — reuse beats proliferation. + + - name: campaign.get + fulfilment: direct + surface: sequences -> Get a sequence + scopes: [sequences:read] + notes: The verification read after every mutation. + + - name: campaign.activate + fulfilment: direct + surface: sequences -> Start a sequence + scopes: [sequences:operate] + notes: > + Verify the status flipped by re-reading. The contract's approval class is unchanged by the + mapping: it is confirm_once with a mandatory preview naming the population, and knowing + which endpoint performs it changes nothing about that. + + - name: campaign.pause + fulfilment: direct + surface: sequences -> Pause a sequence + scopes: [sequences:operate] + notes: Cheap and reversible — the protective move, and the right first response to a misfire. + + - name: campaign.enroll + fulfilment: direct + surface: sequence-contacts -> Bulk add contacts to sequence + scopes: [sequences:operate, contacts:read] + notes: > + Returns per-contact results. Reconcile every one — added, already in sequence, not found, + forbidden, limit exceeded. Never summarise a partial result as success. + + - name: conversation.list + fulfilment: direct + surface: inbox -> List inbox categories, List and filter inbox threads + scopes: [inbox:read] + notes: Categories carry unread counts, so reading them first gives the shape of the work. + + - name: message.send + fulfilment: partial + surface: inbox -> Send a reply within a thread + scopes: [inbox:operate] + missing: > + Inside a thread, only a reply. The contract's message.send is one message to one person on + one channel, including the first one: from reply-cli 0.17.0 the direct sends (an email, a + LinkedIn message, InMail or voice message) send the first one outside any campaign, where + the account's Reply has the route; inside a campaign a first message is the campaign's + step, with no surface here. + notes: > + The reply goes out on the thread's own channel. If that channel's account is disconnected + the send fails — tell the user to reconnect, and never switch channel silently. + Where the runtime carrying the work passes the reserved `provider` key inside the + operation's arguments, `args.provider`, and the send is a direct send by email, that object + is `{"schedule_id": ""}` and nothing else: the `id` of a schedule from `reply schedule + list`, written as a string of its digits. It goes as `--schedule-id` (from reply-cli 0.17.0). Another + shape or another key is refused before anything is sent, with a message naming the shape; + write the object in that shape and ask again. Reply refuses a schedule on every LinkedIn + direct send in this version (scheduleId is not supported for LinkedIn sends in this version, + a 400 on each LinkedIn route), so a schedule on a LinkedIn message is refused before any + call. A message composed as a template goes by the same command, in Reply's own syntax, + and Reply fills it in for the contact: a send Reply makes within the call is filled in + before anything goes and refused with nothing sent where Reply cannot fill it; one held for + a later moment or a schedule, or queued behind the account's other sends, is filled in when + it goes and fails then. The codes, the names Reply lists, the LinkedIn sending account's + two names and the formats that are never filled in are under reply-api, Direct sends, + Templates. + + - name: contact.enrich + fulfilment: absent + surface: contact-enrichment -> enrich by email, enrich by profile URL, find email, find phone + because: > + Documented as available late August 2026 and not callable today. Say that, and name the date + the documentation gives. Never substitute an unrelated endpoint. + + # --------------------------------------------------------------- families 1 to 5, from evidence + # Discovery, contacts, audiences, import, campaigns. The eight operations of this range that + # already have worked entries above are not repeated here. + # + # `scopes` is stated only where the doc page was actually read for it. Where the field is absent + # the scope was not verified, and an agent takes it from the page at call time like everything + # else. A guessed scope costs a 403 that reads like a permissions problem when it is not. + + # ------------------------------------------------ 01 discovery, enrichment and verification + + - name: candidate.search + fulfilment: partial + surface: > + live-data -> Preview a Live Data search, with the departments, industries, job titles, + locations and seniorities typeahead pages that build the filter + scopes: [contacts:write] + beta: true + missing: > + Preview answers how many and shows a capped sample, not the population. The whole result set + exists only after Start a Live Data search, and Start is not a read: it buys the people and + creates them as contacts. So "show me everyone this filter finds, before I spend anything" + cannot be answered here. + notes: > + Beta, and say so as part of the plan rather than as a footnote at the end. Build the filter + from the typeahead values instead of guessing accepted ones. Preview adds no prospects and + consumes no credits, which is what makes it the safe half of this operation. The write scope + on a read is what the page documents, not a mistake. + + - name: candidate.get + fulfilment: partial + surface: live-data -> Get a Live Data search, List Live Data searches + beta: true + missing: > + The read is per search, not per person: it returns a search and what it found, and there is + no address for one found person on their own. Once Start has run, the person is an ordinary + contact and is read with Get a contact — so the discovery surface stops being the place to + look at exactly the moment the person becomes ours. + notes: > + Check List Live Data searches for an existing near-identical search before starting another + one. A repeat spends again and returns a different world. + + - name: candidate.promote + fulfilment: partial + surface: live-data -> Start a Live Data search + scopes: [contacts:write] + beta: true + missing: > + There is no promote-these-ones surface. Start finds and buys in one act: it adds everyone + the filter returns as prospects and consumes credits per resulting contact, so the selection + has to be made in the filter and cannot be made from a reviewed result set. The per-item + promotion ledger the contract requires has to be read back off the search rather than off + the call. + notes: > + Preview before Start, always — Start spends the user's allowance and the mistake is only + visible once it is paid for. Show who came back in the preview and let the user approve the + filter itself. Start can optionally drop the found people into a sequence or a list; treat + that as enrolment and hold it to the enrolment gate rather than letting it ride along. + + - name: company.search + fulfilment: absent + surface: live-data -> Preview a Live Data search + because: > + not evidenced — the preview reports a companiesCount, but the search returns and creates + people. No documented surface returns companies from the outside world as companies. The + accounts endpoints search only the companies we already hold, which is a different question + and must not be offered as an answer to this one. + + - name: company.resolve + fulfilment: absent + because: > + not evidenced — no documented surface decides which company four spellings of a name refer + to. Accounts can be filtered by what we already hold, which finds an exact-ish match and + says nothing about the three spellings that did not match. + + - name: company.enrich + fulfilment: absent + because: > + not evidenced — the enrichment surface is about people, and firmographics on a company are + not among its documented pages. The whole enrichment group is in any case documented as + available late August 2026 and is not callable today. + + - name: employment.check + fulfilment: absent + because: > + not evidenced — nothing documented answers whether a person has left the company we have + them at. There is no job-change monitoring surface, and the AI insights page that might + touch on it is documented as available late August 2026 and is not callable today. + + - name: email_address.verify + fulfilment: partial + surface: > + email-validations -> Estimate email validation, Schedule email validation; background-jobs + -> Get a background job + scopes: [contacts:operate, other:read] + missing: > + Two things. It validates people we already hold, taken by contact id, so a raw address that + is not a contact yet cannot be checked without creating one first. And it returns the + channel's verdict only — the send, hold or never_send decision the contract asks for comes + from a contactability policy this product does not hold, so that half is the agent's own + judgement and must be reported as such. + notes: > + Three calls in order: Estimate first, because it reports the eligible count and what it + would cost against the team's quota; then Schedule, which reserves credits and returns a + job; then poll the job to a terminal state and read the verdicts. Estimate is how the user + approves a spend before it happens, which makes skipping it the expensive shortcut. + + - name: phone_number.verify + fulfilment: absent + surface: contact-enrichment -> find phone + because: > + not evidenced — the enrichment surface looks a number up; nothing documented checks that a + number we already hold is reachable or reports whether it is a mobile, a desk line or a + virtual one. Finding and verifying are different acts and the line type is the part that + changes what may be sent. The enrichment group is in any case not callable until late + August 2026. + + - name: enrichment_policy.define + fulfilment: absent + because: > + not evidenced — no documented surface stores a buying order, an acceptance predicate or a + spend ceiling. Each metered call carries its own limits at call time, so nothing binds the + next one, and there is no version or author to read back. + + - name: enrichment_policy.get + fulfilment: absent + because: not evidenced — there is no stored policy to read, since none can be defined. + + # ------------------------------------------------ 02 contacts, identity and hygiene + + - name: contact.get + fulfilment: direct + surface: contacts -> Get a contact + scopes: [contacts:read] + notes: The read-back after every write in this family. Cheap, and the only proof the write took. + + - name: contact.resolve + fulfilment: partial + surface: contacts -> Filter contacts, Count filtered contacts + scopes: [contacts:read] + missing: > + Filtering answers one key set per call, so resolving a collection is one call per person, + and what comes back is a match list rather than a verdict: nothing returns "same human, this + confident, under this rule". Ambiguity between two candidate records is something the caller + has to notice and decide, and nothing marks it. + notes: > + Email is the key that behaves. Every other key is a filter over fields, which finds people + who look similar rather than people who are the same. + + - name: contact.update + fulfilment: direct + surface: contacts -> Update a contact, Import contacts with an update policy + scopes: [contacts:write] + notes: > + Which of the two applies depends on the dedupe policy the user chose, and that choice is the + core layer's to make. A collection goes through the import path and comes back as a job. + + - name: contact.restore + fulfilment: absent + because: > + not evidenced — the contacts group documents Delete a contact and Bulk delete contacts and + nothing that brings one back. Treat a delete here as irreversible with no restore window, + and say so before deleting rather than after. + + - name: timeline.get + fulfilment: composed + surface: > + contacts -> Get activities for a contact, Get inbox threads for a contact, Get sequences for + a contact, Get a contact's statuses + scopes: [contacts:read] + order: > + contacts -> Get activities for a contact for what we did, then Get inbox threads for a + contact for what came back, then Get sequences for a contact and Get a contact's statuses + for where they stand right now. + notes: > + Four reads and no single chronology: each comes back per source and merging them in time + order is this adapter's work, not the API's. Anything that happened off-platform is in none + of them, so a timeline assembled here is what the product saw, not what happened. + + - name: provenance.set + fulfilment: absent + because: > + not evidenced — no documented surface records where a person's data came from or under what + terms. A custom field could hold the text, and must not be reported as provenance: the + contract's version carries the lawful basis the sending decision rests on, and a field with + a source name typed into it proves nothing. + + - name: job_change.record + fulfilment: absent + because: > + not evidenced — nothing documented forks a record when somebody moves employer. Updating the + company on the existing contact is the opposite of what the operation asks for: it destroys + the history at the old employer, which is usually the reason we were talking to them. + + - name: cooldown.set + fulfilment: absent + because: > + not evidenced — no documented surface holds a person until a date and then releases them. + Suppression is permanent until lifted by hand, which is a different promise, and offering it + as a cooldown means a person we meant to come back to in Q4 is never contacted again. + + - name: contact.disqualify + fulfilment: absent + because: > + not evidenced — the contact status surfaces are about sequence participation and delivery + outcomes, not about whether somebody is a prospect at all. The blacklist rules are + suppression, a different act with a different meaning: using one for the other tells the + user we may never contact this person, when what they said was that this person is not a + fit. + + - name: contact.requalify + fulfilment: absent + because: > + not evidenced — there is no qualification state to reverse, since none can be recorded. + + - name: contact.normalize + fulfilment: absent + because: > + not evidenced — nothing documented rewrites records into a house format under a declared + rule set while keeping what was there before. Bulk updates through the import path can + overwrite values, which is not the same operation: it keeps no prior value and reports no + rule set, so nothing can be undone or explained afterwards. + + - name: identity_policy.define + fulfilment: partial + surface: contacts -> Import contacts + scopes: [contacts:write] + missing: > + The decision exists as an argument on each import — skip existing, which never overwrites, + or update existing — and nowhere else. There is no stored policy, no version, nobody + recorded as having set it, and the matching rules themselves are not configurable. Every + import re-decides the question, and two imports can disagree with nothing to notice it. + notes: > + Because the policy cannot live in the product, it has to be carried by whatever keeps the + user's durable context, and re-confirmed at each import rather than assumed from last time. + + - name: identity_policy.get + fulfilment: absent + because: > + not evidenced — there is no stored identity policy to read back, only the choice made on + each import, which is not recorded anywhere afterwards. + + - name: duplicate.list + fulfilment: absent + because: > + not evidenced — no documented surface reports suspected duplicates. Filtering can confirm + that two records share an address once you already suspect it; nothing proposes the clusters + in the first place, which is the entire operation. + + - name: duplicate.merge + fulfilment: absent + because: > + not evidenced — no documented surface combines two contact records into one. Deleting the + loser and updating the winner is not a merge: it destroys the history the contract requires + the merge to carry across, and there is no restore. + + - name: duplicate.link + fulfilment: absent + because: > + not evidenced — nothing records that two records are the same human while both have to stay. + + - name: duplicate.unlink + fulfilment: absent + because: not evidenced — there is no link to undo, since none can be made. + + - name: duplicate.reject + fulfilment: absent + because: > + not evidenced — no documented surface records a not-a-duplicate decision, so the same pair + would be proposed again by anything that looks a second time. + + - name: field.define + fulfilment: direct + surface: custom-fields -> Create a custom field, List all custom fields + scopes: [contacts:write] + notes: > + List first. A second field with almost the same name is how a mapping starts putting the + right value in the wrong place, and nothing downstream will notice. + + - name: field.retire + fulfilment: partial + surface: custom-fields -> Delete a custom field + scopes: [contacts:write] + missing: > + Delete, not retire, and nothing reports what still references the field before it goes. The + check the contract requires before repeating — is this still used by a mapping, a filter or + a template — has to be done by hand, and the documentation does not say what happens to the + values already stored. Treat the loss as total until somebody demonstrates otherwise. + + # ------------------------------------------------ 03 audience and lists + + - name: segment.define + fulfilment: absent + because: > + not evidenced — filters are expressed per call and no documented surface saves one under a + name. A contact list cannot stand in for a segment: it holds people, not a definition, it + does not re-evaluate, and it cannot say who would match tomorrow. + + - name: segment.get + fulfilment: absent + because: not evidenced — there is no saved definition to show, since none can be saved. + + - name: segment.list + fulfilment: absent + because: not evidenced — there are no saved definitions to list. + + - name: segment.delete + fulfilment: absent + because: not evidenced — there is nothing to retire. + + - name: segment.preview + fulfilment: direct + surface: > + contacts -> Count filtered contacts, Filter contacts; live-data -> Preview a Live Data + search + scopes: [contacts:read, contacts:write] + notes: > + Two universes, two surfaces, and the cost difference the contract describes is real here: + counting our own contacts is free, and the external preview adds no prospects and consumes + no credits either. The external half is Beta; the internal half is not. Run whichever + applies before anything that spends — this is the operation that makes the spend reviewable. + + - name: segment.materialize + fulfilment: composed + surface: > + contacts -> Filter contacts; contact-lists -> List contact lists, Create a contact list, Add + contacts to a contact list + scopes: [contacts:read, contacts:write] + order: > + contacts -> Filter contacts to evaluate the definition, then contact-lists -> Create a + contact list or reuse one from List contact lists, then Add contacts to a contact list, then + contacts -> Filter contacts by that list to reconcile what actually landed. + notes: > + The freeze is genuine but is not recorded as one: nothing on the list says which definition + or which as-of time produced it, so that has to be written down outside the product or the + list becomes a set of people nobody can account for. Say before you start that there is no + way to take people back off a list — see list_membership.remove — so a list built from the + wrong filter is corrected by building another one. + + - name: list.list + fulfilment: direct + surface: contact-lists -> List contact lists + scopes: [contacts:read] + notes: The first call before any list.create — reuse beats proliferation. + + - name: list.get + fulfilment: partial + surface: contact-lists -> Get a contact list, Get contact's lists; contacts -> Filter contacts + scopes: [contacts:read] + missing: > + What is on the list is readable; where it came from is not. Nothing records the definition, + the import or the search behind a list, so the second half of the question has no answer + here — and it must not be improvised from the list's name, which is the one place a wrong + answer will look plausible. + + - name: list_membership.add + fulfilment: direct + surface: contact-lists -> Add contacts to a contact list, Move contacts to a contact list + scopes: [contacts:write] + notes: > + Add and Move are different acts: Move takes people off wherever they were. Reconcile + afterwards by filtering contacts by the list, because the count asked for and the count that + landed differ often enough to matter. + + - name: list_membership.remove + fulfilment: absent + surface: contact-lists -> Move contacts to a contact list + because: > + not evidenced — the contact lists group documents adding and moving and nothing that takes a + person off a list. Move relocates people to another list rather than removing them, so using + it as a removal quietly files them somewhere else. This is the gap that makes a mis-built + list expensive, and the honest response is to get the list right before it is written rather + than to plan on trimming it. + + - name: list.delete + fulfilment: direct + surface: contact-lists -> Delete a contact list + scopes: [contacts:write] + notes: > + Check what still references it first — no campaign binding is reported back, and nothing + after the fact will tell you what broke. + + - name: audience.assess + fulfilment: absent + because: > + not evidenced — no documented surface judges whether a set of people is fit to work. + Duplicates cannot be listed, contactability is not modelled, and address verification is a + separate metered job over contacts rather than over a list. The assessment is therefore the + agent's own and has to be reported as a judgement, not as something the product checked. + + - name: audience.screen + fulfilment: absent + because: > + not evidenced — nothing re-checks a list against the exclusion rules and takes the failures + out. The blacklist rules can be read and a validation job can be run, but there is no + removal from a list at all, so the second half of the operation has nowhere to land. + + - name: contactability_policy.define + fulfilment: absent + because: > + not evidenced — the blacklist rules are individual exclusion entries for domains, addresses + and exceptions, not a policy answering send, hold or never_send per verdict and per flag. + Reporting them as one would leave every verdict the rules do not mention silently defaulting + to send, which is exactly the failure the policy exists to prevent. + + - name: contactability_policy.get + fulfilment: absent + because: > + not evidenced — there is no policy to read, only the individual blacklist entries. + + # ------------------------------------------------ 04 import + + - name: source.inspect + fulfilment: absent + because: > + not evidenced as an API surface, and rightly so — the file is inspected locally, before any + call, which is what the import ordering this skill already carried says: inspect the source + locally, zero API calls. There is no upload-and-profile endpoint and there does not need to + be. Do the inspection, then show the user what would land, then ask. + + - name: import.apply + fulfilment: composed + surface: contacts -> Import contacts, Filter contacts; background-jobs -> Get a background job + scopes: [contacts:write, other:read] + order: > + contacts -> Import contacts, then background-jobs -> Get a background job polled to a + terminal state, then contacts -> Filter contacts by the target list to reconcile created, + updated, skipped and failed against what was asked for. + notes: > + A large import returns a job reference, not a result: the operation completes when the job + reaches a terminal state, never when the call returns. A job that ends failed gets its body + read for the reason — never blind-retry a bulk write, because the first attempt may have + partially succeeded. The approval gate over the file, the count, the mapping, the dedupe + policy and the target list belongs before the first call. + + - name: import.list + fulfilment: partial + surface: background-jobs -> List background jobs + scopes: [other:read] + missing: > + There is no import history. Imports appear as background jobs among every other kind of job, + and the documentation does not say the listing can be filtered to imports, so the question + is answered by reading a general job list and recognising them. Anything older than that + listing retains is simply gone. + + - name: import.get + fulfilment: partial + surface: background-jobs -> Get a background job + scopes: [other:read] + missing: > + A job is identified by its own id, not by an import record, and the documentation does not + state that the result carries a per-row ledger tying each source row to the contact it + created or matched. Keep that reconciliation yourself at import time — after the fact it may + not be recoverable at all. + + - name: import.revert + fulfilment: absent + because: > + not evidenced — nothing undoes an import. Bulk deleting the contacts is not a revert: it + destroys people the import updated rather than created, and it cannot put back a field the + import overwrote. Say the import is not reversible before it runs, which is the only moment + at which saying it helps anyone. + + # ------------------------------------------------ 05 campaign, schedule, windows and limits + + - name: campaign.list + fulfilment: partial + surface: > + sequences -> List all sequences, Count sequences; sequence-folders -> List sequences in a + folder + scopes: [sequences:read] + missing: > + State comes back; health does not. Nothing in the listing separates a campaign that is fine + from one that is not progressing, degraded or blocked, so "what is running, and what is + quietly broken" needs a second pass over stats and sender health — and that verdict is this + adapter's judgement, not a field it read. + + - name: campaign.create + fulfilment: direct + surface: sequences -> Create a sequence, List all sequences + scopes: [sequences:write] + notes: > + Creating never arms anything: the new sequence comes back in a new state and starting it is + a separate call with a separate approval. List first — reuse is usually right, and a + fourteenth near-identical campaign is how a mailbox ends up sending to the same person from + three directions. + + - name: campaign.clone + fulfilment: composed + surface: > + sequences -> Save a sequence as a template, Create a sequence from a template; + sequence-templates -> List all sequence templates + scopes: [sequences:write] + order: > + sequences -> Save a sequence as a template, then Create a sequence from a template. Check + sequence-templates -> List all sequence templates first in case the template already exists. + notes: > + The template route carries structure and content and not enrolments, history or results, + which is what the contract asks of a clone. Read the new campaign back and confirm the + schedule and sender bindings came with it before assuming they did. + + - name: campaign.update + fulfilment: partial + surface: sequences -> Update a sequence, Change sequence owner + scopes: [sequences:write] + missing: > + Owner moves through its own endpoint, so one conceptual update is two calls. Beyond that + there is no declared successor and no personalisation tier on the sequence: a campaign that + hands over to another one cannot say so here and has to be tracked outside the product. + notes: > + The update is last-write-wins — read the campaign first, or a field nobody meant to touch is + reverted by a call that only meant to change the name. The owner endpoint is separate and + may carry its own scope; take it from its page. + + - name: reply_policy.set + fulfilment: partial + surface: sequences -> Update a sequence + scopes: [sequences:write] + missing: > + One switch, not a decision per event class: a reply either finishes the person or sending + continues, and that is the whole vocabulary. There is no per-event-class routing and no + attribution window, so "a reply within thirty days still counts as this campaign's" cannot + be expressed at all. + notes: > + Continuing to send after a reply is the setting that keeps writing to somebody who already + answered. The contract raises this to confirm_once for exactly that reason, and learning it + is one field on an update endpoint changes nothing about the confirmation. + + - name: schedule.set + fulfilment: partial + surface: > + schedules -> Create a schedule, Update a schedule, Set default schedule; sequences -> Update + a sequence to attach it + scopes: [sequences:write] + missing: > + Windows per day and the timezone policy are there, including sending in the prospect's own + timezone rather than the schedule's. A delay basis and an out-of-window behaviour are not: + nothing states whether a touch falling outside a window defers to the next open one or is + skipped, so the defer-or-skip decision the contract makes the user take has no setting to + carry it. Holidays are all-or-nothing per schedule. + notes: > + Two calls: create or update the schedule, then attach it through the sequence update. A + schedule is a shared object, so changing one silently rewrites every future date on every + campaign pointing at it — which is the damage the contract's confirm_once is guarding + against. Check who else uses it before editing rather than after. + + - name: pacing.set + fulfilment: partial + surface: sequences -> Update a sequence + scopes: [sequences:write] + missing: > + People admitted per day, messages per day and a minimum gap between sends all exist, and so + does a same-domain cap the contract does not ask for. Jitter and the cold-start ramp do not: + a new campaign runs at its full configured rate from day one unless somebody raises the + numbers by hand over several days, and nothing records that they intended to. + notes: > + These are per-campaign, which is the point of the operation — slowing this campaign without + slowing everything else on the same mailbox. Ceilings that belong to the sending capability + itself are set elsewhere and are not reachable from here. + + - name: sender_binding.set + fulfilment: partial + surface: > + sequence-email-accounts -> Assign email account to sequence, Set sequence email accounts, + Remove email account from sequence; sequence-linkedin-accounts -> Assign a LinkedIn account + to a sequence + scopes: [sequences:operate] + missing: > + Binding is per campaign only — named participations cannot be bound. And the documentation + does not say what happens to people already mid-campaign when the binding changes, so the + preview the contract requires, the one telling a user which live threads are about to change + From address, cannot be produced from this API. + notes: > + Because the live-participation behaviour is undocumented, treat a rebinding on a running + campaign as an act with an unknown blast radius: pause, rebind, read back, resume. Confirm + the sender is healthy before binding it to anything. + + - name: campaign.validate + fulfilment: absent + because: > + not evidenced — no documented surface answers whether a campaign is safe to turn on. The + pieces a validation would read do exist separately, as steps, sender assignments, the + schedule and the enrolled count, so the check is assembled by the agent out of several reads + and reported as its own work. Never report it as something the product verified: an + unpublished template or a schedule that never opens will not announce itself. + + - name: campaign.test + fulfilment: partial + surface: email-templates -> Send a test email, Render an email template + scopes: [sequences:operate] + missing: > + It tests a template, not the campaign. There is no surface that sends step one exactly as a + real contact would receive it, the documentation places no restriction on the recipient + address, and nothing checks that the unsubscribe mechanism in the message actually works. + The contract's test — receive it yourself, click the unsubscribe link, and only to an + address the workspace can demonstrate it owns — is only partly reachable. + notes: > + A test send is still a send and still metered, so the contract's confirm_each stands. Say + which parts were tested and which were not, rather than reporting a green test. + + - name: campaign.resume + fulfilment: direct + surface: sequences -> Start a sequence, Bulk start sequences + scopes: [sequences:operate] + notes: > + The same endpoint as activation, so it will not refuse a campaign that was never paused the + way the contract says a resume should. Read the state first and decide which operation you + are actually performing: the two carry different approvals, and only one of them is a first + activation. + + - name: campaign.freeze + fulfilment: partial + surface: > + sequences -> Pause a sequence; or holiday-calendars -> Create a holiday calendar with + schedules -> Link a holiday calendar to a schedule + scopes: [sequences:operate, sequences:write] + missing: > + Neither route is a freeze. A pause carries no expiry and never resumes itself, so the thing + that makes a freeze safe — that somebody forgetting about it is not a failure — is gone. A + dated holiday calendar does expire by itself, but it suppresses at the schedule, and a + schedule may be shared by campaigns nobody meant to stop. + notes: > + Say which route was taken and what it costs. A pause leaves the resume as a human's job, so + it belongs in whatever carries work across sessions rather than in someone's memory. A + linked calendar needs a check of which other campaigns point at that schedule, before + linking. + + - name: campaign.unfreeze + fulfilment: partial + surface: > + sequences -> Start a sequence; or schedules -> Unlink a holiday calendar from a schedule + scopes: [sequences:operate, sequences:write] + missing: > + No preview of what letting it go early releases. The contract wants the count of messages + that go out the moment the suppression lifts, and nothing here produces one, so the user is + approving a release whose size nobody has been told. + notes: > + Work the release out from the enrolled counts and the pacing before asking for the + confirmation, and say out loud that the number is an estimate rather than a reading. + + - name: campaign.archive + fulfilment: direct + surface: sequences -> Archive a sequence, Bulk archive sequences + scopes: [sequences:operate] + notes: > + Refuses with a conflict when the campaign is already archived or in an incompatible state, + and the documentation does not enumerate those states — so read the campaign back rather + than inferring what the conflict meant. Stop live enrolments with a reason first, as the + contract requires. + + - name: campaign.unarchive + fulfilment: direct + surface: sequences -> Unarchive a sequence, Bulk unarchive sequences + scopes: [sequences:operate] + notes: > + Bringing it back into the working set does not start it sending. That is a separate call and + a separate decision, and the contract keeps them apart for a reason. + + - name: schedule.resolve + fulfilment: absent + because: > + not evidenced — nothing documented returns a resolved calendar. The schedule can be read and + so can a linked holiday calendar, but the day-by-day answer for a campaign or for one + person, showing what a weekend, a holiday or a closed window moved, has to be computed and + cannot be checked against anything. + + - name: send_window.resolve + fulfilment: absent + because: > + not evidenced — no documented surface answers when one person may be contacted on one + channel. Some inputs are readable, being the schedule's windows, its timezone policy and its + linked holiday calendars, but legal quiet hours in the recipient's local time and operator + blackouts are not modelled at all, so the parts that carry legal weight are the ones missing. + + - name: blackout.define + fulfilment: partial + surface: > + holiday-calendars -> Create a holiday calendar, Update a holiday calendar; schedules -> Link + a holiday calendar to a schedule + scopes: [sequences:write] + missing: > + Named date ranges exist, with an annual-repeat flag. Defer-or-skip does not: nothing states + whether the touches a range stops come back afterwards or are lost, which is half of what + the contract asks the user to decide. Nor does the create call take the region the range + applies to, so whose region applies cannot be stated at the moment the range is drawn. + notes: > + A calendar suppresses nothing until it is linked to a schedule, and it then applies to every + campaign on that schedule. Linking is the act; creating is not, and reporting the create as + the blackout is how a holiday range ends up suppressing nothing. + + - name: blackout.list + fulfilment: composed + surface: > + holiday-calendars -> List holiday calendars; schedules -> List linked holiday calendars + scopes: [sequences:read] + order: > + holiday-calendars -> List holiday calendars for everything defined, then, for each schedule + a campaign in scope actually uses, schedules -> List linked holiday calendars. An unlinked + calendar suppresses nothing and must not be reported as suppression in force. + notes: > + This answers which ranges are in force and until when for the campaigns you name, not + account-wide in one call. State the scope you checked, because the difference between "no + blackouts" and "no blackouts on the two campaigns I looked at" is the whole answer. + + - name: blackout.remove + fulfilment: partial + surface: > + schedules -> Unlink a holiday calendar from a schedule; holiday-calendars -> Delete a + holiday calendar + scopes: [sequences:write] + missing: > + The lift itself works. The preview does not: nothing says whether removing a range opens a + window that is open right now on a live campaign, or how many messages go out as a result — + and that preview is what the contract uses to decide whether this is an act at all. Here it + has to be reasoned out instead of read. + notes: > + Unlink lifts the suppression for one schedule; delete removes the calendar from every + schedule that used it. They are different-sized acts, and the user should be told which one + is being proposed before they agree to it. + + - name: frequency_policy.define + fulfilment: absent + because: > + not evidenced — no documented surface caps how often one person, account or domain hears + from us across campaigns. The per-campaign same-domain limit is the nearest thing and is a + different promise: one campaign's contacts-per-domain-per-day, not a cross-campaign, + cross-channel cap. Offering it as one would let three campaigns touch the same person in a + day while the limit reports as respected. + + - name: frequency_policy.get + fulfilment: absent + because: > + not evidenced — there is no cap to read, since none can be defined, and the per-campaign + same-domain limit answers a different question. + + - name: capacity.estimate + fulfilment: absent + because: > + not evidenced — nothing projects whether a plan can physically run. Sending capacity, pacing + and existing load are each readable somewhere, but no surface puts them against a planned + volume over a stated horizon. Any answer is the agent's own arithmetic over several reads + and has to be reported that way, with the reads it rests on named. + + # ---------------------------------------------------- families 12-16, 91 operations + # Signals and triggers · inbound · consent, suppression and privacy · sending capability + # and deliverability · social and messaging channels. + # + # Evidence: the 1.1.0 mapping this skill carried, the documentation index, and the pages + # named below read directly. Most of this range is `absent`, which is the honest result: + # the contract describes the whole job and no product covers all of it. + + # ------------------------------------------------------------ 12 — signals and triggers + + - name: signal.list + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing reports that someone + changed job, visited a page, raised funding or engaged publicly. + notes: > + ai-sdr-intent-signals -> Industries typeahead, Technologies typeahead is the nearest + thing and it is not this: it resolves the words a user says into values a prospect + search accepts. Offering it here answers a different question than the one asked. + + - name: signal.get + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Without a feed there is + nothing to read one observation from. + + - name: signal.acknowledge + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: signal_policy.define + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing arbitrates between + two things firing on the same person, because nothing fires. + + - name: signal_policy.get + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: trigger.create + fulfilment: partial + surface: webhooks -> Create a webhook subscription, List supported event types + scopes: [webhooks:write, webhooks:read] + missing: > + Only the watching half. A subscription delivers a named event to a listener outside the + product; the rule's other half — producing work in response — has no surface, so the + acting side must live in the agent runtime. The watchable set is fixed and product-side + (message sent, opened, clicked, replied, bounced; contact opted out or finished; + connection request sent and accepted; account connection lost or erroring), so a rule + that must watch something outside that set cannot be expressed at all. + notes: > + Read List supported event types before promising a rule — the event names are the whole + vocabulary, and a trigger written against an event that is not on that list will never + fire rather than failing loudly. + + - name: trigger.update + fulfilment: partial + surface: > + webhooks -> Update a webhook subscription, Enable a webhook subscription, + Disable a webhook subscription + scopes: [webhooks:write, webhooks:operate] + missing: > + The same half as trigger.create: what the rule watches can be changed, what it produces + cannot, because production is not in the product. + notes: > + "Switch it off without losing it" maps exactly onto Disable, which is the reversible + move. Deleting a subscription to stop it and re-creating it later is not the same act + and loses the subscription's history. + + - name: trigger.list + fulfilment: partial + surface: webhooks -> List webhook subscriptions, List supported event types + scopes: [webhooks:read] + missing: > + What each rule watches is listed; what it produces is not, and cannot be, since the + producing half is external. Report the watch, and say plainly that the action behind it + is the runtime's and not the product's. + + - name: trigger.delete + fulfilment: partial + surface: webhooks -> Delete a webhook subscription + scopes: [webhooks:write] + missing: > + Removes the watch only. Whatever the agent runtime built on top of that event keeps + existing and has to be taken down separately, or it becomes a rule waiting on an event + that will never arrive again. + + - name: trigger_run.list + fulfilment: partial + surface: webhooks -> Get webhook delivery logs + scopes: [webhooks:read] + missing: > + Deliveries, not runs. The log says which event fired and whether it reached the + listener; what work came out of it and what a policy held back are not recorded, because + neither the work nor the policy exists on this side. Never report a delivery count as a + count of work done. + + # -------------------------------------------------------------------------- 13 — inbound + + - name: inbound_lead.record + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is no inbound-lead or + form-capture group: an arrival has nowhere to be recorded as an arrival, with the clock + the rest of this family depends on. + notes: > + Do not simulate the queue out of tasks, contact owners or inbox categories. Those + entities have their own meanings and their own operations, and an arrival modelled as a + task loses the one thing that made it an arrival — the response clock. + + - name: inbound_lead.list + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: inbound_lead.get + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: inbound_lead.route + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is no routing rule — + territory, existing owner, round-robin or availability — anywhere in the documentation. + notes: > + Contact and account ownership can be changed, but changing an owner is not routing an + arrival: it carries no rule, no queue and no clock, and reporting it as routing would + claim a guarantee that was never made. + + - name: inbound_lead.claim + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: inbound_lead.release + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: inbound_lead.triage + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing classifies what kind + of request an arrival is. + notes: > + Inbox categories classify reply threads on conversations we started. That is a different + act on a different entity, and it is covered by its own contract operation. + + - name: inbound_lead.close + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: inbound_lead.reopen + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: response_policy.define + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No response target can be + stated, so none can be measured or breached. + + - name: response_policy.get + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + # ------------------------------------------ 14 — consent, suppression and privacy + + - name: outreach.precheck + fulfilment: partial + surface: > + contacts -> Get a contact's statuses; + contact-blacklist-rules -> List email blacklist rules, List domain blacklist rules, + List email exception blacklist rules + scopes: [contacts:read] + order: > + Read the contact's statuses first — the opted-out state is a global flag there, and a + person opted out is a stop with no further questions. Then search the email rules for + the address and the domain rules for its domain. Read the exception rules as well: a + match on a domain rule is not final on its own. + missing: > + It answers one question — is this person opted out or excluded on email — and the + operation asks four. There is no channel dimension, so a social or phone precheck is not + covered. There is no timing half, so "if not, when" cannot be answered. There is no + consent basis and no external-register gate. Nothing says what would fix it. Say all of + this before a user commits to a route that treats the precheck as sufficient. + notes: > + The result is stale the moment it returns, here as in the contract. Nothing about + knowing which endpoint answers it changes that. + + - name: suppression.check + fulfilment: partial + surface: > + contact-blacklist-rules -> List email blacklist rules, List domain blacklist rules, + List email exception blacklist rules + scopes: [contacts:read] + missing: > + The "why". A rule carries its pattern and whether it is system-wide, and nothing else — + no reason class comes back, so the answer is yes-or-no with no ground for it. Only email + addresses and domains are covered; a number, a social profile or a whole account has no + equivalent. + notes: > + The listings filter by pattern, so a raw identifier can be checked without it being a + contact in the system — which is the part of this operation that matters. + + - name: suppression.list + fulfilment: partial + surface: > + contact-blacklist-rules -> List email blacklist rules, List domain blacklist rules, + List email exception blacklist rules + scopes: [contacts:read] + missing: > + Three separate lists rather than one, and none of the three facets the operation + promises: no scope, no reason class, no record of who added the entry. Numbers, social + profiles and whole accounts are not represented at all. + + - name: suppression.add + fulfilment: partial + surface: > + contact-blacklist-rules -> Create an email blacklist rule, Create a domain blacklist + rule, Bulk create email blacklist rules, Bulk create domain blacklist rules + scopes: [contacts:write] + missing: > + "And here is why" has nowhere to go — no reason is recorded against a rule, so the + reason has to be kept in the agent's own record or it is lost, and suppression.remove + later has nothing to weigh. Numbers, social profiles and whole accounts have no + equivalent. + notes: > + The contract's read-before-repeating has a real surface here: search the listing for the + pattern first. Adding a pattern that already exists is a refusal, so a blind retry is + wrong. + + - name: suppression.remove + fulfilment: partial + surface: > + contact-blacklist-rules -> Delete an email blacklist rule, Delete a domain blacklist + rule, Bulk delete email blacklist rules, Bulk delete domain blacklist rules + scopes: [contacts:write] + missing: > + The evidence that licenses the lift is not recorded, and no retention floor is exposed + to check against — so the one guard the contract puts on this irreversible act cannot be + enforced by the product and must be enforced by the agent before the call. Email + addresses and domains only. + + - name: optout.record + fulfilment: partial + surface: > + contact-blacklist-rules -> Create an email blacklist rule, Bulk create email blacklist + rules + scopes: [contacts:write] + missing: > + It records the exclusion, not the act. What they said, where it arrived, when they did + it and when we learned of it have nowhere to go, so the evidence that this was their + decision is not retained. The product carries its own opted-out state on a contact — + readable through Get a contact's statuses — but no documented surface sets it. + notes: > + This is the protective floor operation: recording that somebody said stop is performed + first and reported immediately. A blacklist rule stops future sends, which is the effect + that matters most; keep the act itself in the agent's own record alongside it. + + - name: optout.poll + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing pulls un-ingested stop + signals from the channel — one-click unsubscribes, list-unsubscribe requests, blocks or + stop keywords. + notes: > + The notification surface carries a contact-opted-out event. That is a push about an + opt-out the product has already ingested, not the backlog of ones it has not, and the + two are not interchangeable: subscribing to it tells you nothing about what is waiting + at the channel. + + - name: optout.confirm + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No opt-out confirmation exists + as its own act, and no ledger records whether one was already sent. + notes: > + A direct email to a contact can be sent, and using it for this is the substitution to + refuse. This confirmation is exactly-once, non-promotional and may never require + anything of the recipient; with no ledger to check, a second one is a breach rather than + a duplicate, and nothing here would stop it. + + - name: consent.record + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is no permission record: + what they were told, when, how it was captured and what it covers have nowhere to live. + + - name: consent.revalidate + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. With no basis recorded there + is nothing to recompute and no contactability to downgrade. + + - name: consent.prove + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: notice.send + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Neither the delivery of a + privacy notice nor the record that it was delivered has a surface. + + - name: disclosure.check + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: disclosure.record + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing binds a disclosure to + the message that carried it. + + - name: dnc_registry.check + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No external do-not-contact + register is reachable from here; the blacklist rules are our own list, not a + jurisdiction's. + + - name: privacy_request.create + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is no privacy-request + entity, so no clock starts and nothing later can be tied to a request. + + - name: privacy_request.update + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: privacy_request.refuse + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: privacy_request.fulfill + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is no recorded request + to fulfil against, and no export of everything held about a person. + notes: > + Contacts can be deleted, singly and in bulk. That is contact.delete, a different + contract operation with a different meaning, and performing it must never be reported as + fulfilling a privacy request: the request record is the whole point of this operation + and it does not exist here. + + - name: deletion_feed.poll + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No external erasure register + is reachable from here. + + - name: deletion_feed.report + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: retention.apply + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No storage limit can be stated + or enforced, and no floor is exposed to stop at. + + - name: audit_log.search + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is no audit surface: who + changed what, when, on our side is not answerable. + notes: > + A contact's activity history is the record of outreach that touched that contact. It is + not a record of our own changes, and it cannot answer why this person was contacted at + all — which is the harder half of the question and the one that gets asked under + pressure. + + # -------------------------------------- 15 — sending capability and deliverability + + - name: sender.list + fulfilment: partial + surface: > + email-accounts -> List email accounts, Filter email accounts; + linkedin-accounts -> List LinkedIn accounts, List pending LinkedIn accounts + scopes: [channels:read] + missing: > + Two lists rather than one, and only two of the four capability classes. Mailboxes and + social accounts are covered; numbers and business messaging identities have no group at + all, so a channel the user asks about may be invisible rather than empty. + notes: > + Merge the two and label every row with its channel, or the caller cannot tell what it is + looking at. Read the pending social list too: a half-finished connection must read as + pending setup, never as absent, and leaving it out is how a sender that is nearly ready + gets connected a second time. + + - name: sender.get + fulfilment: partial + surface: > + email-accounts -> Get an email account; + linkedin-accounts -> Get a LinkedIn account + scopes: [channels:read] + missing: > + Identity, channel and configured pacing come back. Pool membership and registration do + not, because neither concept exists here — see sender_pool.* and + messaging_registration.*. Mailboxes and social accounts only. + + - name: sender.health + fulfilment: partial + surface: > + email-accounts -> Get an email account, Test SMTP connectivity, Test IMAP connectivity; + linkedin-accounts -> Get a LinkedIn account + scopes: [channels:read, channels:operate] + missing: > + Connection state and configured limits are readable, and the mailbox read reports + whether the provider has locked or throttled the account. Warm-up position, the + channel's automation sanction, and any statement of how much of today's capacity is + still available are not exposed — so three of the five things this operation promises + have to be tracked by the agent or left unanswered. Numbers and business messaging + identities are not covered. + notes: > + The connectivity tests verify the credential actively rather than reporting a cached + status, which is the difference that matters when an account looks fine and is not. + A disconnected or erroring account is still a hard stop: this is a core operation and + the launch chain refuses on it. + + - name: sender.connect + fulfilment: partial + surface: > + email-accounts -> Create an email account, Connect Gmail account via OAuth, + Connect Office 365 account via OAuth; + linkedin-accounts -> Create a connection link, Create a direct connection link + scopes: [channels:write] + missing: > + Mailboxes and social accounts only; numbers and business messaging identities have no + surface. On the social channel the call produces a link a person has to complete, so the + operation is not finished when the call returns. + notes: > + Poll the pending social list until the account appears in the real one. Until then it is + the contract's pending-setup state, and reporting it as connected is how a campaign gets + launched against a sender that cannot send. + + - name: sender.disconnect + fulfilment: partial + surface: > + email-accounts -> Delete an email account, Bulk delete email accounts; + linkedin-accounts -> Delete a LinkedIn account, Bulk delete LinkedIn accounts + scopes: [channels:write] + missing: > + It deletes rather than detaches, and the guard the contract puts on this operation is + absent: nothing refuses while live enrolments or open conversations still depend on the + sender, and no rebind target can be supplied. The check is the caller's, and it has to + happen before the call because there is nothing to undo afterwards. + notes: > + What is bound to a sender is readable only one campaign at a time + (sequence-email-accounts -> List email accounts in sequence; sequence-linkedin-accounts + -> List LinkedIn accounts for a sequence), so the check is a scan. On the social channel + sender.pause is the reversible alternative and is usually what the user actually wants. + + - name: sender.reauthorize + fulfilment: partial + surface: > + linkedin-accounts -> Reconnect a LinkedIn account; + email-accounts -> Connect Gmail account via OAuth, Connect Office 365 account via OAuth + scopes: [channels:write] + missing: > + Only the social channel has a reconnect that names the existing account. On a mailbox + the documented route is re-running the provider connection, and nothing states that the + history behind it survives — which is the whole promise of this operation. Verify by + re-reading rather than assuming, and tell the user what you could not confirm. + + - name: sender.pause + fulfilment: partial + surface: linkedin-accounts -> Toggle LinkedIn account status + scopes: [channels:operate] + missing: > + Social accounts only. A mailbox has no documented pause — the resume surface exists with + no counterpart — so on email the protective move has to be made one level up, at + campaign.pause or by removing the sender from the campaign. Say which one you used, + because they are not the same blast radius. + notes: > + The social call flips between enabled and disabled rather than setting a state. Read the + account first: issued blind against an already-paused account it re-enables it, which + turns the first move in an incident into the worst one. + + - name: sender.resume + fulfilment: partial + surface: > + email-accounts -> Resume sending; + linkedin-accounts -> Toggle LinkedIn account status + scopes: [channels:operate] + missing: > + Nothing refuses the resume on an invalid warm-up position, because no warm-up position + is exposed at all — the contract's guard has to be enforced by the caller or it is not + enforced. The mailbox surface is scoped to accounts the provider locked or throttled, + not to an operator pause, and no operator pause exists on that channel. + notes: > + Resolve the underlying problem before calling, then re-read the account to confirm the + lock actually cleared. The social call flips rather than sets — read state first, same + as with sender.pause. + + - name: sender_limit.set + fulfilment: partial + surface: > + linkedin-accounts -> Update LinkedIn account limits; + email-accounts -> Update an email account + scopes: [channels:write] + missing: > + The contract's one decision is two different surfaces, one per channel, and only the + social one is a dedicated limits endpoint — on a mailbox the limits ride on the account + update, so a careless call can overwrite settings the caller did not intend to touch. + Numbers and business messaging identities have no surface. + notes: > + Read the limits in force first and re-read after: report what actually took, not what + was requested. Lowering is protective; raising is the direction that needs the approval, + and the mapping does not change that. + + - name: warmup_plan.set + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No ramp can be defined, read + or started, and no warm-up position is exposed anywhere in the API. + notes: > + This is the absence that costs the most in this family: sender.resume refuses on the + warm-up position, and with no position readable that refusal cannot be automated. Tell + the user the ramp is theirs to hold, and hold it in the agent's own record. + + - name: message_element.set + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. The legal identification + block, the postal address, the channel's stop artefacts and the tracking domain have no + per-sender configuration surface. + + - name: sender.reserve + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is no allowance + reservation, so two parallel runs against one sender can spend the same capacity twice + and neither will be told. + + - name: sender.release + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing to give back, since + nothing can be claimed. + + - name: sender.summarize + fulfilment: absent + surface: email-accounts -> Get email account stats, Filter email account stats + because: > + The per-sender figures surface is documented Coming soon and is not callable today. Say + that rather than reaching for something adjacent, and check the page again before + planning around it. + notes: > + The reporting overview is account-wide, not per sender, and answers a different + question. Substituting it produces a number that looks like this sender's and is not, + which is worse than having none. Even when the stats surface opens, failures by class, + complaints with their publisher and denominator, deferrals and throttles are not + promised by it. + + - name: restriction.record + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is no restriction + ledger, so a restriction cannot be recorded, counted, or carried forward. + notes: > + The arrival of one is observable — the notification surface carries account-alert, + connection-lost and account-error events, and the mailbox read reports a provider lock. + What is missing is the durable record behind them. Keep it in the agent's own record: + the recurrence count and the invalidated warm-up position both hang off it, and + platforms escalate on how often a sender is restricted rather than on what for. + + - name: restriction.appeal + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No appeal route is exposed; + where the platform offers one it is outside this API, and saying so plainly is the + correct answer. + + - name: sender_pool.create + fulfilment: partial + surface: > + sequence-email-accounts -> Set sequence email accounts, Assign email account to + sequence; + sequence-linkedin-accounts -> Assign a LinkedIn account to a sequence + scopes: [sequences:read, sequences:operate] + missing: > + There is no pool object. The grouping exists only as the set of senders bound to one + campaign, so it cannot be named, cannot be created before the campaign exists, and + cannot be reused by a second campaign without being rebuilt. Routing policy is not part + of it. + notes: > + Rotation across the bound senders is the product's own behaviour, so do not tell a user + that sending across several senders is unavailable — that is a wrong answer, not a + cautious one. What is unavailable is the reusable, named, independently routable pool. + + - name: sender_pool.update + fulfilment: partial + surface: > + sequence-email-accounts -> Set sequence email accounts, Assign email account to + sequence, Remove email account from sequence; + sequence-linkedin-accounts -> Assign a LinkedIn account to a sequence, Remove a LinkedIn + account from a sequence + scopes: [sequences:read, sequences:operate] + missing: > + Membership changes, one campaign at a time. The routing policy does not — and sticky per + recipient in particular is not selectable, which on a conversational channel is + correctness rather than optimisation. Say that before a user commits to a route that + needs a recipient to keep hearing from the same sender. + notes: > + Setting the whole set replaces it. Read the current members first, or a call meant to + add one sender silently removes the rest. + + - name: sender_pool.list + fulfilment: partial + surface: > + sequence-email-accounts -> List email accounts in sequence; + sequence-linkedin-accounts -> List LinkedIn accounts for a sequence + scopes: [sequences:read] + missing: > + Pools cannot be enumerated. Every read is scoped to one campaign, so "what pools exist" + is answerable only by walking every campaign, and how work routes across the members is + not reported at all. + + - name: sender_pool.delete + fulfilment: partial + surface: > + sequence-email-accounts -> Remove email account from sequence; + sequence-linkedin-accounts -> Remove a LinkedIn account from a sequence + scopes: [sequences:read, sequences:operate] + missing: > + There is no pool to dissolve. Removing every binding leaves the campaign with no sender + rather than dissolving a named group — nothing refuses it while the campaign is live and + no replacement target can be supplied, so the campaign is left unable to send and + nothing says so. + notes: > + The capabilities themselves are untouched, as the contract expects: this removes + bindings, not senders. + + - name: sending_domain.register + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Domains are not a first-class + entity here; a sender carries its address and that is all. + + - name: sending_domain.list + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: sending_domain.retire + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: authentication_requirement.list + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. What has to be published for a + domain to authenticate is not stated anywhere in the API. + + - name: domain_compliance.check + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No verdict per publisher and + per requirement is available, so a failing requirement cannot be named. + + - name: domain_reputation.get + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No reputation signal, + blocklist listing or dataset is exposed. + + - name: message_compliance.check + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing evaluates a rendered + message against what it will be held to: required elements, a working unsubscribe, or + the reputation of the domains it links to. + notes: > + The rendered message itself can be obtained (email-templates -> Render an email + template, Send a test email), so the check can be performed outside the product against + a real rendering rather than against the source. That is worth doing, and it is not this + operation — report it as an external check. + + - name: placement_test.create + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is no seed-list send and + no per-provider placement result. + notes: > + The email-validation surface estimates and schedules address validation. That answers + whether an address exists, never where a message lands, and offering it here would + answer a deliverability question with a data-quality one. + + - name: placement_test.get + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: messaging_registration.submit + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No brand or use-case + registration exists, because the channels that require one before any send is permitted + are not represented in this API. + + - name: messaging_registration.get + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: approved_content.submit + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No content is submitted to a + platform for pre-approval. + notes: > + The pending-approval surface in the AI-SDR cluster is a person inside the organisation + approving generated content before it sends. This operation is a platform gating content + before we are permitted to send it at all. They are different actors with different + consequences for refusal, and mapping one onto the other would report an internal + sign-off as a platform's permission. + + - name: approved_content.get + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: approved_content.retire + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + # ---------------------------------------------- 16 — social and messaging channels + + - name: social_invitation.send + fulfilment: direct + surface: direct-outreach -> Send a LinkedIn connection request to a contact + scopes: [contacts:operate] + notes: > + The optional note is supported, and that is exactly why the contract's confirm_each + applies: it is content addressed to one named person, so the literal text is approved + before the call, not a description of it. The person must already be a contact carrying + a profile URL, and the caller names which connected social account sends it — so + sender.health comes first. The send happens outside any campaign, which means campaign + pacing does not apply to it and the daily invitation limit has to be respected by the + caller; see linkedin-guardrails for the pacing this operation is subject to. + The contract's read before repeating — the invitation state for this pair — has no + surface here, because social_invitation.list is absent. Keep that ledger in the agent's + own record, or a retry becomes a second invitation to somebody who already has one. + + - name: social_invitation.list + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Invitations sent cannot be + listed, so neither what is pending nor how old it is can be answered. + notes: > + The pending social-account listing is a different thing despite the similar name: it is + accounts waiting to finish connecting to the product, not invitations waiting on people. + Confusing the two produces a confident answer to a question nobody asked. + + - name: social_invitation.withdraw + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. A sent invitation cannot be + taken back through the API. + + - name: social_invitation.accept + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: social_invitation.decline + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: social_relationship.get + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing answers, on demand, + whether we are connected to this person or at what degree. + notes: > + The notification surface reports connection requests sent and accepted, so a standing + relationship ledger can be maintained outside the product from those events. That is a + ledger the agent builds and owns; it is not a read, and it knows nothing about people we + never invited. + + - name: social_profile.view + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No profile read is exposed, + metered or otherwise. + + - name: social_profile.follow + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: social_profile.unfollow + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: social_post.react + fulfilment: absent + because: not evidenced — no documented surface was found for this. + + - name: social_post.comment + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. No published content can be + posted under a person's identity through this API. + + - name: social_credit.get + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. The metered messaging + allowance is not readable: how many credits remain, when they expire and whether a reply + returns one are all unanswerable. + notes: > + A metered message can be sent without any way to check the balance first, so the meter + is discovered by exhausting it. Warn the user before planning volume that depends on it. + + - name: conversation_window.get + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing reports whether this + person may be written to freely right now, only with pre-approved content, or only by + spending a credit. + notes: > + Both routes exist as sends — an ordinary message and a metered one — but nothing says + which is permitted for a given person, so the choice is the caller's and a wrong one + fails at send time rather than at planning time. That is a real cost to surface before + the user commits to a social route. + + # ------------------------------------------------------- family 6 — steps, content, content policy + + - name: step.list + fulfilment: direct + surface: sequence-steps -> List all sequence steps, Get a sequence step + scopes: [sequences:read] + notes: > + The step carries its own execution mode, which is what tells you which steps owe a human + rather than going out on their own. + + - name: step.add + fulfilment: partial + surface: sequence-steps -> Create a sequence step, Bulk create sequence steps + scopes: [sequences:write] + missing: > + Position is not settable. The create body has no position, order or index field, so a step + lands after the ones already made and no reorder endpoint exists to correct it. Content is + inline on the step rather than bound to a template version, so a step cannot reference + published copy. A branch is expressed as a condition step plus a parent reference and a + positive-or-negative flag, and the evaluation window and early-satisfaction behaviour the + contract asks for have no field at all. + notes: > + Channel and kind arrive together as one discriminated type — email, LinkedIn with its own + action subtype, call, SMS, WhatsApp, task, condition — and the delay is a single minutes + value, so the contract's unit and basis have to be reduced to minutes before the call. + Complex step work, notably variants on a live sequence and LinkedIn steps, is often better + handed to the product's own editor than approximated here. Say so and hand off rather than + guessing. + + - name: step.update + fulfilment: partial + surface: sequence-steps -> Update a sequence step + scopes: [sequences:write] + missing: > + The step type is a discriminator and cannot be changed, so moving a step to another channel + means delete and re-add, which loses the step's variants with it. Position is out of reach + here for the same reason it is in step.add. + notes: > + A full replacement rather than a patch — read the step first and resend every field you are + not changing, or the delay and the copy you left out are gone. Nothing in the documentation + restricts the call while the sequence is live, so the in-flight statement the contract + requires is the agent's obligation and not the API's. + + - name: step.remove + fulfilment: direct + surface: sequence-steps -> Delete a sequence step, Bulk delete sequence steps + scopes: [sequences:write] + notes: > + Takes the step's variants and their history with it. Re-read the step list afterwards — an + absent step is a completed removal, not a failure. + + - name: step.reorder + fulfilment: absent + because: > + Neither Create a sequence step nor Update a sequence step exposes a position, order or index + field, and no reorder endpoint is documented. Steps sit in the order they were created. + Delete and re-add is not a substitute — it destroys variants and their measurement history, + which is the exact loss this operation exists to prevent. + + - name: variant.add + fulfilment: direct + surface: sequence-steps -> Create a step variant, Bulk create step variants + scopes: [sequences:write, sequences:operate] + notes: > + A variant carries a subject, a message, an enabled flag and up to three attachment + identifiers. There is no split share, so report the split as unsettable rather than assuming + one — which is what the operation itself already requires. Enable step variants and Disable + step variants govern whether the step uses variants at all and need the operate scope rather + than write. + + - name: variant.update + fulfilment: direct + surface: sequence-steps -> Update a step variant + scopes: [sequences:write] + notes: > + The enabled flag is here, which makes disabling the right move for a variant under test. + + - name: variant.remove + fulfilment: direct + surface: sequence-steps -> Delete a step variant, Bulk delete step variants + scopes: [sequences:write] + notes: > + Destroys the variant's measurement history. Disable it instead while a test is running. + + - name: variant.list + fulfilment: direct + surface: sequence-steps -> List step variants + scopes: [sequences:read] + notes: > + Returns each variant's enabled flag. The share each runs at is not part of the model here, + so report it as unavailable rather than inferring an even split. + + - name: template.create + fulfilment: partial + surface: email-templates -> Create an email template + scopes: [sequences:write] + missing: > + No draft state. A template exists in one state and is usable the moment it is created, so + the contract's guarantee that unreviewed copy cannot be sent is not enforced by the product + and has to be carried by the approval gate instead. + notes: > + Folders organise templates — read List email template folders and List email templates + first, because reuse beats proliferation here as much as it does for lists. + + - name: template.update + fulfilment: partial + surface: email-templates -> Update an email template + scopes: [sequences:write] + missing: > + No versioning. The update replaces the content in place and no earlier version is kept, so + the rule that a change always produces a new draft and never mutates published copy cannot + be honoured. Keep the previous text yourself if anyone may need it back. + notes: > + Steps hold their copy inline, so changing a template does not change what a live campaign + sends. Those are two separate edits, and which one the user actually asked for is worth + settling before either. + + - name: template.get + fulfilment: partial + surface: email-templates -> Get an email template, Get template variables + scopes: [sequences:read] + missing: > + No version list, no published or retired state, and no list of what binds it — steps carry + their own copy, so there is nothing to report as a dependent. + notes: > + Get template variables is the read that says which merge fields the copy needs, before + anyone renders it against a real person. + + - name: template.list + fulfilment: partial + surface: email-templates -> List email templates, List email template folders + scopes: [sequences:read] + missing: > + The second half of the question. Folders say where a template sits; nothing says whether its + copy is draft, published or retired, because those states do not exist here. + + - name: template.publish + fulfilment: absent + because: > + No version lifecycle is documented for templates. There is no draft, no published version + and no publish endpoint — a template is usable from the moment it exists. Never present + creating or updating one as publishing it. + + - name: template.retire + fulfilment: absent + because: > + The same absent lifecycle. Delete an email template destroys the template rather than + retiring a version, and it cannot answer the question this operation is really asking — + which live campaigns still depend on this copy — so it must not be substituted. + + - name: content_policy.define + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. The blacklist rules govern which + addresses and domains may be contacted, not what the copy may say, and substituting them + answers a different question entirely. + + - name: content_policy.list + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. + + - name: content_policy.check + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing takes a rendered message + and returns the rules it breaks, so copy has to be checked against the account's rules + outside the product before it is approved. + + # ------------------------------------------------------------------------- family 7 — messages + + - name: message.draft + fulfilment: partial + surface: email-templates -> Render an email template, Get template variables + scopes: [sequences:operate] + missing: > + The render returns a subject and a body and nothing else. The footer, the identification + block and the unsubscribe mechanism the contract requires the draft to show are absent from + the response, so what is previewed cannot be proved to be the whole of what would leave. + Merge values that are missing or wrong are reported, which is the part it does keep. + notes: > + Renders against one contact identifier, optionally in the context of a campaign and a + sending identity so their variables resolve too. Two other renders exist and both carry a + beta mark — Get sequence preview for a contact under sequence-contacts, and Generate an AI + draft reply under inbox — so say beta out loud before planning a route through either. + + - name: message.schedule + fulfilment: partial + surface: > + direct-outreach -> the direct sends (an email, a LinkedIn message, InMail or voice message, + and Send a LinkedIn connection request to a contact), each with its send-after moment + missing: > + Only a send outside any campaign, and only where the account's Reply has the route. From + reply-cli 0.17.0 the direct sends take `--send-after`, a moment with its offset, which the CLI + sends as UTC, and Reply holds the send until then; a moment already past is sent at once. A + Reply that does not keep a direct send for later answers a bare 404, and nothing is + scheduled. The contract's read before repeating — the pending sends for this person on this + thread — has no list surface here: a harness that keeps the reference reads and cancels by + it. + notes: > + From reply-cli 0.17.0, send with `--idempotency-key`, which goes as the Idempotency-Key header: + the same request repeated under the same key answers the send Reply took and sends nothing + twice, so a lost answer is repeated under the key rather than read around. Reply honours the + key only where it has the direct-send routes, so read `reply direct-send get` of a reference + first (from reply-cli 0.17.0): its own `direct_send.not_found` or `direct_send.not_owned` says + the routes are there, a bare 404 says they are not, and a key sent there protects nothing. + The answer names the send's `reference` and its `state`: `sent` means it went, `failed` and `cancelled` are final, and + any other state means Reply holds it and it has not gone yet. Keep the reference; it is the + only handle on the send, and after a lost answer `reply direct-send get` of it is read before + any repeat. Reply keeps a key for a day, so a repeat goes under it only within 23 hours of + the first try; past that, nothing is sent again. From reply-cli 0.17.0 an email direct send + also takes `--schedule-id`, a schedule from `reply schedule list`; Reply refuses it on every + LinkedIn route. Reply then holds the send until the schedule's first opening at or after the + moment, or after now where none is given, and the answer names no moment: Reply estimates + one only where the schedule opens within 30 days, and reply-cli does not pass the estimate. + A manual-email task dated for the 14th is still queued work for a person, not a queued send. + + - name: scheduled_message.list + fulfilment: absent + because: > + No surface lists the pending sends — not by person, campaign or sender. From reply-cli 0.17.0, + `reply direct-send get ` reads one send by its reference — its state, its moment, + when it went and why it failed — which answers for a send already known and never for "what is + queued". A harness that keeps the reference reads and cancels by it. + + - name: scheduled_message.cancel + fulfilment: partial + surface: direct-outreach -> the direct send's cancel, by its reference + missing: > + By reference only, and only where the account's Reply has the route. From reply-cli 0.17.0, + `reply direct-send cancel ` cancels one direct send still held for its moment. + Nothing lists the pending sends, so a harness that keeps the reference reads and cancels by + it; a send whose reference was not kept cannot be found to cancel. What is pending in a live + participation is still the next touch of a campaign, and stopping that is enrollment.pause or + enrollment.stop rather than this. + notes: > + A cancel of a send already cancelled is a success, and one whose answer was lost is safe to + run again. A send that has gone answers `direct_send.already_sent` and one that failed + `direct_send.already_failed`: report it as gone or failed, never as cancelled. A bare 404 means + the account's Reply does not have the route yet. + + # ----------------------------------------------------------------------- family 8 — enrollment + + - name: enrollment.list + fulfilment: direct + surface: > + sequence-contacts -> List contacts in sequence, List contacts in sequence with extended + state; contacts -> Get sequences for a contact + scopes: [sequences:read, contacts:read] + notes: > + Both ends of the same read are covered — the campaign's people, and one person's campaigns. + Count contacts in sequence is documented as coming soon, so count by paging the list rather + than planning around it. + + - name: enrollment.get + fulfilment: direct + surface: > + sequence-contacts -> Get a contact in a sequence, List contacts in sequence with extended + state + scopes: [sequences:read] + notes: > + The extended-state listing is the one that carries progress detail; the single read is the + cheaper check-first before a hold, a resume or a stop. Which of the fields this operation + names are actually present comes from those two pages at call time, not from here. + + - name: enrollment.pause + fulfilment: partial + surface: sequence-contacts -> Set contacts' status in this sequence + scopes: [sequences:operate] + missing: > + No reason is accepted and there is no dated automatic resume. The hold is a bare status, so + why someone was held and when they should carry on again survive only wherever the agent + chooses to write them down. + notes: > + At most one hundred people per call, and only a participation that is currently active can + be held. The response returns failures keyed by person and an empty object when every one + succeeded — reconcile per person rather than reading that empty object as a count. + + - name: enrollment.resume + fulfilment: partial + surface: sequence-contacts -> Set contacts' status in this sequence + scopes: [sequences:operate] + missing: > + Setting a participation back to active is accepted from any current state, so the refusal + the contract requires — resume only what is actually held — is not enforced by the API. The + check-first read has to perform it, or a finished participation is quietly restarted and + someone is written to again. + notes: > + On a live campaign this sends. The preview naming who resumes is the approval artefact and + knowing which endpoint performs the call softens nothing about that. + + - name: enrollment.stop + fulfilment: partial + surface: sequence-contacts -> Remove contact from sequence, Bulk remove contacts from sequence + scopes: [sequences:operate] + missing: > + The mandatory reason. The body carries identifiers and nothing else, so neither why someone + was taken out nor that a different person was the cause can be recorded — and naming that + other person is part of the operation, not a nicety. Record the reason wherever the run + itself is recorded. + notes: > + The bulk response counts requested, removed, not found and not in sequence, and lists the + identifiers actually removed. An already-absent participation reads as a completed stop. + + - name: disposition.set + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Marking someone replied or bounced + records what happened to a message, and an inbox category records what a reply meant; + neither is the business outcome of the participation, and pressing one into service as a + stand-in corrupts the number people are measured on. + + # -------------------------------------------------------------------- family 9 — conversations + + - name: conversation.get + fulfilment: direct + surface: inbox -> Get inbox thread, List messages in an inbox thread + scopes: [inbox:read] + notes: > + Two reads — the thread, then its messages in order. Note the thread's channel while you are + there, because a reply has to go out on the same one. + + - name: conversation.classify + fulfilment: partial + surface: inbox -> Assign or clear a thread's category, Assign threads to a category + scopes: [inbox:operate] + missing: > + The meaning is recorded, its provenance is not. No field carries who decided it, which + message they decided it from, or how sure they were, so a category set by a model and one + set by a person are indistinguishable afterwards. + notes: > + The vocabulary is the account's own inbox categories — read List inbox categories first and + map onto what exists rather than inventing a label. Re-read the thread to confirm it took. + + - name: conversation.assign + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Assign threads to a category and + Assign or clear a thread's category move a thread between categories, not between people, + and the resemblance in the names is exactly the trap. Changing who owns the person is a + different act with different consequences and is not a substitute. + + - name: conversation.snooze + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing takes a thread out of the + queue and brings it back on a date. + + - name: conversation.close + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Mark threads as read records a + read state, not a worked one, and deleting a thread destroys it. Neither says the thread was + dealt with, which is the whole of what closing one means. + + - name: conversation.reopen + fulfilment: absent + because: > + Nothing closes a thread here, so nothing reopens one. Mark threads as unread is the nearest + surface and it says something else. + + - name: referral.record + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. The pieces exist separately, since + the named person can be created and the referrer can be taken out of the campaign, but + nothing records that the one came from the other — and that link is the only fact that + justifies contacting a stranger, so performing the two calls without it is not the + operation. + + - name: activity.log + fulfilment: partial + surface: contacts -> Add a note to a contact + scopes: [contacts:operate] + missing: > + Only the note. A free-text note is one of the things this operation records; an email sent + from a personal client, a conversation in a corridor, or a message on a channel we do not + send from cannot be logged as an activity with its channel, direction and time, so the + record stays an incomplete account of what happened to this person. + notes: > + Get activities for a contact is the read that shows what the product recorded itself, and a + note is not guaranteed to appear in it. Check before telling the user the record is whole. + + # ---------------------------------------------------------------------------- family 10 — tasks + + - name: task.list + fulfilment: direct + surface: tasks -> List all tasks, Filter tasks + scopes: [tasks:read] + notes: > + Filter tasks is the one that answers what is owed today, by due window and by owner. + + - name: task.get + fulfilment: direct + surface: tasks -> Get a task + scopes: [tasks:read] + notes: > + A task carries the message it is asking for as a subject and a body, so this read gives a + human what they need to do the work rather than a pointer to it. + + - name: task.create + fulfilment: composed + surface: tasks -> Create a task, Reassign a task + scopes: [tasks:write] + order: > + Create a task, then Reassign a task when the queue belongs to somebody else — the create + body has no assignee field, so the task lands with the calling user. Work for yourself needs + only the first call. + notes: > + Type, start time, due time and a body are required, the type decides what the task is for, + and LinkedIn work carries its own subtype. Batch reassign tasks handles a set in one call. + + - name: task.complete + fulfilment: direct + surface: tasks -> Complete a task, Batch complete tasks + scopes: [tasks:operate] + notes: > + Marks the work done and sends nothing, which is exactly what this operation means. Execute + and complete a task is a separate endpoint that does send the message the task holds — + never reach for it to satisfy this operation. If the user wants the send, that is + message.send with the approval message.send requires. + + - name: task.skip + fulfilment: absent + because: > + The documented task states are new, finished, cancelled, archived and detached from a + campaign, and none of them is skipped. The update endpoint cannot set a state at all, so + declining a task while recording that it was declined has no surface. Completing it instead + would put a lie in the record. + + - name: task.reschedule + fulfilment: direct + surface: tasks -> Update a task + scopes: [tasks:write] + notes: > + Start and due times are both updatable, but the call replaces the whole task — read it + first and resend the type, the body and the person, or they are lost. Only a task still in + its new state can be updated, so finished work cannot be pushed to tomorrow. + + - name: task.cancel + fulfilment: partial + surface: tasks -> Delete a task, Bulk delete tasks + scopes: [tasks:write] + missing: > + Dropping the work is possible, recording that it was deliberately dropped is not. Deletion + destroys the task, and the cancelled state the documentation describes cannot be set through + the update endpoint, so afterwards nothing distinguishes work called off from work that was + never there. + notes: > + Say the deletion is irreversible before doing it. The contract treats this operation as + compensatable and on this surface it is not, which is a difference the user has to hear + first rather than discover. + + - name: task.reassign + fulfilment: direct + surface: tasks -> Reassign a task, Batch reassign tasks + scopes: [tasks:write] + notes: > + The batch form is the one for handing over a whole queue. Reconcile per task rather than + assuming the entire set moved. + + - name: call.place + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Execute and complete a task, the + only endpoint that performs a task's action, supports manual email and SMS and rejects every + other type, so a call task cannot be dialled through the API. Calls are placed in the + product, and the user needs telling that plainly. + + - name: call.log + fulfilment: absent + because: > + not evidenced — call activity is readable through reporting, under Get calls reporting + overview and List call activity, and nothing writes one. A call that happened away from the + product cannot be recorded here. + + - name: call_recording.get + fulfilment: absent + because: > + not evidenced — no documented surface was found for this, and none for the agreement that + permitted the recording either. + + - name: call_recording.discard + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. A recording that has to be + destroyed must be dealt with in the product, and that has to be said out loud rather than + left for the user to assume an agent handled it. + + # ------------------------------------------------------------------------- family 11 — meetings + + - name: meeting.propose + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing offers times and nothing + hands over a way to pick one. Toggle thread meeting-intent marks that a thread is about a + meeting and proposes nothing, so it must not be read as a booking surface. + + - name: meeting.book + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Meetings appear in reporting as + facts that already happened; no endpoint creates one, issues an invitation, or records a + meeting that was invited elsewhere. + + - name: meeting.confirm + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. There is nothing to read a + meeting's attendee responses from and nothing that chases the people who have not answered. + + - name: meeting.reschedule + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. With no booking surface there is + no meeting here to move. + + - name: meeting.cancel + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Tell the user to cancel it in the + calendar rather than leaving someone expecting a meeting nobody will attend. + + - name: meeting_outcome.record + fulfilment: absent + because: > + not evidenced — the meetings report carries when a booking was made, by whom, from which + campaign and on which channel, and no outcome field of any kind. Held, no-show and cancelled + beforehand cannot be told apart here, which also means meeting outcomes cannot be read back + out of this product later. + + - name: meeting.list + fulfilment: partial + surface: reports -> List meetings + scopes: [reporting:read] + missing: > + A booking ledger rather than a calendar. A row gives who booked it, the channel it came + from, the person, the campaign and when the booking was made — not when the meeting is, who + is attending, how to join, or how it went. Nothing upcoming can be answered from it and no + outcome can be read out of it. + notes: > + Filterable by date window and by user, so it does answer how many meetings were booked and + by whom over a stated period. Measurement is rate-limited harder than the rest of the + surface — sequential calls, cached within the session, no polling. + + - name: meeting.get + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. The reporting list is the only + place a meeting appears at all and it has no per-meeting read. + + - name: qualification.record + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Custom fields could be made to + hold the answers, but that is a schema somebody would have to invent, and inventing it here + would produce a record no other run could read back. + + - name: handoff.create + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Changing who owns a person moves + the record; it makes no offer, starts no clock, and can be neither accepted nor refused, so + it is not this operation. + + - name: handoff.accept + fulfilment: absent + because: > + Nothing creates a handoff here, so there is nothing to accept and no commitment clock to + start. + + - name: handoff.reject + fulfilment: absent + because: > + Nothing creates a handoff here, so there is nothing to refuse. + + - name: handoff.return + fulfilment: absent + because: > + Nothing creates or accepts a handoff here, so there is nothing to give back. + + - name: handoff.withdraw + fulfilment: absent + because: > + Nothing creates a handoff here, so there is nothing to pull back. + + - name: handoff.list + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. Nothing shows what has been handed + over and left unanswered, in either direction. + + - name: handoff.get + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. + + - name: opportunity.create + fulfilment: absent + because: > + not evidenced — no documented surface was found for this. A conversion into a deal is + recorded wherever the pipeline lives, and this adapter has no view of that. Name the system + the user should record it in rather than approximating it with a field on a person or an + account. + + + # ------------------------------------------------------------ 17 — oversight, review and safety + # Evidence: the AI SDR pending-approval and sequence-settings pages, the contact blacklist rule + # group, and the endpoint index checked for a stop-rule, budget, escalation or review surface. + + - name: approval.request + fulfilment: absent + because: > + No documented surface puts an item into a queue for a human. The pending-approval endpoints + list, read, send, reject and regenerate items that are already there — the AI SDR sequence + generates them itself under the approval mode set on that sequence, and nothing else can be + queued for review. + + - name: approval.list + fulfilment: partial + surface: ai-sdr-pending-approvals -> List pending approvals + scopes: [ai-sdr:read] + beta: true + missing: > + Only AI-generated messages inside an AI SDR sequence reach this queue, on email and + LinkedIn. A bulk write, a piece of content or a policy change waiting on a human has no + queue here at all, so an empty queue does not mean nothing is waiting. + notes: > + Each item carries when it was created rather than how long it has waited — the age the + operation reports is computed from that. The queue can be filtered by sequence and by user. + + - name: approval.get + fulfilment: partial + surface: ai-sdr-pending-approvals -> Get pending approval for a contact + scopes: [ai-sdr:read] + beta: true + missing: > + The item is addressed by contact rather than by an approval identifier, and only an + AI-generated message is retrievable this way. Anything else a human is being asked to + approve has no item to fetch. + + - name: approval.resolve + fulfilment: partial + surface: > + ai-sdr-pending-approvals -> Send a pending approval, Send a batch of pending approvals, + Reject (delete) a pending approval + scopes: [ai-sdr:write] + beta: true + missing: > + Rejection records no reason and is heavier than the contract's reject: it discards the + queued draft and removes the contact from the sequence, with nothing documented to bring + either back. Tell the user that before they reject, and keep the reason wherever the run is + recorded. + notes: > + Approving is the send, exactly as the contract has it, so the approval class is unchanged by + the mapping — one named recipient is confirm_each, and the batch send is confirm_once over a + preview that names the population. + + - name: autonomy.get + fulfilment: partial + surface: ai-sdr-sequences -> Read AI SDR sequence settings + scopes: [ai-sdr:read] + beta: true + missing: > + One AI SDR sequence's own settings — whether its generated messages need approval, and + whether autopilot is on. Nothing states what a credential may do unattended across the + account, and there is no queue timeout, unattended action cap or escalation target to read. + Everywhere else, autonomy is the agent's own policy held outside this product. + + - name: autonomy.set + fulfilment: partial + surface: > + ai-sdr-sequences -> Set the approval mode, Enable autopilot, Disable autopilot + scopes: [ai-sdr:operate] + beta: true + missing: > + The gate and the mode, on one AI SDR sequence. The queue timeout and what a timeout means, + the unattended action cap, the escalation target and per-channel differences have no setting + here. + notes: > + Turning the gate off can also release everything already waiting, in the same call. That + makes loosening the gate a send, not a settings change, and it must be previewed and + approved as one. + + - name: escalation.raise + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: escalation.list + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: escalation.resolve + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: editorial_review.record + fulfilment: absent + because: > + not evidenced — no documented surface binds a named human's review to a sent message. A + message approved out of the AI SDR queue records that it was sent, which is not the same + fact and must never be reported as one. + + - name: editorial_review.get + fulfilment: absent + because: > + not evidenced — nothing records the review, so nothing can return it. The honest answer to + an auditor here is that no review evidence exists in this product. + + - name: review.request + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: review.list + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: review.get + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: review.score + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: feedback.record + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: review_policy.define + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: review_policy.get + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: scorecard.define + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: scorecard.list + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: scorecard.publish + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: scorecard.retire + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: coaching.summarize + fulfilment: absent + because: > + not evidenced — the reporting surfaces cover activity and performance, not coaching. Nothing + records that someone attended, listened, commented, scored or gave feedback, so there is + nothing to summarise per coach. + + - name: budget.get + fulfilment: absent + because: > + not evidenced — no documented surface reports what is left on a meter. A meter does exist: + starting a Live Data search spends the user's data allowance. That the remaining allowance + cannot be read is exactly why a search is previewed before it is started. + + - name: budget.set + fulfilment: absent + because: > + not evidenced — checked against the endpoint index, nothing sets an allowance ceiling of the + kind a pre-flight check reads. + + - name: stoprule.set + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: stoprule.list + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: stoprule.clear + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: stoprule_firing.list + fulfilment: absent + because: > + not evidenced — nothing stops the work by itself here, so there are no firings to list. When + sending is off in this product it was a person or an agent that stopped it, and the reason + lives in the run record rather than in the API. + + - name: stoprule_firing.get + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: outreach.hold + fulfilment: partial + surface: > + contact-blacklist-rules -> Create an email blacklist rule, Create a domain blacklist rule, + Bulk create email blacklist rules, Bulk create domain blacklist rules + scopes: [contacts:write] + missing: > + This blocks future contact and nothing else. Live enrolments, scheduled steps, open tasks, + pending approvals and outstanding meeting proposals are untouched by it, and the rule + returns no per-item ledger of who was actually reached. The kill switch the contract + describes is only realised once those are stopped too, through their own operations, and + every one of them has to be reported. + notes: > + A person is held by an email rule and a company or a domain by a domain rule. Rules are + account-wide, so check the existing rules before adding one and expect the block to apply to + work other people own. + + - name: outreach.release + fulfilment: partial + surface: > + contact-blacklist-rules -> Delete an email blacklist rule, Delete a domain blacklist rule, + List email blacklist rules, List domain blacklist rules + scopes: [contacts:write, contacts:read] + missing: > + Deleting the rule lifts the block, but nothing resumes by itself: whatever was stopped when + the hold went on has to be restarted deliberately, and no ledger of what was held exists to + restart it from. Re-check each person's eligibility first — the contract requires it and + this product will not. + + # --------------------------------------- 18 — the team: people, ownership, workload and targets + # Evidence: the user-account pages, the contact and account owner endpoints, the task + # reassignment endpoints, and the endpoint index checked for workload, quota and goal surfaces. + + - name: actor.list + fulfilment: partial + surface: user-account -> List team users + missing: > + Identity only — the team, the user identifier, the display name and the email address. The + state the operation asks for, active, ramping, unavailable or gone, is not carried, so this + read cannot tell an agent whether the person it is about to hand work to is still there. + notes: > + No scope required. It covers the teams this credential can act in; people outside them do + not appear, which is a different answer from not existing. + + - name: actor.get + fulfilment: partial + surface: user-account -> Get current user, List team users + missing: > + Only the calling credential has a record of its own. Anyone else is an identity row in the + team listing and nothing more — no state, and none of the ceilings that apply to them. + + - name: team.list + fulfilment: direct + surface: user-account -> List team users + notes: > + Every row carries the team it belongs to, so one read answers both which teams exist and who + is in them. No scope required. Teams this credential cannot act in are not listed. + + - name: workload.get + fulfilment: absent + because: > + not evidenced — checked against the endpoint index, nothing reports what a person is + carrying. Open tasks and live enrolments can each be listed on their own, but no surface + answers the question this operation asks, and adding up two listings is not the same answer. + + - name: workload_policy.define + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: workload_policy.get + fulfilment: absent + because: > + not evidenced — no ceiling is declared anywhere, so the answer here is always none declared, + which the contract reads as unlimited. + + - name: ownership.get + fulfilment: partial + surface: accounts -> Get an account; contacts -> Filter contacts + scopes: [contacts:read] + missing: > + The owner is an attribute of the record rather than a surface of its own, so it is read with + the record. The second half of the question has no answer here at all: nothing states + whether acting on an unowned record would make the actor its owner, and that rule is set in + the product's own settings rather than returned by any response. + + - name: ownership.assign + fulfilment: direct + surface: contacts -> Change contacts owner; accounts -> Update account owner + scopes: [contacts:operate, contacts:write] + notes: > + One endpoint per subject kind — people through the contact group, companies through the + account group. There is no routing rule to defer to here, so the caller names the person; + check they are still on the team first, because the owner listing carries no state. + + - name: assignment_policy.define + fulfilment: absent + because: not evidenced — no documented surface was found for this + + - name: assignment_policy.get + fulfilment: absent + because: > + not evidenced — no routing rule is stored in this product, so there is none to read and + nothing that would say who gets the next piece of work. + + - name: book.transfer + fulfilment: partial + surface: > + contacts -> Change contacts owner; accounts -> Update account owner; tasks -> Batch reassign + tasks + scopes: [contacts:operate, contacts:write, tasks:write] + missing: > + Three parts of the book move — contact ownership, account ownership and open tasks. The + senders behind live threads, the open conversations and the authored content do not, and no + surface reports the book as a whole, so the ledger the contract requires has to be built by + the caller from what each call returns before anything is repeated. + notes: > + Reassigning ownership does not re-point the sending account behind a live thread. Say so + before the transfer: a departing person's threads keep sending from their mailbox until the + sequences are changed, and that is the part users are most often surprised by. + + - name: goal.define + fulfilment: absent + because: > + not evidenced — checked against the endpoint index, this product stores no quota, goal or + target, so there is nothing to set. + + - name: goal.get + fulfilment: absent + because: not evidenced — no target is stored here, so there is none to read. + + - name: goal.list + fulfilment: absent + because: not evidenced — no target is stored here, so there is none to list. + + - name: pace.get + fulfilment: absent + because: > + not evidenced — pace is a target measured against achievement, and no target exists in this + product. Achievement alone is readable through the reporting surfaces, and reporting it as + pace would invent the half that is missing. + + # ----------------------------------------------------------- 19 — accounts and buying groups + # Evidence: the account pages, read against the account record shape on its own doc page. + + - name: account.get + fulfilment: direct + surface: accounts -> Get an account + scopes: [contacts:read] + notes: > + The record carries the owner, the stage it is in and how many people are linked to it. The + verification read after any account write. + + - name: account.search + fulfilment: direct + surface: accounts -> Filter accounts, List accounts + scopes: [contacts:read] + notes: > + Companies already held, never an outside database and never metered — matching the contract + exactly. The discovery family is where an outside search belongs. + + - name: account.update + fulfilment: partial + surface: accounts -> Update an account + scopes: [contacts:write] + missing: > + The account's stage can be moved and the rest of the record edited, but the tier the + contract names has no home on the record and neither does the reason for the change. The + stages are whatever this account has declared, so resolve the words the user says against + them before writing — a stage that does not exist is a guess. + + - name: account.claim + fulfilment: absent + because: > + not evidenced — there is no lease on an account here. Ownership can be changed, which is a + different and heavier act: it does not expire by itself, and using it as a claim would leave + the account permanently reassigned. + + - name: account.release + fulfilment: absent + because: not evidenced — nothing claims an account, so there is nothing to release. + + - name: account_membership.create + fulfilment: direct + surface: accounts -> Bulk add contacts to an account + scopes: [contacts:operate] + notes: > + Bulk-shaped: reconcile every person in the response rather than reporting the call. Attach + deliberately, so that four spellings of one company do not become four accounts. + + - name: account_membership.list + fulfilment: partial + surface: accounts -> List contacts for an account + scopes: [contacts:read] + missing: > + Who is attached, and no more. How each person came to be attached is not recorded, so the + basis the contract wants on every row cannot be given, and whether someone is being touched + right now needs a separate read against the sequence they are in. + + - name: account_membership.delete + fulfilment: direct + surface: accounts -> Bulk remove contacts from an account + scopes: [contacts:operate] + notes: > + Detaches the person from the company; it does not delete the person and does not stop any + outreach they are in. + + - name: collision.check + fulfilment: partial + surface: > + accounts -> List contacts for an account; sequence-contacts -> List contacts in sequence + with extended state, Get a contact in a sequence + scopes: [contacts:read, sequences:read] + missing: > + Only outreach collisions are visible, and only by assembling them: the people on the + account, then each one's state in the sequences they are in, then the owner on each record. + A live customer, support or opportunity motion is invisible here — it lives in the CRM — so + a clean answer from this check is not evidence that the company is free. + notes: > + Re-run it immediately before enrolling. Collisions appear between planning and execution, + and the gap is exactly where the embarrassing double-touch happens. + + - name: buying_group.define + fulfilment: absent + because: > + not evidenced — people can be attached to an account, but nothing records what each of them + does in a decision, so a group with roles cannot be expressed here. + + - name: buying_group.get + fulfilment: absent + because: not evidenced — no group with roles is stored, so there is none to return. + + - name: buying_group.enroll + fulfilment: absent + because: > + not evidenced — no surface enrols a group as a group. Enrolling several people from one + account one by one is a different act: nothing staggers them, orders them, or reacts to one + person's reply on behalf of the others, and doing it by hand while calling it this operation + would hide exactly the coordination the operation exists for. + + # --------------------------------------------------------------------------- 20 — measurement + # Evidence: the reports group in the endpoint index, the sequence stats anchors carried by the + # 1.1.0 mapping, and the index checked for export, opportunity and metric-definition surfaces. + + - name: engagement.summarize + fulfilment: partial + surface: > + reports -> Get email reporting overview, Get calls reporting overview, Get tasks reporting + overview, Get LinkedIn reporting overview, Get channel efficiency overview, Get team + performance overview; sequences -> Get stats for all sequences, Get sequence stats + scopes: [reporting:read, sequences:read] + missing: > + The grouping is not an argument. Each report offers the one breakdown it was built for — by + channel, by sequence, by team member — and a question that needs a different grouping has to + be assembled from the rows behind the numbers instead. The measure set is likewise the + report's, not the caller's. + notes: > + These endpoints are rate-limited harder than the rest of the API: sequential calls, cached + within the session, no polling. Report the window alongside every figure — two numbers are + only comparable when the window and the basis match. + + - name: engagement_event.list + fulfilment: direct + surface: > + reports -> List email activity, List call activity, List task activity, List LinkedIn + activity + scopes: [reporting:read] + notes: > + One listing per channel — these are the rows behind the summary, and the route to any + grouping the overviews do not offer. Same stricter rate limits. + + - name: funnel.summarize + fulfilment: partial + surface: > + reports -> Get email reporting overview, Get channel efficiency overview, List meetings + scopes: [reporting:read] + missing: > + No surface returns a ladder. The stages come from separate reads, and neither the + denominator a stage is measured against nor how well that stage can be known at all is + stated anywhere — the caller declares both and has to say so when reporting the result. + Stages past the meeting are not covered by any of these. + + - name: opportunity.summarize + fulfilment: absent + because: > + not evidenced — checked against the endpoint index, nothing here carries opportunities or + revenue. That answer lives in the CRM, and reporting meetings as though they were the far + end of the funnel would overstate what is known. + + - name: attribution.explain + fulfilment: absent + because: > + not evidenced — no attribution model is stated anywhere, so nothing can explain why an + outcome was credited where it was, or what another model would have said. + + - name: response_time.summarize + fulfilment: absent + because: > + not evidenced — no documented surface reports time from arrival to first touch, or from a + reply arriving to it being answered. + + - name: metric.describe + fulfilment: absent + because: > + not evidenced — checked against the endpoint index, there is no enumeration or definition + surface. What a figure means here is prose on its report page, read by a human, and it says + nothing about how far the figure can be trusted. + + - name: metric.compare + fulfilment: absent + because: > + not evidenced — no surface compares two arms or reports a sample size and an interval. Two + report calls placed side by side are not this operation: the arithmetic that says whether + the difference means anything is the part that is missing. + + - name: export.request + fulfilment: absent + because: > + not evidenced — checked against the endpoint index, no general data export exists. The + reporting listings return rows inline and paginated, which is a read rather than a bounded + extract, and treating one as the other would move personal data with none of the handling an + extract implies. + + - name: export.get + fulfilment: absent + because: not evidenced — nothing produces an extract here, so there is none to collect. + + # ---------------------------------------------------------------- 21 — introspection and runtime + # Evidence: the user-account and background-job pages, the custom field group, the inbox + # category group, the documented rate limits, and the index checked for an idempotency lookup. + + - name: operation.search + fulfilment: absent + because: > + Nothing in this product answers it, and nothing should — the thing being searched is the + contract, which the core pack carries. Recorded absent because this register answers only + for what this adapter performs. + + - name: operation.describe + fulfilment: absent + because: > + As above: an operation's meaning, its refusals and its five properties come from the + contract in the core pack, not from any API surface here. + + - name: operation.preview + fulfilment: partial + surface: > + sequence-contacts -> Get sequence preview for a contact; ai-sdr-sequences -> Preview + autopilot results; live-data -> Preview a Live Data search + beta: true + missing: > + There is no general dry run. Three specific acts can be previewed, all of them beta, and + every other write is knowable only by performing it — which means that for most operations + the preview an approval gate wants has to be assembled from reads before the write, not + requested from the product. + notes: > + Preview before Start on a Live Data search is a hard rule, not a courtesy: Start spends the + user's allowance and Preview does not. + + - name: plan.validate + fulfilment: absent + because: > + not evidenced — no surface takes a plan. Authority, ordering, preconditions and headroom are + checked step by step against the reads each step needs, by the agent, before anything runs. + + - name: contract.describe + fulfilment: absent + because: > + Nothing here describes the contract — which version is in force, what was renamed from what, + and what it binds an agent to is the core pack's own answer, not this API's. + + - name: capability.list + fulfilment: partial + surface: user-account -> Get current user, List team users + missing: > + The granted scope set is not returned by anything. Identity and the teams a credential may + act in are readable; what it may actually do is discovered only by making a call and reading + an insufficient_scope refusal back. For an unattended run that means the honest per-capability + answer is unknown until something is attempted, and unknown is not permission. + notes: > + Neither read needs a scope, so both work with any working credential. When a capability has + to be known in advance, the key's scopes are visible in the product settings rather than + through the API. + + - name: vocabulary.list + fulfilment: partial + surface: inbox -> List inbox categories + scopes: [inbox:read] + missing: > + Only the reply categories this account has declared. Enrolment statuses, meeting outcomes, + step intents, exit reasons, content-policy rule classes and the properties a branch + condition may be written over have no listing at all — checked against the endpoint index, + there is no enumeration surface. For those kinds the answer is unknown, which the contract + allows and which is not the same as an empty list. + + - name: schema.describe + fulfilment: partial + surface: custom-fields -> List all custom fields, Get a custom field + scopes: [contacts:read] + missing: > + Custom fields only, and only on people. No surface describes the standard fields of a record + kind or says which of them may be written; that is prose on the record's own doc pages, read + at call time, and it cannot be enumerated. + + - name: channel.describe + fulfilment: absent + because: > + not evidenced — no documented surface states a channel's own rules: whether automation is + sanctioned there, how its allowance works, how long a reply window stays open or what + recording consent it expects. A sending account's configured limits are a different thing + and belong to the sender operations; using them as an answer here would confuse one + mailbox's ceiling with the channel's rules. + + - name: adapter.describe + fulfilment: partial + surface: > + the Rate limits guide page; background-jobs -> Get a background job + scopes: [other:read] + missing: > + Nothing returns any of this. The request ceilings and the queued-versus-inline rule are + documented in prose — reporting and stats endpoints are limited harder than the rest, and a + long write answers with a background job to poll — but batch ceilings, page sizes and the + scope and lifetime of an idempotency key are not stated, and none of it can be read per + installation. + + - name: adapter.verify + fulfilment: absent + because: > + not evidenced — nothing here tests fulfilment. This register is the claim, made from + documentation rather than from a run, and it is the thing a verification would check rather + than a substitute for one. + + - name: job.get + fulfilment: partial + surface: background-jobs -> Get a background job, List background jobs + scopes: [other:read] + missing: > + Status, progress and the terminal timestamps are documented, but the result payload is + opaque and its shape varies by job kind, so the per-item ledger the contract requires is not + guaranteed to be there. Where one outcome per item is needed, reconcile against the entities + themselves rather than trusting the job to carry it. + notes: > + A long write completes when the job reaches a terminal state, not when the call returns. + Never blind-retry a bulk write that failed — the first attempt may have partly succeeded. + + - name: job.cancel + fulfilment: direct + surface: background-jobs -> Cancel a background job + scopes: [other:operate] + notes: > + Items already processed stay processed, exactly as the contract has it. Cancelling is not an + undo: it leaves a partial result, and that result has to be reconciled and reported. + + - name: invocation.get + fulfilment: absent + because: > + not evidenced — checked against the endpoint index, nothing looks a call up by the + idempotency key it was sent with. After a lost response the only recovery is the operation's + own check-first read, which is why every write in the contract names one. + + - name: term.resolve + fulfilment: absent + because: > + Nothing here resolves a word onto a concept. The vocabularies this account declares can be + listed, but mapping a colleague's shorthand or another system's label onto the right concept + is the contract's own answer in the core pack. diff --git a/skills/reply-adapter/reply-operations-mapping/references/fulfilment.md b/skills/reply-adapter/reply-operations-mapping/references/fulfilment.md new file mode 100644 index 0000000..eb8f1c2 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/fulfilment.md @@ -0,0 +1,872 @@ + + +# What this adapter does not reach + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +This file describes **one product's coverage of the contract**, and nothing else. +Every line in it is a statement about this adapter — never about the operations themselves. The +vendor-neutral layer exists precisely so that a capability this product lacks stays visible as an +unmet need rather than quietly disappearing from the set of things an SDR requires; deleting an +operation from the contract because this API has no endpoint for it would undo the layer entirely. + +**Expect this file to be long, and read its length as the design working rather than failing.** No +provider covers the whole of an SDR's job, and a map that admitted only the parts one product happens +to reach would be a flattering map and a useless one. A gap recorded here costs a user one honest +sentence. A gap papered over with an adjacent endpoint costs them a broken run, wrong data, or a +message sent to someone who should never have received it — so when an operation is absent, say so +and name what the documentation says. Never substitute something that returns approximately the right +shape. + +**Coverage.** 325 of 325 operations carry an entry — 43 direct, 6 composed, 84 partial, 192 absent. 0 have no entry at all: nothing is claimed about them in either direction, and they are named row by row, as *not assessed*, in their family mapping table. The table at the foot of this file is where to look for the shape of that silence. + +## 01 — Discovery, enrichment and verification + +*People and audience* · [mapping-01-discovery.md](mapping-01-discovery.md) + +- `candidate.search` — **partial** + - *Missing:* Preview answers how many and shows a capped sample, not the population. The whole result set exists only after Start a Live Data search, and Start is not a read: it buys the people and creates them as contacts. So "show me everyone this filter finds, before I spend anything" cannot be answered here. + - *Surface:* live-data -> Preview a Live Data search, with the departments, industries, job titles, locations and seniorities typeahead pages that build the filter (documented Beta or Coming soon) + - *Notes:* Beta, and say so as part of the plan rather than as a footnote at the end. Build the filter from the typeahead values instead of guessing accepted ones. Preview adds no prospects and consumes no credits, which is what makes it the safe half of this operation. The write scope on a read is what the page documents, not a mistake. +- `candidate.get` — **partial** + - *Missing:* The read is per search, not per person: it returns a search and what it found, and there is no address for one found person on their own. Once Start has run, the person is an ordinary contact and is read with Get a contact — so the discovery surface stops being the place to look at exactly the moment the person becomes ours. + - *Surface:* live-data -> Get a Live Data search, List Live Data searches (documented Beta or Coming soon) + - *Notes:* Check List Live Data searches for an existing near-identical search before starting another one. A repeat spends again and returns a different world. +- `candidate.promote` — **partial** + - *Missing:* There is no promote-these-ones surface. Start finds and buys in one act: it adds everyone the filter returns as prospects and consumes credits per resulting contact, so the selection has to be made in the filter and cannot be made from a reviewed result set. The per-item promotion ledger the contract requires has to be read back off the search rather than off the call. + - *Surface:* live-data -> Start a Live Data search (documented Beta or Coming soon) + - *Notes:* Preview before Start, always — Start spends the user's allowance and the mistake is only visible once it is paid for. Show who came back in the preview and let the user approve the filter itself. Start can optionally drop the found people into a sequence or a list; treat that as enrolment and hold it to the enrolment gate rather than letting it ride along. +- `company.search` — **absent** + - *Because:* not evidenced — the preview reports a companiesCount, but the search returns and creates people. No documented surface returns companies from the outside world as companies. The accounts endpoints search only the companies we already hold, which is a different question and must not be offered as an answer to this one. + - *Surface:* live-data -> Preview a Live Data search +- `company.resolve` — **absent** + - *Because:* not evidenced — no documented surface decides which company four spellings of a name refer to. Accounts can be filtered by what we already hold, which finds an exact-ish match and says nothing about the three spellings that did not match. +- `contact.enrich` — **absent** + - *Because:* Documented as available late August 2026 and not callable today. Say that, and name the date the documentation gives. Never substitute an unrelated endpoint. + - *Surface:* contact-enrichment -> enrich by email, enrich by profile URL, find email, find phone +- `company.enrich` — **absent** + - *Because:* not evidenced — the enrichment surface is about people, and firmographics on a company are not among its documented pages. The whole enrichment group is in any case documented as available late August 2026 and is not callable today. +- `employment.check` — **absent** + - *Because:* not evidenced — nothing documented answers whether a person has left the company we have them at. There is no job-change monitoring surface, and the AI insights page that might touch on it is documented as available late August 2026 and is not callable today. +- `email_address.verify` — **partial** + - *Missing:* Two things. It validates people we already hold, taken by contact id, so a raw address that is not a contact yet cannot be checked without creating one first. And it returns the channel's verdict only — the send, hold or never_send decision the contract asks for comes from a contactability policy this product does not hold, so that half is the agent's own judgement and must be reported as such. + - *Surface:* email-validations -> Estimate email validation, Schedule email validation; background-jobs -> Get a background job + - *Notes:* Three calls in order: Estimate first, because it reports the eligible count and what it would cost against the team's quota; then Schedule, which reserves credits and returns a job; then poll the job to a terminal state and read the verdicts. Estimate is how the user approves a spend before it happens, which makes skipping it the expensive shortcut. +- `phone_number.verify` — **absent** + - *Because:* not evidenced — the enrichment surface looks a number up; nothing documented checks that a number we already hold is reachable or reports whether it is a mobile, a desk line or a virtual one. Finding and verifying are different acts and the line type is the part that changes what may be sent. The enrichment group is in any case not callable until late August 2026. + - *Surface:* contact-enrichment -> find phone +- `enrichment_policy.define` — **absent** + - *Because:* not evidenced — no documented surface stores a buying order, an acceptance predicate or a spend ceiling. Each metered call carries its own limits at call time, so nothing binds the next one, and there is no version or author to read back. +- `enrichment_policy.get` — **absent** + - *Because:* not evidenced — there is no stored policy to read, since none can be defined. + +## 02 — Contacts, identity and hygiene + +*People and audience* · [mapping-02-contacts.md](mapping-02-contacts.md) + +- `contact.resolve` — **partial** + - *Missing:* Filtering answers one key set per call, so resolving a collection is one call per person, and what comes back is a match list rather than a verdict: nothing returns "same human, this confident, under this rule". Ambiguity between two candidate records is something the caller has to notice and decide, and nothing marks it. + - *Surface:* contacts -> Filter contacts, Count filtered contacts + - *Notes:* Email is the key that behaves. Every other key is a filter over fields, which finds people who look similar rather than people who are the same. +- `contact.restore` — **absent** + - *Because:* not evidenced — the contacts group documents Delete a contact and Bulk delete contacts and nothing that brings one back. Treat a delete here as irreversible with no restore window, and say so before deleting rather than after. +- `provenance.set` — **absent** + - *Because:* not evidenced — no documented surface records where a person's data came from or under what terms. A custom field could hold the text, and must not be reported as provenance: the contract's version carries the lawful basis the sending decision rests on, and a field with a source name typed into it proves nothing. +- `job_change.record` — **absent** + - *Because:* not evidenced — nothing documented forks a record when somebody moves employer. Updating the company on the existing contact is the opposite of what the operation asks for: it destroys the history at the old employer, which is usually the reason we were talking to them. +- `cooldown.set` — **absent** + - *Because:* not evidenced — no documented surface holds a person until a date and then releases them. Suppression is permanent until lifted by hand, which is a different promise, and offering it as a cooldown means a person we meant to come back to in Q4 is never contacted again. +- `contact.disqualify` — **absent** + - *Because:* not evidenced — the contact status surfaces are about sequence participation and delivery outcomes, not about whether somebody is a prospect at all. The blacklist rules are suppression, a different act with a different meaning: using one for the other tells the user we may never contact this person, when what they said was that this person is not a fit. +- `contact.requalify` — **absent** + - *Because:* not evidenced — there is no qualification state to reverse, since none can be recorded. +- `contact.normalize` — **absent** + - *Because:* not evidenced — nothing documented rewrites records into a house format under a declared rule set while keeping what was there before. Bulk updates through the import path can overwrite values, which is not the same operation: it keeps no prior value and reports no rule set, so nothing can be undone or explained afterwards. +- `identity_policy.define` — **partial** + - *Missing:* The decision exists as an argument on each import — skip existing, which never overwrites, or update existing — and nowhere else. There is no stored policy, no version, nobody recorded as having set it, and the matching rules themselves are not configurable. Every import re-decides the question, and two imports can disagree with nothing to notice it. + - *Surface:* contacts -> Import contacts + - *Notes:* Because the policy cannot live in the product, it has to be carried by whatever keeps the user's durable context, and re-confirmed at each import rather than assumed from last time. +- `identity_policy.get` — **absent** + - *Because:* not evidenced — there is no stored identity policy to read back, only the choice made on each import, which is not recorded anywhere afterwards. +- `duplicate.list` — **absent** + - *Because:* not evidenced — no documented surface reports suspected duplicates. Filtering can confirm that two records share an address once you already suspect it; nothing proposes the clusters in the first place, which is the entire operation. +- `duplicate.merge` — **absent** + - *Because:* not evidenced — no documented surface combines two contact records into one. Deleting the loser and updating the winner is not a merge: it destroys the history the contract requires the merge to carry across, and there is no restore. +- `duplicate.link` — **absent** + - *Because:* not evidenced — nothing records that two records are the same human while both have to stay. +- `duplicate.unlink` — **absent** + - *Because:* not evidenced — there is no link to undo, since none can be made. +- `duplicate.reject` — **absent** + - *Because:* not evidenced — no documented surface records a not-a-duplicate decision, so the same pair would be proposed again by anything that looks a second time. +- `field.retire` — **partial** + - *Missing:* Delete, not retire, and nothing reports what still references the field before it goes. The check the contract requires before repeating — is this still used by a mapping, a filter or a template — has to be done by hand, and the documentation does not say what happens to the values already stored. Treat the loss as total until somebody demonstrates otherwise. + - *Surface:* custom-fields -> Delete a custom field + +## 03 — Audience and lists + +*People and audience* · [mapping-03-audiences.md](mapping-03-audiences.md) + +- `segment.define` — **absent** + - *Because:* not evidenced — filters are expressed per call and no documented surface saves one under a name. A contact list cannot stand in for a segment: it holds people, not a definition, it does not re-evaluate, and it cannot say who would match tomorrow. +- `segment.get` — **absent** + - *Because:* not evidenced — there is no saved definition to show, since none can be saved. +- `segment.list` — **absent** + - *Because:* not evidenced — there are no saved definitions to list. +- `segment.delete` — **absent** + - *Because:* not evidenced — there is nothing to retire. +- `list.get` — **partial** + - *Missing:* What is on the list is readable; where it came from is not. Nothing records the definition, the import or the search behind a list, so the second half of the question has no answer here — and it must not be improvised from the list's name, which is the one place a wrong answer will look plausible. + - *Surface:* contact-lists -> Get a contact list, Get contact's lists; contacts -> Filter contacts +- `list_membership.remove` — **absent** + - *Because:* not evidenced — the contact lists group documents adding and moving and nothing that takes a person off a list. Move relocates people to another list rather than removing them, so using it as a removal quietly files them somewhere else. This is the gap that makes a mis-built list expensive, and the honest response is to get the list right before it is written rather than to plan on trimming it. + - *Surface:* contact-lists -> Move contacts to a contact list +- `audience.assess` — **absent** + - *Because:* not evidenced — no documented surface judges whether a set of people is fit to work. Duplicates cannot be listed, contactability is not modelled, and address verification is a separate metered job over contacts rather than over a list. The assessment is therefore the agent's own and has to be reported as a judgement, not as something the product checked. +- `audience.screen` — **absent** + - *Because:* not evidenced — nothing re-checks a list against the exclusion rules and takes the failures out. The blacklist rules can be read and a validation job can be run, but there is no removal from a list at all, so the second half of the operation has nowhere to land. +- `contactability_policy.define` — **absent** + - *Because:* not evidenced — the blacklist rules are individual exclusion entries for domains, addresses and exceptions, not a policy answering send, hold or never_send per verdict and per flag. Reporting them as one would leave every verdict the rules do not mention silently defaulting to send, which is exactly the failure the policy exists to prevent. +- `contactability_policy.get` — **absent** + - *Because:* not evidenced — there is no policy to read, only the individual blacklist entries. + +## 04 — Import + +*People and audience* · [mapping-04-import.md](mapping-04-import.md) + +- `source.inspect` — **absent** + - *Because:* not evidenced as an API surface, and rightly so — the file is inspected locally, before any call, which is what the import ordering this skill already carried says: inspect the source locally, zero API calls. There is no upload-and-profile endpoint and there does not need to be. Do the inspection, then show the user what would land, then ask. +- `import.list` — **partial** + - *Missing:* There is no import history. Imports appear as background jobs among every other kind of job, and the documentation does not say the listing can be filtered to imports, so the question is answered by reading a general job list and recognising them. Anything older than that listing retains is simply gone. + - *Surface:* background-jobs -> List background jobs +- `import.get` — **partial** + - *Missing:* A job is identified by its own id, not by an import record, and the documentation does not state that the result carries a per-row ledger tying each source row to the contact it created or matched. Keep that reconciliation yourself at import time — after the fact it may not be recoverable at all. + - *Surface:* background-jobs -> Get a background job +- `import.revert` — **absent** + - *Because:* not evidenced — nothing undoes an import. Bulk deleting the contacts is not a revert: it destroys people the import updated rather than created, and it cannot put back a field the import overwrote. Say the import is not reversible before it runs, which is the only moment at which saying it helps anyone. + +## 05 — Campaign, schedule, windows and limits + +*The programme* · [mapping-05-campaigns.md](mapping-05-campaigns.md) + +- `campaign.list` — **partial** + - *Missing:* State comes back; health does not. Nothing in the listing separates a campaign that is fine from one that is not progressing, degraded or blocked, so "what is running, and what is quietly broken" needs a second pass over stats and sender health — and that verdict is this adapter's judgement, not a field it read. + - *Surface:* sequences -> List all sequences, Count sequences; sequence-folders -> List sequences in a folder +- `campaign.update` — **partial** + - *Missing:* Owner moves through its own endpoint, so one conceptual update is two calls. Beyond that there is no declared successor and no personalisation tier on the sequence: a campaign that hands over to another one cannot say so here and has to be tracked outside the product. + - *Surface:* sequences -> Update a sequence, Change sequence owner + - *Notes:* The update is last-write-wins — read the campaign first, or a field nobody meant to touch is reverted by a call that only meant to change the name. The owner endpoint is separate and may carry its own scope; take it from its page. +- `reply_policy.set` — **partial** + - *Missing:* One switch, not a decision per event class: a reply either finishes the person or sending continues, and that is the whole vocabulary. There is no per-event-class routing and no attribution window, so "a reply within thirty days still counts as this campaign's" cannot be expressed at all. + - *Surface:* sequences -> Update a sequence + - *Notes:* Continuing to send after a reply is the setting that keeps writing to somebody who already answered. The contract raises this to confirm_once for exactly that reason, and learning it is one field on an update endpoint changes nothing about the confirmation. +- `schedule.set` — **partial** + - *Missing:* Windows per day and the timezone policy are there, including sending in the prospect's own timezone rather than the schedule's. A delay basis and an out-of-window behaviour are not: nothing states whether a touch falling outside a window defers to the next open one or is skipped, so the defer-or-skip decision the contract makes the user take has no setting to carry it. Holidays are all-or-nothing per schedule. + - *Surface:* schedules -> Create a schedule, Update a schedule, Set default schedule; sequences -> Update a sequence to attach it + - *Notes:* Two calls: create or update the schedule, then attach it through the sequence update. A schedule is a shared object, so changing one silently rewrites every future date on every campaign pointing at it — which is the damage the contract's confirm_once is guarding against. Check who else uses it before editing rather than after. +- `pacing.set` — **partial** + - *Missing:* People admitted per day, messages per day and a minimum gap between sends all exist, and so does a same-domain cap the contract does not ask for. Jitter and the cold-start ramp do not: a new campaign runs at its full configured rate from day one unless somebody raises the numbers by hand over several days, and nothing records that they intended to. + - *Surface:* sequences -> Update a sequence + - *Notes:* These are per-campaign, which is the point of the operation — slowing this campaign without slowing everything else on the same mailbox. Ceilings that belong to the sending capability itself are set elsewhere and are not reachable from here. +- `sender_binding.set` — **partial** + - *Missing:* Binding is per campaign only — named participations cannot be bound. And the documentation does not say what happens to people already mid-campaign when the binding changes, so the preview the contract requires, the one telling a user which live threads are about to change From address, cannot be produced from this API. + - *Surface:* sequence-email-accounts -> Assign email account to sequence, Set sequence email accounts, Remove email account from sequence; sequence-linkedin-accounts -> Assign a LinkedIn account to a sequence + - *Notes:* Because the live-participation behaviour is undocumented, treat a rebinding on a running campaign as an act with an unknown blast radius: pause, rebind, read back, resume. Confirm the sender is healthy before binding it to anything. +- `campaign.validate` — **absent** + - *Because:* not evidenced — no documented surface answers whether a campaign is safe to turn on. The pieces a validation would read do exist separately, as steps, sender assignments, the schedule and the enrolled count, so the check is assembled by the agent out of several reads and reported as its own work. Never report it as something the product verified: an unpublished template or a schedule that never opens will not announce itself. +- `campaign.test` — **partial** + - *Missing:* It tests a template, not the campaign. There is no surface that sends step one exactly as a real contact would receive it, the documentation places no restriction on the recipient address, and nothing checks that the unsubscribe mechanism in the message actually works. The contract's test — receive it yourself, click the unsubscribe link, and only to an address the workspace can demonstrate it owns — is only partly reachable. + - *Surface:* email-templates -> Send a test email, Render an email template + - *Notes:* A test send is still a send and still metered, so the contract's confirm_each stands. Say which parts were tested and which were not, rather than reporting a green test. +- `campaign.freeze` — **partial** + - *Missing:* Neither route is a freeze. A pause carries no expiry and never resumes itself, so the thing that makes a freeze safe — that somebody forgetting about it is not a failure — is gone. A dated holiday calendar does expire by itself, but it suppresses at the schedule, and a schedule may be shared by campaigns nobody meant to stop. + - *Surface:* sequences -> Pause a sequence; or holiday-calendars -> Create a holiday calendar with schedules -> Link a holiday calendar to a schedule + - *Notes:* Say which route was taken and what it costs. A pause leaves the resume as a human's job, so it belongs in whatever carries work across sessions rather than in someone's memory. A linked calendar needs a check of which other campaigns point at that schedule, before linking. +- `campaign.unfreeze` — **partial** + - *Missing:* No preview of what letting it go early releases. The contract wants the count of messages that go out the moment the suppression lifts, and nothing here produces one, so the user is approving a release whose size nobody has been told. + - *Surface:* sequences -> Start a sequence; or schedules -> Unlink a holiday calendar from a schedule + - *Notes:* Work the release out from the enrolled counts and the pacing before asking for the confirmation, and say out loud that the number is an estimate rather than a reading. +- `schedule.resolve` — **absent** + - *Because:* not evidenced — nothing documented returns a resolved calendar. The schedule can be read and so can a linked holiday calendar, but the day-by-day answer for a campaign or for one person, showing what a weekend, a holiday or a closed window moved, has to be computed and cannot be checked against anything. +- `send_window.resolve` — **absent** + - *Because:* not evidenced — no documented surface answers when one person may be contacted on one channel. Some inputs are readable, being the schedule's windows, its timezone policy and its linked holiday calendars, but legal quiet hours in the recipient's local time and operator blackouts are not modelled at all, so the parts that carry legal weight are the ones missing. +- `blackout.define` — **partial** + - *Missing:* Named date ranges exist, with an annual-repeat flag. Defer-or-skip does not: nothing states whether the touches a range stops come back afterwards or are lost, which is half of what the contract asks the user to decide. Nor does the create call take the region the range applies to, so whose region applies cannot be stated at the moment the range is drawn. + - *Surface:* holiday-calendars -> Create a holiday calendar, Update a holiday calendar; schedules -> Link a holiday calendar to a schedule + - *Notes:* A calendar suppresses nothing until it is linked to a schedule, and it then applies to every campaign on that schedule. Linking is the act; creating is not, and reporting the create as the blackout is how a holiday range ends up suppressing nothing. +- `blackout.remove` — **partial** + - *Missing:* The lift itself works. The preview does not: nothing says whether removing a range opens a window that is open right now on a live campaign, or how many messages go out as a result — and that preview is what the contract uses to decide whether this is an act at all. Here it has to be reasoned out instead of read. + - *Surface:* schedules -> Unlink a holiday calendar from a schedule; holiday-calendars -> Delete a holiday calendar + - *Notes:* Unlink lifts the suppression for one schedule; delete removes the calendar from every schedule that used it. They are different-sized acts, and the user should be told which one is being proposed before they agree to it. +- `frequency_policy.define` — **absent** + - *Because:* not evidenced — no documented surface caps how often one person, account or domain hears from us across campaigns. The per-campaign same-domain limit is the nearest thing and is a different promise: one campaign's contacts-per-domain-per-day, not a cross-campaign, cross-channel cap. Offering it as one would let three campaigns touch the same person in a day while the limit reports as respected. +- `frequency_policy.get` — **absent** + - *Because:* not evidenced — there is no cap to read, since none can be defined, and the per-campaign same-domain limit answers a different question. +- `capacity.estimate` — **absent** + - *Because:* not evidenced — nothing projects whether a plan can physically run. Sending capacity, pacing and existing load are each readable somewhere, but no surface puts them against a planned volume over a stated horizon. Any answer is the agent's own arithmetic over several reads and has to be reported that way, with the reads it rests on named. + +## 06 — Steps, content and content policy + +*The programme* · [mapping-06-steps.md](mapping-06-steps.md) + +- `step.add` — **partial** + - *Missing:* Position is not settable. The create body has no position, order or index field, so a step lands after the ones already made and no reorder endpoint exists to correct it. Content is inline on the step rather than bound to a template version, so a step cannot reference published copy. A branch is expressed as a condition step plus a parent reference and a positive-or-negative flag, and the evaluation window and early-satisfaction behaviour the contract asks for have no field at all. + - *Surface:* sequence-steps -> Create a sequence step, Bulk create sequence steps + - *Notes:* Channel and kind arrive together as one discriminated type — email, LinkedIn with its own action subtype, call, SMS, WhatsApp, task, condition — and the delay is a single minutes value, so the contract's unit and basis have to be reduced to minutes before the call. Complex step work, notably variants on a live sequence and LinkedIn steps, is often better handed to the product's own editor than approximated here. Say so and hand off rather than guessing. +- `step.update` — **partial** + - *Missing:* The step type is a discriminator and cannot be changed, so moving a step to another channel means delete and re-add, which loses the step's variants with it. Position is out of reach here for the same reason it is in step.add. + - *Surface:* sequence-steps -> Update a sequence step + - *Notes:* A full replacement rather than a patch — read the step first and resend every field you are not changing, or the delay and the copy you left out are gone. Nothing in the documentation restricts the call while the sequence is live, so the in-flight statement the contract requires is the agent's obligation and not the API's. +- `step.reorder` — **absent** + - *Because:* Neither Create a sequence step nor Update a sequence step exposes a position, order or index field, and no reorder endpoint is documented. Steps sit in the order they were created. Delete and re-add is not a substitute — it destroys variants and their measurement history, which is the exact loss this operation exists to prevent. +- `template.create` — **partial** + - *Missing:* No draft state. A template exists in one state and is usable the moment it is created, so the contract's guarantee that unreviewed copy cannot be sent is not enforced by the product and has to be carried by the approval gate instead. + - *Surface:* email-templates -> Create an email template + - *Notes:* Folders organise templates — read List email template folders and List email templates first, because reuse beats proliferation here as much as it does for lists. +- `template.update` — **partial** + - *Missing:* No versioning. The update replaces the content in place and no earlier version is kept, so the rule that a change always produces a new draft and never mutates published copy cannot be honoured. Keep the previous text yourself if anyone may need it back. + - *Surface:* email-templates -> Update an email template + - *Notes:* Steps hold their copy inline, so changing a template does not change what a live campaign sends. Those are two separate edits, and which one the user actually asked for is worth settling before either. +- `template.get` — **partial** + - *Missing:* No version list, no published or retired state, and no list of what binds it — steps carry their own copy, so there is nothing to report as a dependent. + - *Surface:* email-templates -> Get an email template, Get template variables + - *Notes:* Get template variables is the read that says which merge fields the copy needs, before anyone renders it against a real person. +- `template.list` — **partial** + - *Missing:* The second half of the question. Folders say where a template sits; nothing says whether its copy is draft, published or retired, because those states do not exist here. + - *Surface:* email-templates -> List email templates, List email template folders +- `template.publish` — **absent** + - *Because:* No version lifecycle is documented for templates. There is no draft, no published version and no publish endpoint — a template is usable from the moment it exists. Never present creating or updating one as publishing it. +- `template.retire` — **absent** + - *Because:* The same absent lifecycle. Delete an email template destroys the template rather than retiring a version, and it cannot answer the question this operation is really asking — which live campaigns still depend on this copy — so it must not be substituted. +- `content_policy.define` — **absent** + - *Because:* not evidenced — no documented surface was found for this. The blacklist rules govern which addresses and domains may be contacted, not what the copy may say, and substituting them answers a different question entirely. +- `content_policy.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `content_policy.check` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing takes a rendered message and returns the rules it breaks, so copy has to be checked against the account's rules outside the product before it is approved. + +## 07 — Messages + +*The programme* · [mapping-07-messages.md](mapping-07-messages.md) + +- `message.draft` — **partial** + - *Missing:* The render returns a subject and a body and nothing else. The footer, the identification block and the unsubscribe mechanism the contract requires the draft to show are absent from the response, so what is previewed cannot be proved to be the whole of what would leave. Merge values that are missing or wrong are reported, which is the part it does keep. + - *Surface:* email-templates -> Render an email template, Get template variables + - *Notes:* Renders against one contact identifier, optionally in the context of a campaign and a sending identity so their variables resolve too. Two other renders exist and both carry a beta mark — Get sequence preview for a contact under sequence-contacts, and Generate an AI draft reply under inbox — so say beta out loud before planning a route through either. +- `message.send` — **partial** + - *Missing:* Inside a thread, only a reply. The contract's message.send is one message to one person on one channel, including the first one: from reply-cli 0.17.0 the direct sends (an email, a LinkedIn message, InMail or voice message) send the first one outside any campaign, where the account's Reply has the route; inside a campaign a first message is the campaign's step, with no surface here. + - *Surface:* inbox -> Send a reply within a thread + - *Notes:* The reply goes out on the thread's own channel. If that channel's account is disconnected the send fails — tell the user to reconnect, and never switch channel silently. Where the runtime carrying the work passes the reserved `provider` key inside the operation's arguments, `args.provider`, and the send is a direct send by email, that object is `{"schedule_id": ""}` and nothing else: the `id` of a schedule from `reply schedule list`, written as a string of its digits. It goes as `--schedule-id` (from reply-cli 0.17.0). Another shape or another key is refused before anything is sent, with a message naming the shape; write the object in that shape and ask again. Reply refuses a schedule on every LinkedIn direct send in this version (scheduleId is not supported for LinkedIn sends in this version, a 400 on each LinkedIn route), so a schedule on a LinkedIn message is refused before any call. A message composed as a template goes by the same command, in Reply's own syntax, and Reply fills it in for the contact: a send Reply makes within the call is filled in before anything goes and refused with nothing sent where Reply cannot fill it; one held for a later moment or a schedule, or queued behind the account's other sends, is filled in when it goes and fails then. The codes, the names Reply lists, the LinkedIn sending account's two names and the formats that are never filled in are under reply-api, Direct sends, Templates. +- `message.schedule` — **partial** + - *Missing:* Only a send outside any campaign, and only where the account's Reply has the route. From reply-cli 0.17.0 the direct sends take `--send-after`, a moment with its offset, which the CLI sends as UTC, and Reply holds the send until then; a moment already past is sent at once. A Reply that does not keep a direct send for later answers a bare 404, and nothing is scheduled. The contract's read before repeating — the pending sends for this person on this thread — has no list surface here: a harness that keeps the reference reads and cancels by it. + - *Surface:* direct-outreach -> the direct sends (an email, a LinkedIn message, InMail or voice message, and Send a LinkedIn connection request to a contact), each with its send-after moment + - *Notes:* From reply-cli 0.17.0, send with `--idempotency-key`, which goes as the Idempotency-Key header: the same request repeated under the same key answers the send Reply took and sends nothing twice, so a lost answer is repeated under the key rather than read around. Reply honours the key only where it has the direct-send routes, so read `reply direct-send get` of a reference first (from reply-cli 0.17.0): its own `direct_send.not_found` or `direct_send.not_owned` says the routes are there, a bare 404 says they are not, and a key sent there protects nothing. The answer names the send's `reference` and its `state`: `sent` means it went, `failed` and `cancelled` are final, and any other state means Reply holds it and it has not gone yet. Keep the reference; it is the only handle on the send, and after a lost answer `reply direct-send get` of it is read before any repeat. Reply keeps a key for a day, so a repeat goes under it only within 23 hours of the first try; past that, nothing is sent again. From reply-cli 0.17.0 an email direct send also takes `--schedule-id`, a schedule from `reply schedule list`; Reply refuses it on every LinkedIn route. Reply then holds the send until the schedule's first opening at or after the moment, or after now where none is given, and the answer names no moment: Reply estimates one only where the schedule opens within 30 days, and reply-cli does not pass the estimate. A manual-email task dated for the 14th is still queued work for a person, not a queued send. +- `scheduled_message.list` — **absent** + - *Because:* No surface lists the pending sends — not by person, campaign or sender. From reply-cli 0.17.0, `reply direct-send get ` reads one send by its reference — its state, its moment, when it went and why it failed — which answers for a send already known and never for "what is queued". A harness that keeps the reference reads and cancels by it. +- `scheduled_message.cancel` — **partial** + - *Missing:* By reference only, and only where the account's Reply has the route. From reply-cli 0.17.0, `reply direct-send cancel ` cancels one direct send still held for its moment. Nothing lists the pending sends, so a harness that keeps the reference reads and cancels by it; a send whose reference was not kept cannot be found to cancel. What is pending in a live participation is still the next touch of a campaign, and stopping that is enrollment.pause or enrollment.stop rather than this. + - *Surface:* direct-outreach -> the direct send's cancel, by its reference + - *Notes:* A cancel of a send already cancelled is a success, and one whose answer was lost is safe to run again. A send that has gone answers `direct_send.already_sent` and one that failed `direct_send.already_failed`: report it as gone or failed, never as cancelled. A bare 404 means the account's Reply does not have the route yet. + +## 08 — Enrollment + +*The programme* · [mapping-08-enrollment.md](mapping-08-enrollment.md) + +- `enrollment.pause` — **partial** + - *Missing:* No reason is accepted and there is no dated automatic resume. The hold is a bare status, so why someone was held and when they should carry on again survive only wherever the agent chooses to write them down. + - *Surface:* sequence-contacts -> Set contacts' status in this sequence + - *Notes:* At most one hundred people per call, and only a participation that is currently active can be held. The response returns failures keyed by person and an empty object when every one succeeded — reconcile per person rather than reading that empty object as a count. +- `enrollment.resume` — **partial** + - *Missing:* Setting a participation back to active is accepted from any current state, so the refusal the contract requires — resume only what is actually held — is not enforced by the API. The check-first read has to perform it, or a finished participation is quietly restarted and someone is written to again. + - *Surface:* sequence-contacts -> Set contacts' status in this sequence + - *Notes:* On a live campaign this sends. The preview naming who resumes is the approval artefact and knowing which endpoint performs the call softens nothing about that. +- `enrollment.stop` — **partial** + - *Missing:* The mandatory reason. The body carries identifiers and nothing else, so neither why someone was taken out nor that a different person was the cause can be recorded — and naming that other person is part of the operation, not a nicety. Record the reason wherever the run itself is recorded. + - *Surface:* sequence-contacts -> Remove contact from sequence, Bulk remove contacts from sequence + - *Notes:* The bulk response counts requested, removed, not found and not in sequence, and lists the identifiers actually removed. An already-absent participation reads as a completed stop. +- `disposition.set` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Marking someone replied or bounced records what happened to a message, and an inbox category records what a reply meant; neither is the business outcome of the participation, and pressing one into service as a stand-in corrupts the number people are measured on. + +## 09 — Conversations and activity + +*The conversation, the queue and the day* · [mapping-09-conversations.md](mapping-09-conversations.md) + +- `conversation.classify` — **partial** + - *Missing:* The meaning is recorded, its provenance is not. No field carries who decided it, which message they decided it from, or how sure they were, so a category set by a model and one set by a person are indistinguishable afterwards. + - *Surface:* inbox -> Assign or clear a thread's category, Assign threads to a category + - *Notes:* The vocabulary is the account's own inbox categories — read List inbox categories first and map onto what exists rather than inventing a label. Re-read the thread to confirm it took. +- `conversation.assign` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Assign threads to a category and Assign or clear a thread's category move a thread between categories, not between people, and the resemblance in the names is exactly the trap. Changing who owns the person is a different act with different consequences and is not a substitute. +- `conversation.snooze` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing takes a thread out of the queue and brings it back on a date. +- `conversation.close` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Mark threads as read records a read state, not a worked one, and deleting a thread destroys it. Neither says the thread was dealt with, which is the whole of what closing one means. +- `conversation.reopen` — **absent** + - *Because:* Nothing closes a thread here, so nothing reopens one. Mark threads as unread is the nearest surface and it says something else. +- `referral.record` — **absent** + - *Because:* not evidenced — no documented surface was found for this. The pieces exist separately, since the named person can be created and the referrer can be taken out of the campaign, but nothing records that the one came from the other — and that link is the only fact that justifies contacting a stranger, so performing the two calls without it is not the operation. +- `activity.log` — **partial** + - *Missing:* Only the note. A free-text note is one of the things this operation records; an email sent from a personal client, a conversation in a corridor, or a message on a channel we do not send from cannot be logged as an activity with its channel, direction and time, so the record stays an incomplete account of what happened to this person. + - *Surface:* contacts -> Add a note to a contact + - *Notes:* Get activities for a contact is the read that shows what the product recorded itself, and a note is not guaranteed to appear in it. Check before telling the user the record is whole. + +## 10 — Task queue and touches + +*The conversation, the queue and the day* · [mapping-10-tasks.md](mapping-10-tasks.md) + +- `task.skip` — **absent** + - *Because:* The documented task states are new, finished, cancelled, archived and detached from a campaign, and none of them is skipped. The update endpoint cannot set a state at all, so declining a task while recording that it was declined has no surface. Completing it instead would put a lie in the record. +- `task.cancel` — **partial** + - *Missing:* Dropping the work is possible, recording that it was deliberately dropped is not. Deletion destroys the task, and the cancelled state the documentation describes cannot be set through the update endpoint, so afterwards nothing distinguishes work called off from work that was never there. + - *Surface:* tasks -> Delete a task, Bulk delete tasks + - *Notes:* Say the deletion is irreversible before doing it. The contract treats this operation as compensatable and on this surface it is not, which is a difference the user has to hear first rather than discover. +- `call.place` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Execute and complete a task, the only endpoint that performs a task's action, supports manual email and SMS and rejects every other type, so a call task cannot be dialled through the API. Calls are placed in the product, and the user needs telling that plainly. +- `call.log` — **absent** + - *Because:* not evidenced — call activity is readable through reporting, under Get calls reporting overview and List call activity, and nothing writes one. A call that happened away from the product cannot be recorded here. +- `call_recording.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this, and none for the agreement that permitted the recording either. +- `call_recording.discard` — **absent** + - *Because:* not evidenced — no documented surface was found for this. A recording that has to be destroyed must be dealt with in the product, and that has to be said out loud rather than left for the user to assume an agent handled it. + +## 11 — Meetings, qualification and handoff + +*The conversation, the queue and the day* · [mapping-11-meetings.md](mapping-11-meetings.md) + +- `meeting.propose` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing offers times and nothing hands over a way to pick one. Toggle thread meeting-intent marks that a thread is about a meeting and proposes nothing, so it must not be read as a booking surface. +- `meeting.book` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Meetings appear in reporting as facts that already happened; no endpoint creates one, issues an invitation, or records a meeting that was invited elsewhere. +- `meeting.confirm` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is nothing to read a meeting's attendee responses from and nothing that chases the people who have not answered. +- `meeting.reschedule` — **absent** + - *Because:* not evidenced — no documented surface was found for this. With no booking surface there is no meeting here to move. +- `meeting.cancel` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Tell the user to cancel it in the calendar rather than leaving someone expecting a meeting nobody will attend. +- `meeting_outcome.record` — **absent** + - *Because:* not evidenced — the meetings report carries when a booking was made, by whom, from which campaign and on which channel, and no outcome field of any kind. Held, no-show and cancelled beforehand cannot be told apart here, which also means meeting outcomes cannot be read back out of this product later. +- `meeting.list` — **partial** + - *Missing:* A booking ledger rather than a calendar. A row gives who booked it, the channel it came from, the person, the campaign and when the booking was made — not when the meeting is, who is attending, how to join, or how it went. Nothing upcoming can be answered from it and no outcome can be read out of it. + - *Surface:* reports -> List meetings + - *Notes:* Filterable by date window and by user, so it does answer how many meetings were booked and by whom over a stated period. Measurement is rate-limited harder than the rest of the surface — sequential calls, cached within the session, no polling. +- `meeting.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. The reporting list is the only place a meeting appears at all and it has no per-meeting read. +- `qualification.record` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Custom fields could be made to hold the answers, but that is a schema somebody would have to invent, and inventing it here would produce a record no other run could read back. +- `handoff.create` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Changing who owns a person moves the record; it makes no offer, starts no clock, and can be neither accepted nor refused, so it is not this operation. +- `handoff.accept` — **absent** + - *Because:* Nothing creates a handoff here, so there is nothing to accept and no commitment clock to start. +- `handoff.reject` — **absent** + - *Because:* Nothing creates a handoff here, so there is nothing to refuse. +- `handoff.return` — **absent** + - *Because:* Nothing creates or accepts a handoff here, so there is nothing to give back. +- `handoff.withdraw` — **absent** + - *Because:* Nothing creates a handoff here, so there is nothing to pull back. +- `handoff.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing shows what has been handed over and left unanswered, in either direction. +- `handoff.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `opportunity.create` — **absent** + - *Because:* not evidenced — no documented surface was found for this. A conversion into a deal is recorded wherever the pipeline lives, and this adapter has no view of that. Name the system the user should record it in rather than approximating it with a field on a person or an account. + +## 12 — Signals and triggers + +*The conversation, the queue and the day* · [mapping-12-signals.md](mapping-12-signals.md) + +- `signal.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing reports that someone changed job, visited a page, raised funding or engaged publicly. + - *Notes:* ai-sdr-intent-signals -> Industries typeahead, Technologies typeahead is the nearest thing and it is not this: it resolves the words a user says into values a prospect search accepts. Offering it here answers a different question than the one asked. +- `signal.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Without a feed there is nothing to read one observation from. +- `signal.acknowledge` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `signal_policy.define` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing arbitrates between two things firing on the same person, because nothing fires. +- `signal_policy.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `trigger.create` — **partial** + - *Missing:* Only the watching half. A subscription delivers a named event to a listener outside the product; the rule's other half — producing work in response — has no surface, so the acting side must live in the agent runtime. The watchable set is fixed and product-side (message sent, opened, clicked, replied, bounced; contact opted out or finished; connection request sent and accepted; account connection lost or erroring), so a rule that must watch something outside that set cannot be expressed at all. + - *Surface:* webhooks -> Create a webhook subscription, List supported event types + - *Notes:* Read List supported event types before promising a rule — the event names are the whole vocabulary, and a trigger written against an event that is not on that list will never fire rather than failing loudly. +- `trigger.update` — **partial** + - *Missing:* The same half as trigger.create: what the rule watches can be changed, what it produces cannot, because production is not in the product. + - *Surface:* webhooks -> Update a webhook subscription, Enable a webhook subscription, Disable a webhook subscription + - *Notes:* "Switch it off without losing it" maps exactly onto Disable, which is the reversible move. Deleting a subscription to stop it and re-creating it later is not the same act and loses the subscription's history. +- `trigger.list` — **partial** + - *Missing:* What each rule watches is listed; what it produces is not, and cannot be, since the producing half is external. Report the watch, and say plainly that the action behind it is the runtime's and not the product's. + - *Surface:* webhooks -> List webhook subscriptions, List supported event types +- `trigger.delete` — **partial** + - *Missing:* Removes the watch only. Whatever the agent runtime built on top of that event keeps existing and has to be taken down separately, or it becomes a rule waiting on an event that will never arrive again. + - *Surface:* webhooks -> Delete a webhook subscription +- `trigger_run.list` — **partial** + - *Missing:* Deliveries, not runs. The log says which event fired and whether it reached the listener; what work came out of it and what a policy held back are not recorded, because neither the work nor the policy exists on this side. Never report a delivery count as a count of work done. + - *Surface:* webhooks -> Get webhook delivery logs + +## 13 — Inbound + +*The conversation, the queue and the day* · [mapping-13-inbound.md](mapping-13-inbound.md) + +- `inbound_lead.record` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is no inbound-lead or form-capture group: an arrival has nowhere to be recorded as an arrival, with the clock the rest of this family depends on. + - *Notes:* Do not simulate the queue out of tasks, contact owners or inbox categories. Those entities have their own meanings and their own operations, and an arrival modelled as a task loses the one thing that made it an arrival — the response clock. +- `inbound_lead.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `inbound_lead.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `inbound_lead.route` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is no routing rule — territory, existing owner, round-robin or availability — anywhere in the documentation. + - *Notes:* Contact and account ownership can be changed, but changing an owner is not routing an arrival: it carries no rule, no queue and no clock, and reporting it as routing would claim a guarantee that was never made. +- `inbound_lead.claim` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `inbound_lead.release` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `inbound_lead.triage` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing classifies what kind of request an arrival is. + - *Notes:* Inbox categories classify reply threads on conversations we started. That is a different act on a different entity, and it is covered by its own contract operation. +- `inbound_lead.close` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `inbound_lead.reopen` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `response_policy.define` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No response target can be stated, so none can be measured or breached. +- `response_policy.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. + +## 14 — Consent, suppression and privacy + +*Permission and capability* · [mapping-14-privacy.md](mapping-14-privacy.md) + +- `outreach.precheck` — **partial** + - *Missing:* It answers one question — is this person opted out or excluded on email — and the operation asks four. There is no channel dimension, so a social or phone precheck is not covered. There is no timing half, so "if not, when" cannot be answered. There is no consent basis and no external-register gate. Nothing says what would fix it. Say all of this before a user commits to a route that treats the precheck as sufficient. + - *Surface:* contacts -> Get a contact's statuses; contact-blacklist-rules -> List email blacklist rules, List domain blacklist rules, List email exception blacklist rules + - *Notes:* The result is stale the moment it returns, here as in the contract. Nothing about knowing which endpoint answers it changes that. +- `suppression.check` — **partial** + - *Missing:* The "why". A rule carries its pattern and whether it is system-wide, and nothing else — no reason class comes back, so the answer is yes-or-no with no ground for it. Only email addresses and domains are covered; a number, a social profile or a whole account has no equivalent. + - *Surface:* contact-blacklist-rules -> List email blacklist rules, List domain blacklist rules, List email exception blacklist rules + - *Notes:* The listings filter by pattern, so a raw identifier can be checked without it being a contact in the system — which is the part of this operation that matters. +- `suppression.list` — **partial** + - *Missing:* Three separate lists rather than one, and none of the three facets the operation promises: no scope, no reason class, no record of who added the entry. Numbers, social profiles and whole accounts are not represented at all. + - *Surface:* contact-blacklist-rules -> List email blacklist rules, List domain blacklist rules, List email exception blacklist rules +- `suppression.add` — **partial** + - *Missing:* "And here is why" has nowhere to go — no reason is recorded against a rule, so the reason has to be kept in the agent's own record or it is lost, and suppression.remove later has nothing to weigh. Numbers, social profiles and whole accounts have no equivalent. + - *Surface:* contact-blacklist-rules -> Create an email blacklist rule, Create a domain blacklist rule, Bulk create email blacklist rules, Bulk create domain blacklist rules + - *Notes:* The contract's read-before-repeating has a real surface here: search the listing for the pattern first. Adding a pattern that already exists is a refusal, so a blind retry is wrong. +- `suppression.remove` — **partial** + - *Missing:* The evidence that licenses the lift is not recorded, and no retention floor is exposed to check against — so the one guard the contract puts on this irreversible act cannot be enforced by the product and must be enforced by the agent before the call. Email addresses and domains only. + - *Surface:* contact-blacklist-rules -> Delete an email blacklist rule, Delete a domain blacklist rule, Bulk delete email blacklist rules, Bulk delete domain blacklist rules +- `optout.record` — **partial** + - *Missing:* It records the exclusion, not the act. What they said, where it arrived, when they did it and when we learned of it have nowhere to go, so the evidence that this was their decision is not retained. The product carries its own opted-out state on a contact — readable through Get a contact's statuses — but no documented surface sets it. + - *Surface:* contact-blacklist-rules -> Create an email blacklist rule, Bulk create email blacklist rules + - *Notes:* This is the protective floor operation: recording that somebody said stop is performed first and reported immediately. A blacklist rule stops future sends, which is the effect that matters most; keep the act itself in the agent's own record alongside it. +- `optout.poll` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing pulls un-ingested stop signals from the channel — one-click unsubscribes, list-unsubscribe requests, blocks or stop keywords. + - *Notes:* The notification surface carries a contact-opted-out event. That is a push about an opt-out the product has already ingested, not the backlog of ones it has not, and the two are not interchangeable: subscribing to it tells you nothing about what is waiting at the channel. +- `optout.confirm` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No opt-out confirmation exists as its own act, and no ledger records whether one was already sent. + - *Notes:* A direct email to a contact can be sent, and using it for this is the substitution to refuse. This confirmation is exactly-once, non-promotional and may never require anything of the recipient; with no ledger to check, a second one is a breach rather than a duplicate, and nothing here would stop it. +- `consent.record` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is no permission record: what they were told, when, how it was captured and what it covers have nowhere to live. +- `consent.revalidate` — **absent** + - *Because:* not evidenced — no documented surface was found for this. With no basis recorded there is nothing to recompute and no contactability to downgrade. +- `consent.prove` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `notice.send` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Neither the delivery of a privacy notice nor the record that it was delivered has a surface. +- `disclosure.check` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `disclosure.record` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing binds a disclosure to the message that carried it. +- `dnc_registry.check` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No external do-not-contact register is reachable from here; the blacklist rules are our own list, not a jurisdiction's. +- `privacy_request.create` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is no privacy-request entity, so no clock starts and nothing later can be tied to a request. +- `privacy_request.update` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `privacy_request.refuse` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `privacy_request.fulfill` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is no recorded request to fulfil against, and no export of everything held about a person. + - *Notes:* Contacts can be deleted, singly and in bulk. That is contact.delete, a different contract operation with a different meaning, and performing it must never be reported as fulfilling a privacy request: the request record is the whole point of this operation and it does not exist here. +- `deletion_feed.poll` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No external erasure register is reachable from here. +- `deletion_feed.report` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `retention.apply` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No storage limit can be stated or enforced, and no floor is exposed to stop at. +- `audit_log.search` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is no audit surface: who changed what, when, on our side is not answerable. + - *Notes:* A contact's activity history is the record of outreach that touched that contact. It is not a record of our own changes, and it cannot answer why this person was contacted at all — which is the harder half of the question and the one that gets asked under pressure. + +## 15 — Sending capability and deliverability + +*Permission and capability* · [mapping-15-sending.md](mapping-15-sending.md) + +- `sender.list` — **partial** + - *Missing:* Two lists rather than one, and only two of the four capability classes. Mailboxes and social accounts are covered; numbers and business messaging identities have no group at all, so a channel the user asks about may be invisible rather than empty. + - *Surface:* email-accounts -> List email accounts, Filter email accounts; linkedin-accounts -> List LinkedIn accounts, List pending LinkedIn accounts + - *Notes:* Merge the two and label every row with its channel, or the caller cannot tell what it is looking at. Read the pending social list too: a half-finished connection must read as pending setup, never as absent, and leaving it out is how a sender that is nearly ready gets connected a second time. +- `sender.get` — **partial** + - *Missing:* Identity, channel and configured pacing come back. Pool membership and registration do not, because neither concept exists here — see sender_pool.* and messaging_registration.*. Mailboxes and social accounts only. + - *Surface:* email-accounts -> Get an email account; linkedin-accounts -> Get a LinkedIn account +- `sender.health` — **partial** + - *Missing:* Connection state and configured limits are readable, and the mailbox read reports whether the provider has locked or throttled the account. Warm-up position, the channel's automation sanction, and any statement of how much of today's capacity is still available are not exposed — so three of the five things this operation promises have to be tracked by the agent or left unanswered. Numbers and business messaging identities are not covered. + - *Surface:* email-accounts -> Get an email account, Test SMTP connectivity, Test IMAP connectivity; linkedin-accounts -> Get a LinkedIn account + - *Notes:* The connectivity tests verify the credential actively rather than reporting a cached status, which is the difference that matters when an account looks fine and is not. A disconnected or erroring account is still a hard stop: this is a core operation and the launch chain refuses on it. +- `sender.connect` — **partial** + - *Missing:* Mailboxes and social accounts only; numbers and business messaging identities have no surface. On the social channel the call produces a link a person has to complete, so the operation is not finished when the call returns. + - *Surface:* email-accounts -> Create an email account, Connect Gmail account via OAuth, Connect Office 365 account via OAuth; linkedin-accounts -> Create a connection link, Create a direct connection link + - *Notes:* Poll the pending social list until the account appears in the real one. Until then it is the contract's pending-setup state, and reporting it as connected is how a campaign gets launched against a sender that cannot send. +- `sender.disconnect` — **partial** + - *Missing:* It deletes rather than detaches, and the guard the contract puts on this operation is absent: nothing refuses while live enrolments or open conversations still depend on the sender, and no rebind target can be supplied. The check is the caller's, and it has to happen before the call because there is nothing to undo afterwards. + - *Surface:* email-accounts -> Delete an email account, Bulk delete email accounts; linkedin-accounts -> Delete a LinkedIn account, Bulk delete LinkedIn accounts + - *Notes:* What is bound to a sender is readable only one campaign at a time (sequence-email-accounts -> List email accounts in sequence; sequence-linkedin-accounts -> List LinkedIn accounts for a sequence), so the check is a scan. On the social channel sender.pause is the reversible alternative and is usually what the user actually wants. +- `sender.reauthorize` — **partial** + - *Missing:* Only the social channel has a reconnect that names the existing account. On a mailbox the documented route is re-running the provider connection, and nothing states that the history behind it survives — which is the whole promise of this operation. Verify by re-reading rather than assuming, and tell the user what you could not confirm. + - *Surface:* linkedin-accounts -> Reconnect a LinkedIn account; email-accounts -> Connect Gmail account via OAuth, Connect Office 365 account via OAuth +- `sender.pause` — **partial** + - *Missing:* Social accounts only. A mailbox has no documented pause — the resume surface exists with no counterpart — so on email the protective move has to be made one level up, at campaign.pause or by removing the sender from the campaign. Say which one you used, because they are not the same blast radius. + - *Surface:* linkedin-accounts -> Toggle LinkedIn account status + - *Notes:* The social call flips between enabled and disabled rather than setting a state. Read the account first: issued blind against an already-paused account it re-enables it, which turns the first move in an incident into the worst one. +- `sender.resume` — **partial** + - *Missing:* Nothing refuses the resume on an invalid warm-up position, because no warm-up position is exposed at all — the contract's guard has to be enforced by the caller or it is not enforced. The mailbox surface is scoped to accounts the provider locked or throttled, not to an operator pause, and no operator pause exists on that channel. + - *Surface:* email-accounts -> Resume sending; linkedin-accounts -> Toggle LinkedIn account status + - *Notes:* Resolve the underlying problem before calling, then re-read the account to confirm the lock actually cleared. The social call flips rather than sets — read state first, same as with sender.pause. +- `sender_limit.set` — **partial** + - *Missing:* The contract's one decision is two different surfaces, one per channel, and only the social one is a dedicated limits endpoint — on a mailbox the limits ride on the account update, so a careless call can overwrite settings the caller did not intend to touch. Numbers and business messaging identities have no surface. + - *Surface:* linkedin-accounts -> Update LinkedIn account limits; email-accounts -> Update an email account + - *Notes:* Read the limits in force first and re-read after: report what actually took, not what was requested. Lowering is protective; raising is the direction that needs the approval, and the mapping does not change that. +- `warmup_plan.set` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No ramp can be defined, read or started, and no warm-up position is exposed anywhere in the API. + - *Notes:* This is the absence that costs the most in this family: sender.resume refuses on the warm-up position, and with no position readable that refusal cannot be automated. Tell the user the ramp is theirs to hold, and hold it in the agent's own record. +- `message_element.set` — **absent** + - *Because:* not evidenced — no documented surface was found for this. The legal identification block, the postal address, the channel's stop artefacts and the tracking domain have no per-sender configuration surface. +- `sender.reserve` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is no allowance reservation, so two parallel runs against one sender can spend the same capacity twice and neither will be told. +- `sender.release` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing to give back, since nothing can be claimed. +- `sender.summarize` — **absent** + - *Because:* The per-sender figures surface is documented Coming soon and is not callable today. Say that rather than reaching for something adjacent, and check the page again before planning around it. + - *Surface:* email-accounts -> Get email account stats, Filter email account stats + - *Notes:* The reporting overview is account-wide, not per sender, and answers a different question. Substituting it produces a number that looks like this sender's and is not, which is worse than having none. Even when the stats surface opens, failures by class, complaints with their publisher and denominator, deferrals and throttles are not promised by it. +- `restriction.record` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is no restriction ledger, so a restriction cannot be recorded, counted, or carried forward. + - *Notes:* The arrival of one is observable — the notification surface carries account-alert, connection-lost and account-error events, and the mailbox read reports a provider lock. What is missing is the durable record behind them. Keep it in the agent's own record: the recurrence count and the invalidated warm-up position both hang off it, and platforms escalate on how often a sender is restricted rather than on what for. +- `restriction.appeal` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No appeal route is exposed; where the platform offers one it is outside this API, and saying so plainly is the correct answer. +- `sender_pool.create` — **partial** + - *Missing:* There is no pool object. The grouping exists only as the set of senders bound to one campaign, so it cannot be named, cannot be created before the campaign exists, and cannot be reused by a second campaign without being rebuilt. Routing policy is not part of it. + - *Surface:* sequence-email-accounts -> Set sequence email accounts, Assign email account to sequence; sequence-linkedin-accounts -> Assign a LinkedIn account to a sequence + - *Notes:* Rotation across the bound senders is the product's own behaviour, so do not tell a user that sending across several senders is unavailable — that is a wrong answer, not a cautious one. What is unavailable is the reusable, named, independently routable pool. +- `sender_pool.update` — **partial** + - *Missing:* Membership changes, one campaign at a time. The routing policy does not — and sticky per recipient in particular is not selectable, which on a conversational channel is correctness rather than optimisation. Say that before a user commits to a route that needs a recipient to keep hearing from the same sender. + - *Surface:* sequence-email-accounts -> Set sequence email accounts, Assign email account to sequence, Remove email account from sequence; sequence-linkedin-accounts -> Assign a LinkedIn account to a sequence, Remove a LinkedIn account from a sequence + - *Notes:* Setting the whole set replaces it. Read the current members first, or a call meant to add one sender silently removes the rest. +- `sender_pool.list` — **partial** + - *Missing:* Pools cannot be enumerated. Every read is scoped to one campaign, so "what pools exist" is answerable only by walking every campaign, and how work routes across the members is not reported at all. + - *Surface:* sequence-email-accounts -> List email accounts in sequence; sequence-linkedin-accounts -> List LinkedIn accounts for a sequence +- `sender_pool.delete` — **partial** + - *Missing:* There is no pool to dissolve. Removing every binding leaves the campaign with no sender rather than dissolving a named group — nothing refuses it while the campaign is live and no replacement target can be supplied, so the campaign is left unable to send and nothing says so. + - *Surface:* sequence-email-accounts -> Remove email account from sequence; sequence-linkedin-accounts -> Remove a LinkedIn account from a sequence + - *Notes:* The capabilities themselves are untouched, as the contract expects: this removes bindings, not senders. +- `sending_domain.register` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Domains are not a first-class entity here; a sender carries its address and that is all. +- `sending_domain.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `sending_domain.retire` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `authentication_requirement.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this. What has to be published for a domain to authenticate is not stated anywhere in the API. +- `domain_compliance.check` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No verdict per publisher and per requirement is available, so a failing requirement cannot be named. +- `domain_reputation.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No reputation signal, blocklist listing or dataset is exposed. +- `message_compliance.check` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing evaluates a rendered message against what it will be held to: required elements, a working unsubscribe, or the reputation of the domains it links to. + - *Notes:* The rendered message itself can be obtained (email-templates -> Render an email template, Send a test email), so the check can be performed outside the product against a real rendering rather than against the source. That is worth doing, and it is not this operation — report it as an external check. +- `placement_test.create` — **absent** + - *Because:* not evidenced — no documented surface was found for this. There is no seed-list send and no per-provider placement result. + - *Notes:* The email-validation surface estimates and schedules address validation. That answers whether an address exists, never where a message lands, and offering it here would answer a deliverability question with a data-quality one. +- `placement_test.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `messaging_registration.submit` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No brand or use-case registration exists, because the channels that require one before any send is permitted are not represented in this API. +- `messaging_registration.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `approved_content.submit` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No content is submitted to a platform for pre-approval. + - *Notes:* The pending-approval surface in the AI-SDR cluster is a person inside the organisation approving generated content before it sends. This operation is a platform gating content before we are permitted to send it at all. They are different actors with different consequences for refusal, and mapping one onto the other would report an internal sign-off as a platform's permission. +- `approved_content.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `approved_content.retire` — **absent** + - *Because:* not evidenced — no documented surface was found for this. + +## 16 — Social and messaging channels + +*Permission and capability* · [mapping-16-social.md](mapping-16-social.md) + +- `social_invitation.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Invitations sent cannot be listed, so neither what is pending nor how old it is can be answered. + - *Notes:* The pending social-account listing is a different thing despite the similar name: it is accounts waiting to finish connecting to the product, not invitations waiting on people. Confusing the two produces a confident answer to a question nobody asked. +- `social_invitation.withdraw` — **absent** + - *Because:* not evidenced — no documented surface was found for this. A sent invitation cannot be taken back through the API. +- `social_invitation.accept` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `social_invitation.decline` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `social_relationship.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing answers, on demand, whether we are connected to this person or at what degree. + - *Notes:* The notification surface reports connection requests sent and accepted, so a standing relationship ledger can be maintained outside the product from those events. That is a ledger the agent builds and owns; it is not a read, and it knows nothing about people we never invited. +- `social_profile.view` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No profile read is exposed, metered or otherwise. +- `social_profile.follow` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `social_profile.unfollow` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `social_post.react` — **absent** + - *Because:* not evidenced — no documented surface was found for this. +- `social_post.comment` — **absent** + - *Because:* not evidenced — no documented surface was found for this. No published content can be posted under a person's identity through this API. +- `social_credit.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. The metered messaging allowance is not readable: how many credits remain, when they expire and whether a reply returns one are all unanswerable. + - *Notes:* A metered message can be sent without any way to check the balance first, so the meter is discovered by exhausting it. Warn the user before planning volume that depends on it. +- `conversation_window.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this. Nothing reports whether this person may be written to freely right now, only with pre-approved content, or only by spending a credit. + - *Notes:* Both routes exist as sends — an ordinary message and a metered one — but nothing says which is permitted for a given person, so the choice is the caller's and a wrong one fails at send time rather than at planning time. That is a real cost to surface before the user commits to a social route. + +## 17 — Oversight, review and safety + +*The organisation around the work* · [mapping-17-oversight.md](mapping-17-oversight.md) + +- `approval.request` — **absent** + - *Because:* No documented surface puts an item into a queue for a human. The pending-approval endpoints list, read, send, reject and regenerate items that are already there — the AI SDR sequence generates them itself under the approval mode set on that sequence, and nothing else can be queued for review. +- `approval.list` — **partial** + - *Missing:* Only AI-generated messages inside an AI SDR sequence reach this queue, on email and LinkedIn. A bulk write, a piece of content or a policy change waiting on a human has no queue here at all, so an empty queue does not mean nothing is waiting. + - *Surface:* ai-sdr-pending-approvals -> List pending approvals (documented Beta or Coming soon) + - *Notes:* Each item carries when it was created rather than how long it has waited — the age the operation reports is computed from that. The queue can be filtered by sequence and by user. +- `approval.get` — **partial** + - *Missing:* The item is addressed by contact rather than by an approval identifier, and only an AI-generated message is retrievable this way. Anything else a human is being asked to approve has no item to fetch. + - *Surface:* ai-sdr-pending-approvals -> Get pending approval for a contact (documented Beta or Coming soon) +- `approval.resolve` — **partial** + - *Missing:* Rejection records no reason and is heavier than the contract's reject: it discards the queued draft and removes the contact from the sequence, with nothing documented to bring either back. Tell the user that before they reject, and keep the reason wherever the run is recorded. + - *Surface:* ai-sdr-pending-approvals -> Send a pending approval, Send a batch of pending approvals, Reject (delete) a pending approval (documented Beta or Coming soon) + - *Notes:* Approving is the send, exactly as the contract has it, so the approval class is unchanged by the mapping — one named recipient is confirm_each, and the batch send is confirm_once over a preview that names the population. +- `autonomy.get` — **partial** + - *Missing:* One AI SDR sequence's own settings — whether its generated messages need approval, and whether autopilot is on. Nothing states what a credential may do unattended across the account, and there is no queue timeout, unattended action cap or escalation target to read. Everywhere else, autonomy is the agent's own policy held outside this product. + - *Surface:* ai-sdr-sequences -> Read AI SDR sequence settings (documented Beta or Coming soon) +- `autonomy.set` — **partial** + - *Missing:* The gate and the mode, on one AI SDR sequence. The queue timeout and what a timeout means, the unattended action cap, the escalation target and per-channel differences have no setting here. + - *Surface:* ai-sdr-sequences -> Set the approval mode, Enable autopilot, Disable autopilot (documented Beta or Coming soon) + - *Notes:* Turning the gate off can also release everything already waiting, in the same call. That makes loosening the gate a send, not a settings change, and it must be previewed and approved as one. +- `escalation.raise` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `escalation.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `escalation.resolve` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `editorial_review.record` — **absent** + - *Because:* not evidenced — no documented surface binds a named human's review to a sent message. A message approved out of the AI SDR queue records that it was sent, which is not the same fact and must never be reported as one. +- `editorial_review.get` — **absent** + - *Because:* not evidenced — nothing records the review, so nothing can return it. The honest answer to an auditor here is that no review evidence exists in this product. +- `review.request` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `review.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `review.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `review.score` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `feedback.record` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `review_policy.define` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `review_policy.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `scorecard.define` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `scorecard.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `scorecard.publish` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `scorecard.retire` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `coaching.summarize` — **absent** + - *Because:* not evidenced — the reporting surfaces cover activity and performance, not coaching. Nothing records that someone attended, listened, commented, scored or gave feedback, so there is nothing to summarise per coach. +- `budget.get` — **absent** + - *Because:* not evidenced — no documented surface reports what is left on a meter. A meter does exist: starting a Live Data search spends the user's data allowance. That the remaining allowance cannot be read is exactly why a search is previewed before it is started. +- `budget.set` — **absent** + - *Because:* not evidenced — checked against the endpoint index, nothing sets an allowance ceiling of the kind a pre-flight check reads. +- `stoprule.set` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `stoprule.list` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `stoprule.clear` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `stoprule_firing.list` — **absent** + - *Because:* not evidenced — nothing stops the work by itself here, so there are no firings to list. When sending is off in this product it was a person or an agent that stopped it, and the reason lives in the run record rather than in the API. +- `stoprule_firing.get` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `outreach.hold` — **partial** + - *Missing:* This blocks future contact and nothing else. Live enrolments, scheduled steps, open tasks, pending approvals and outstanding meeting proposals are untouched by it, and the rule returns no per-item ledger of who was actually reached. The kill switch the contract describes is only realised once those are stopped too, through their own operations, and every one of them has to be reported. + - *Surface:* contact-blacklist-rules -> Create an email blacklist rule, Create a domain blacklist rule, Bulk create email blacklist rules, Bulk create domain blacklist rules + - *Notes:* A person is held by an email rule and a company or a domain by a domain rule. Rules are account-wide, so check the existing rules before adding one and expect the block to apply to work other people own. +- `outreach.release` — **partial** + - *Missing:* Deleting the rule lifts the block, but nothing resumes by itself: whatever was stopped when the hold went on has to be restarted deliberately, and no ledger of what was held exists to restart it from. Re-check each person's eligibility first — the contract requires it and this product will not. + - *Surface:* contact-blacklist-rules -> Delete an email blacklist rule, Delete a domain blacklist rule, List email blacklist rules, List domain blacklist rules + +## 18 — The team: people, ownership, workload and targets + +*The organisation around the work* · [mapping-18-team.md](mapping-18-team.md) + +- `actor.list` — **partial** + - *Missing:* Identity only — the team, the user identifier, the display name and the email address. The state the operation asks for, active, ramping, unavailable or gone, is not carried, so this read cannot tell an agent whether the person it is about to hand work to is still there. + - *Surface:* user-account -> List team users + - *Notes:* No scope required. It covers the teams this credential can act in; people outside them do not appear, which is a different answer from not existing. +- `actor.get` — **partial** + - *Missing:* Only the calling credential has a record of its own. Anyone else is an identity row in the team listing and nothing more — no state, and none of the ceilings that apply to them. + - *Surface:* user-account -> Get current user, List team users +- `workload.get` — **absent** + - *Because:* not evidenced — checked against the endpoint index, nothing reports what a person is carrying. Open tasks and live enrolments can each be listed on their own, but no surface answers the question this operation asks, and adding up two listings is not the same answer. +- `workload_policy.define` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `workload_policy.get` — **absent** + - *Because:* not evidenced — no ceiling is declared anywhere, so the answer here is always none declared, which the contract reads as unlimited. +- `ownership.get` — **partial** + - *Missing:* The owner is an attribute of the record rather than a surface of its own, so it is read with the record. The second half of the question has no answer here at all: nothing states whether acting on an unowned record would make the actor its owner, and that rule is set in the product's own settings rather than returned by any response. + - *Surface:* accounts -> Get an account; contacts -> Filter contacts +- `assignment_policy.define` — **absent** + - *Because:* not evidenced — no documented surface was found for this +- `assignment_policy.get` — **absent** + - *Because:* not evidenced — no routing rule is stored in this product, so there is none to read and nothing that would say who gets the next piece of work. +- `book.transfer` — **partial** + - *Missing:* Three parts of the book move — contact ownership, account ownership and open tasks. The senders behind live threads, the open conversations and the authored content do not, and no surface reports the book as a whole, so the ledger the contract requires has to be built by the caller from what each call returns before anything is repeated. + - *Surface:* contacts -> Change contacts owner; accounts -> Update account owner; tasks -> Batch reassign tasks + - *Notes:* Reassigning ownership does not re-point the sending account behind a live thread. Say so before the transfer: a departing person's threads keep sending from their mailbox until the sequences are changed, and that is the part users are most often surprised by. +- `goal.define` — **absent** + - *Because:* not evidenced — checked against the endpoint index, this product stores no quota, goal or target, so there is nothing to set. +- `goal.get` — **absent** + - *Because:* not evidenced — no target is stored here, so there is none to read. +- `goal.list` — **absent** + - *Because:* not evidenced — no target is stored here, so there is none to list. +- `pace.get` — **absent** + - *Because:* not evidenced — pace is a target measured against achievement, and no target exists in this product. Achievement alone is readable through the reporting surfaces, and reporting it as pace would invent the half that is missing. + +## 19 — Accounts and buying groups + +*The organisation around the work* · [mapping-19-accounts.md](mapping-19-accounts.md) + +- `account.update` — **partial** + - *Missing:* The account's stage can be moved and the rest of the record edited, but the tier the contract names has no home on the record and neither does the reason for the change. The stages are whatever this account has declared, so resolve the words the user says against them before writing — a stage that does not exist is a guess. + - *Surface:* accounts -> Update an account +- `account.claim` — **absent** + - *Because:* not evidenced — there is no lease on an account here. Ownership can be changed, which is a different and heavier act: it does not expire by itself, and using it as a claim would leave the account permanently reassigned. +- `account.release` — **absent** + - *Because:* not evidenced — nothing claims an account, so there is nothing to release. +- `account_membership.list` — **partial** + - *Missing:* Who is attached, and no more. How each person came to be attached is not recorded, so the basis the contract wants on every row cannot be given, and whether someone is being touched right now needs a separate read against the sequence they are in. + - *Surface:* accounts -> List contacts for an account +- `collision.check` — **partial** + - *Missing:* Only outreach collisions are visible, and only by assembling them: the people on the account, then each one's state in the sequences they are in, then the owner on each record. A live customer, support or opportunity motion is invisible here — it lives in the CRM — so a clean answer from this check is not evidence that the company is free. + - *Surface:* accounts -> List contacts for an account; sequence-contacts -> List contacts in sequence with extended state, Get a contact in a sequence + - *Notes:* Re-run it immediately before enrolling. Collisions appear between planning and execution, and the gap is exactly where the embarrassing double-touch happens. +- `buying_group.define` — **absent** + - *Because:* not evidenced — people can be attached to an account, but nothing records what each of them does in a decision, so a group with roles cannot be expressed here. +- `buying_group.get` — **absent** + - *Because:* not evidenced — no group with roles is stored, so there is none to return. +- `buying_group.enroll` — **absent** + - *Because:* not evidenced — no surface enrols a group as a group. Enrolling several people from one account one by one is a different act: nothing staggers them, orders them, or reacts to one person's reply on behalf of the others, and doing it by hand while calling it this operation would hide exactly the coordination the operation exists for. + +## 20 — Measurement + +*The organisation around the work* · [mapping-20-measurement.md](mapping-20-measurement.md) + +- `engagement.summarize` — **partial** + - *Missing:* The grouping is not an argument. Each report offers the one breakdown it was built for — by channel, by sequence, by team member — and a question that needs a different grouping has to be assembled from the rows behind the numbers instead. The measure set is likewise the report's, not the caller's. + - *Surface:* reports -> Get email reporting overview, Get calls reporting overview, Get tasks reporting overview, Get LinkedIn reporting overview, Get channel efficiency overview, Get team performance overview; sequences -> Get stats for all sequences, Get sequence stats + - *Notes:* These endpoints are rate-limited harder than the rest of the API: sequential calls, cached within the session, no polling. Report the window alongside every figure — two numbers are only comparable when the window and the basis match. +- `funnel.summarize` — **partial** + - *Missing:* No surface returns a ladder. The stages come from separate reads, and neither the denominator a stage is measured against nor how well that stage can be known at all is stated anywhere — the caller declares both and has to say so when reporting the result. Stages past the meeting are not covered by any of these. + - *Surface:* reports -> Get email reporting overview, Get channel efficiency overview, List meetings +- `opportunity.summarize` — **absent** + - *Because:* not evidenced — checked against the endpoint index, nothing here carries opportunities or revenue. That answer lives in the CRM, and reporting meetings as though they were the far end of the funnel would overstate what is known. +- `attribution.explain` — **absent** + - *Because:* not evidenced — no attribution model is stated anywhere, so nothing can explain why an outcome was credited where it was, or what another model would have said. +- `response_time.summarize` — **absent** + - *Because:* not evidenced — no documented surface reports time from arrival to first touch, or from a reply arriving to it being answered. +- `metric.describe` — **absent** + - *Because:* not evidenced — checked against the endpoint index, there is no enumeration or definition surface. What a figure means here is prose on its report page, read by a human, and it says nothing about how far the figure can be trusted. +- `metric.compare` — **absent** + - *Because:* not evidenced — no surface compares two arms or reports a sample size and an interval. Two report calls placed side by side are not this operation: the arithmetic that says whether the difference means anything is the part that is missing. +- `export.request` — **absent** + - *Because:* not evidenced — checked against the endpoint index, no general data export exists. The reporting listings return rows inline and paginated, which is a read rather than a bounded extract, and treating one as the other would move personal data with none of the handling an extract implies. +- `export.get` — **absent** + - *Because:* not evidenced — nothing produces an extract here, so there is none to collect. + +## 21 — Introspection and runtime + +*The organisation around the work* · [mapping-21-introspection.md](mapping-21-introspection.md) + +- `operation.search` — **absent** + - *Because:* Nothing in this product answers it, and nothing should — the thing being searched is the contract, which the core pack carries. Recorded absent because this register answers only for what this adapter performs. +- `operation.describe` — **absent** + - *Because:* As above: an operation's meaning, its refusals and its five properties come from the contract in the core pack, not from any API surface here. +- `operation.preview` — **partial** + - *Missing:* There is no general dry run. Three specific acts can be previewed, all of them beta, and every other write is knowable only by performing it — which means that for most operations the preview an approval gate wants has to be assembled from reads before the write, not requested from the product. + - *Surface:* sequence-contacts -> Get sequence preview for a contact; ai-sdr-sequences -> Preview autopilot results; live-data -> Preview a Live Data search (documented Beta or Coming soon) + - *Notes:* Preview before Start on a Live Data search is a hard rule, not a courtesy: Start spends the user's allowance and Preview does not. +- `plan.validate` — **absent** + - *Because:* not evidenced — no surface takes a plan. Authority, ordering, preconditions and headroom are checked step by step against the reads each step needs, by the agent, before anything runs. +- `contract.describe` — **absent** + - *Because:* Nothing here describes the contract — which version is in force, what was renamed from what, and what it binds an agent to is the core pack's own answer, not this API's. +- `capability.list` — **partial** + - *Missing:* The granted scope set is not returned by anything. Identity and the teams a credential may act in are readable; what it may actually do is discovered only by making a call and reading an insufficient_scope refusal back. For an unattended run that means the honest per-capability answer is unknown until something is attempted, and unknown is not permission. + - *Surface:* user-account -> Get current user, List team users + - *Notes:* Neither read needs a scope, so both work with any working credential. When a capability has to be known in advance, the key's scopes are visible in the product settings rather than through the API. +- `vocabulary.list` — **partial** + - *Missing:* Only the reply categories this account has declared. Enrolment statuses, meeting outcomes, step intents, exit reasons, content-policy rule classes and the properties a branch condition may be written over have no listing at all — checked against the endpoint index, there is no enumeration surface. For those kinds the answer is unknown, which the contract allows and which is not the same as an empty list. + - *Surface:* inbox -> List inbox categories +- `schema.describe` — **partial** + - *Missing:* Custom fields only, and only on people. No surface describes the standard fields of a record kind or says which of them may be written; that is prose on the record's own doc pages, read at call time, and it cannot be enumerated. + - *Surface:* custom-fields -> List all custom fields, Get a custom field +- `channel.describe` — **absent** + - *Because:* not evidenced — no documented surface states a channel's own rules: whether automation is sanctioned there, how its allowance works, how long a reply window stays open or what recording consent it expects. A sending account's configured limits are a different thing and belong to the sender operations; using them as an answer here would confuse one mailbox's ceiling with the channel's rules. +- `adapter.describe` — **partial** + - *Missing:* Nothing returns any of this. The request ceilings and the queued-versus-inline rule are documented in prose — reporting and stats endpoints are limited harder than the rest, and a long write answers with a background job to poll — but batch ceilings, page sizes and the scope and lifetime of an idempotency key are not stated, and none of it can be read per installation. + - *Surface:* the Rate limits guide page; background-jobs -> Get a background job +- `adapter.verify` — **absent** + - *Because:* not evidenced — nothing here tests fulfilment. This register is the claim, made from documentation rather than from a run, and it is the thing a verification would check rather than a substitute for one. +- `job.get` — **partial** + - *Missing:* Status, progress and the terminal timestamps are documented, but the result payload is opaque and its shape varies by job kind, so the per-item ledger the contract requires is not guaranteed to be there. Where one outcome per item is needed, reconcile against the entities themselves rather than trusting the job to carry it. + - *Surface:* background-jobs -> Get a background job, List background jobs + - *Notes:* A long write completes when the job reaches a terminal state, not when the call returns. Never blind-retry a bulk write that failed — the first attempt may have partly succeeded. +- `invocation.get` — **absent** + - *Because:* not evidenced — checked against the endpoint index, nothing looks a call up by the idempotency key it was sent with. After a lost response the only recovery is the operation's own check-first read, which is why every write in the contract names one. +- `term.resolve` — **absent** + - *Because:* Nothing here resolves a word onto a concept. The vocabularies this account declares can be listed, but mapping a colleague's shorthand or another system's label onto the right concept is the contract's own answer in the core pack. + +## Coverage by family + +A family whose *not assessed* column is not zero has not been fully answered for yet. Nothing should be read into those operations either way — an unanswered question is not a recorded absence. + +| Family | Operations | Direct | Composed | Partial | Absent | Not assessed | +|---|---|---|---|---|---|---| +| 01 Discovery, enrichment and verification · [mapping-01-discovery.md](mapping-01-discovery.md) | 12 | 0 | 0 | 4 | 8 | 0 | +| 02 Contacts, identity and hygiene · [mapping-02-contacts.md](mapping-02-contacts.md) | 23 | 6 | 1 | 3 | 13 | 0 | +| 03 Audience and lists · [mapping-03-audiences.md](mapping-03-audiences.md) | 16 | 5 | 1 | 1 | 9 | 0 | +| 04 Import · [mapping-04-import.md](mapping-04-import.md) | 5 | 0 | 1 | 2 | 2 | 0 | +| 05 Campaign, schedule, windows and limits · [mapping-05-campaigns.md](mapping-05-campaigns.md) | 26 | 7 | 2 | 11 | 6 | 0 | +| 06 Steps, content and content policy · [mapping-06-steps.md](mapping-06-steps.md) | 18 | 6 | 0 | 6 | 6 | 0 | +| 07 Messages · [mapping-07-messages.md](mapping-07-messages.md) | 5 | 0 | 0 | 4 | 1 | 0 | +| 08 Enrollment · [mapping-08-enrollment.md](mapping-08-enrollment.md) | 7 | 3 | 0 | 3 | 1 | 0 | +| 09 Conversations and activity · [mapping-09-conversations.md](mapping-09-conversations.md) | 9 | 2 | 0 | 2 | 5 | 0 | +| 10 Task queue and touches · [mapping-10-tasks.md](mapping-10-tasks.md) | 12 | 5 | 1 | 1 | 5 | 0 | +| 11 Meetings, qualification and handoff · [mapping-11-meetings.md](mapping-11-meetings.md) | 17 | 0 | 0 | 1 | 16 | 0 | +| 12 Signals and triggers · [mapping-12-signals.md](mapping-12-signals.md) | 10 | 0 | 0 | 5 | 5 | 0 | +| 13 Inbound · [mapping-13-inbound.md](mapping-13-inbound.md) | 11 | 0 | 0 | 0 | 11 | 0 | +| 14 Consent, suppression and privacy · [mapping-14-privacy.md](mapping-14-privacy.md) | 23 | 0 | 0 | 6 | 17 | 0 | +| 15 Sending capability and deliverability · [mapping-15-sending.md](mapping-15-sending.md) | 34 | 0 | 0 | 13 | 21 | 0 | +| 16 Social and messaging channels · [mapping-16-social.md](mapping-16-social.md) | 13 | 1 | 0 | 0 | 12 | 0 | +| 17 Oversight, review and safety · [mapping-17-oversight.md](mapping-17-oversight.md) | 32 | 0 | 0 | 7 | 25 | 0 | +| 18 The team: people, ownership, workload and targets · [mapping-18-team.md](mapping-18-team.md) | 15 | 2 | 0 | 4 | 9 | 0 | +| 19 Accounts and buying groups · [mapping-19-accounts.md](mapping-19-accounts.md) | 12 | 4 | 0 | 3 | 5 | 0 | +| 20 Measurement · [mapping-20-measurement.md](mapping-20-measurement.md) | 10 | 1 | 0 | 2 | 7 | 0 | +| 21 Introspection and runtime · [mapping-21-introspection.md](mapping-21-introspection.md) | 15 | 1 | 0 | 6 | 8 | 0 | diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-01-discovery.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-01-discovery.md new file mode 100644 index 0000000..1a67935 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-01-discovery.md @@ -0,0 +1,35 @@ + + +# Family 1 — Discovery, enrichment and verification · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*People and audience* · 12 operations, 12 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `candidate.search` | `read` | `auto` | `partial`
*documented Beta or Coming soon* | live-data -> Preview a Live Data search, with the departments, industries, job titles, locations and seniorities typeahead pages that build the filter | `contacts:write` | *missing:* Preview answers how many and shows a capped sample, not the population. The whole result set exists only after Start a Live Data search, and Start is not a read: it buys the people and creates them as contacts. So "show me everyone this filter finds, before I spend anything" cannot be answered here.
Beta, and say so as part of the plan rather than as a footnote at the end. Build the filter from the typeahead values instead of guessing accepted ones. Preview adds no prospects and consumes no credits, which is what makes it the safe half of this operation. The write scope on a read is what the page documents, not a mistake. | +| `candidate.get` | `read` | `auto` | `partial`
*documented Beta or Coming soon* | live-data -> Get a Live Data search, List Live Data searches | — | *missing:* The read is per search, not per person: it returns a search and what it found, and there is no address for one found person on their own. Once Start has run, the person is an ordinary contact and is read with Get a contact — so the discovery surface stops being the place to look at exactly the moment the person becomes ours.
Check List Live Data searches for an existing near-identical search before starting another one. A repeat spends again and returns a different world. | +| `candidate.promote` | `control` | `confirm_once` | `partial`
*documented Beta or Coming soon* | live-data -> Start a Live Data search | `contacts:write` | *missing:* There is no promote-these-ones surface. Start finds and buys in one act: it adds everyone the filter returns as prospects and consumes credits per resulting contact, so the selection has to be made in the filter and cannot be made from a reviewed result set. The per-item promotion ledger the contract requires has to be read back off the search rather than off the call.
Preview before Start, always — Start spends the user's allowance and the mistake is only visible once it is paid for. Show who came back in the preview and let the user approve the filter itself. Start can optionally drop the found people into a sequence or a list; treat that as enrolment and hold it to the enrolment gate rather than letting it ride along. | +| `company.search` | `read` | `auto` | `absent` | live-data -> Preview a Live Data search | — | *because:* not evidenced — the preview reports a companiesCount, but the search returns and creates people. No documented surface returns companies from the outside world as companies. The accounts endpoints search only the companies we already hold, which is a different question and must not be offered as an answer to this one. | +| `company.resolve` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface decides which company four spellings of a name refer to. Accounts can be filtered by what we already hold, which finds an exact-ish match and says nothing about the three spellings that did not match. | +| `contact.enrich` | `control` | `confirm_once` | `absent` | contact-enrichment -> enrich by email, enrich by profile URL, find email, find phone | — | *because:* Documented as available late August 2026 and not callable today. Say that, and name the date the documentation gives. Never substitute an unrelated endpoint. | +| `company.enrich` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — the enrichment surface is about people, and firmographics on a company are not among its documented pages. The whole enrichment group is in any case documented as available late August 2026 and is not callable today. | +| `employment.check` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — nothing documented answers whether a person has left the company we have them at. There is no job-change monitoring surface, and the AI insights page that might touch on it is documented as available late August 2026 and is not callable today. | +| `email_address.verify` | `read` | `auto` | `partial` | email-validations -> Estimate email validation, Schedule email validation; background-jobs -> Get a background job | `contacts:operate`, `other:read` | *missing:* Two things. It validates people we already hold, taken by contact id, so a raw address that is not a contact yet cannot be checked without creating one first. And it returns the channel's verdict only — the send, hold or never_send decision the contract asks for comes from a contactability policy this product does not hold, so that half is the agent's own judgement and must be reported as such.
Three calls in order: Estimate first, because it reports the eligible count and what it would cost against the team's quota; then Schedule, which reserves credits and returns a job; then poll the job to a terminal state and read the verdicts. Estimate is how the user approves a spend before it happens, which makes skipping it the expensive shortcut. | +| `phone_number.verify` | `read` | `auto` | `absent` | contact-enrichment -> find phone | — | *because:* not evidenced — the enrichment surface looks a number up; nothing documented checks that a number we already hold is reachable or reports whether it is a mobile, a desk line or a virtual one. Finding and verifying are different acts and the line type is the part that changes what may be sent. The enrichment group is in any case not callable until late August 2026. | +| `enrichment_policy.define` | `control` | `confirm_once`
*departs:* raised above the derived `auto`: it carries four decisions with no safe default — source order, the acceptance predicate that stops the chain, per-field granularity, and a budget ceiling per run and per period — and every later purchase is made under it. | `absent` | — | — | *because:* not evidenced — no documented surface stores a buying order, an acceptance predicate or a spend ceiling. Each metered call carries its own limits at call time, so nothing binds the next one, and there is no version or author to read back. | +| `enrichment_policy.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — there is no stored policy to read, since none can be defined. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-01-discovery.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-02-contacts.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-02-contacts.md new file mode 100644 index 0000000..c8370b4 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-02-contacts.md @@ -0,0 +1,46 @@ + + +# Family 2 — Contacts, identity and hygiene · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*People and audience* · 23 operations, 23 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `contact.search` † | `read` | `auto` | `direct` | contacts -> Filter contacts, List all contacts | `contacts:read` | Filtering by email is the identity check that belongs before any create. | +| `contact.get` † | `read` | `auto` | `direct` | contacts -> Get a contact | `contacts:read` | The read-back after every write in this family. Cheap, and the only proof the write took. | +| `contact.resolve` | `read` | `auto` | `partial` | contacts -> Filter contacts, Count filtered contacts | `contacts:read` | *missing:* Filtering answers one key set per call, so resolving a collection is one call per person, and what comes back is a match list rather than a verdict: nothing returns "same human, this confident, under this rule". Ambiguity between two candidate records is something the caller has to notice and decide, and nothing marks it.
Email is the key that behaves. Every other key is a filter over fields, which finds people who look similar rather than people who are the same. | +| `contact.create` † | `control` | `confirm_once`
*conditional:* auto for create-only over a single record; confirm_once for any collection and any policy that may update. | `direct` | contacts -> Import contacts | `contacts:write` | Bulk-oriented: a large import returns a background job, so the operation completes when the job reaches a terminal state, not when the call returns. Field mapping is decided in the core layer and applied here. | +| `contact.update` | `control` | `confirm_once`
*conditional:* auto for a single record; confirm_once for a collection. | `direct` | contacts -> Update a contact, Import contacts with an update policy | `contacts:write` | Which of the two applies depends on the dedupe policy the user chose, and that choice is the core layer's to make. A collection goes through the import path and comes back as a job. | +| `contact.delete` | `control` | `confirm_once`
*departs:* raised: it destroys working history other operations key on. | `direct` | contacts -> the delete endpoint on its doc page | `contacts:write` | Irreversible in this product as well as in the contract. | +| `contact.restore` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — the contacts group documents Delete a contact and Bulk delete contacts and nothing that brings one back. Treat a delete here as irreversible with no restore window, and say so before deleting rather than after. | +| `timeline.get` | `read` | `auto` | `composed` | contacts -> Get activities for a contact, Get inbox threads for a contact, Get sequences for a contact, Get a contact's statuses | `contacts:read` | *order:* contacts -> Get activities for a contact for what we did, then Get inbox threads for a contact for what came back, then Get sequences for a contact and Get a contact's statuses for where they stand right now.
Four reads and no single chronology: each comes back per source and merging them in time order is this adapter's work, not the API's. Anything that happened off-platform is in none of them, so a timeline assembled here is what the product saw, not what happened. | +| `provenance.set` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface records where a person's data came from or under what terms. A custom field could hold the text, and must not be reported as provenance: the contract's version carries the lawful basis the sending decision rests on, and a field with a source name typed into it proves nothing. | +| `job_change.record` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — nothing documented forks a record when somebody moves employer. Updating the company on the existing contact is the opposite of what the operation asks for: it destroys the history at the old employer, which is usually the reason we were talking to them. | +| `cooldown.set` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface holds a person until a date and then releases them. Suppression is permanent until lifted by hand, which is a different promise, and offering it as a cooldown means a person we meant to come back to in Q4 is never contacted again. | +| `contact.disqualify` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — the contact status surfaces are about sequence participation and delivery outcomes, not about whether somebody is a prospect at all. The blacklist rules are suppression, a different act with a different meaning: using one for the other tells the user we may never contact this person, when what they said was that this person is not a fit. | +| `contact.requalify` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — there is no qualification state to reverse, since none can be recorded. | +| `contact.normalize` | `control` | `confirm_once`
*departs:* raised above the derived `auto` as a bulk write: one call rewrites values across every record in scope under the account's declared rule set. | `absent` | — | — | *because:* not evidenced — nothing documented rewrites records into a house format under a declared rule set while keeping what was there before. Bulk updates through the import path can overwrite values, which is not the same operation: it keeps no prior value and reports no rule set, so nothing can be undone or explained afterwards. | +| `identity_policy.define` | `control` | `confirm_once`
*departs:* raised above the derived `auto`: it carries seven decisions, none with a safe default, and records already written under the old policy are not re-decided. | `partial` | contacts -> Import contacts | `contacts:write` | *missing:* The decision exists as an argument on each import — skip existing, which never overwrites, or update existing — and nowhere else. There is no stored policy, no version, nobody recorded as having set it, and the matching rules themselves are not configurable. Every import re-decides the question, and two imports can disagree with nothing to notice it.
Because the policy cannot live in the product, it has to be carried by whatever keeps the user's durable context, and re-confirmed at each import rather than assumed from last time. | +| `identity_policy.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — there is no stored identity policy to read back, only the choice made on each import, which is not recorded anywhere afterwards. | +| `duplicate.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface reports suspected duplicates. Filtering can confirm that two records share an address once you already suspect it; nothing proposes the clusters in the first place, which is the entire operation. | +| `duplicate.merge` | `control` | `confirm_each`
*departs:* raised above the derived `confirm_once`: each cluster is a separate irreversible judgement about a different human. | `absent` | — | — | *because:* not evidenced — no documented surface combines two contact records into one. Deleting the loser and updating the winner is not a merge: it destroys the history the contract requires the merge to carry across, and there is no restore. | +| `duplicate.link` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — nothing records that two records are the same human while both have to stay. | +| `duplicate.unlink` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — there is no link to undo, since none can be made. | +| `duplicate.reject` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface records a not-a-duplicate decision, so the same pair would be proposed again by anything that looks a second time. | +| `field.define` | `control` | `confirm_once` | `direct` | custom-fields -> Create a custom field, List all custom fields | `contacts:write` | List first. A second field with almost the same name is how a mapping starts putting the right value in the wrong place, and nothing downstream will notice. | +| `field.retire` | `control` | `confirm_once` | `partial` | custom-fields -> Delete a custom field | `contacts:write` | *missing:* Delete, not retire, and nothing reports what still references the field before it goes. The check the contract requires before repeating — is this still used by a mapping, a filter or a template — has to be done by hand, and the documentation does not say what happens to the values already stored. Treat the loss as total until somebody demonstrates otherwise. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-02-contacts.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-03-audiences.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-03-audiences.md new file mode 100644 index 0000000..207bade --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-03-audiences.md @@ -0,0 +1,39 @@ + + +# Family 3 — Audience and lists · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*People and audience* · 16 operations, 16 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `segment.define` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — filters are expressed per call and no documented surface saves one under a name. A contact list cannot stand in for a segment: it holds people, not a definition, it does not re-evaluate, and it cannot say who would match tomorrow. | +| `segment.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — there is no saved definition to show, since none can be saved. | +| `segment.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — there are no saved definitions to list. | +| `segment.delete` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — there is nothing to retire. | +| `segment.preview` | `read` | `auto` | `direct` | contacts -> Count filtered contacts, Filter contacts; live-data -> Preview a Live Data search | `contacts:read`, `contacts:write` | Two universes, two surfaces, and the cost difference the contract describes is real here: counting our own contacts is free, and the external preview adds no prospects and consumes no credits either. The external half is Beta; the internal half is not. Run whichever applies before anything that spends — this is the operation that makes the spend reviewable. | +| `segment.materialize` | `control` | `confirm_once` | `composed` | contacts -> Filter contacts; contact-lists -> List contact lists, Create a contact list, Add contacts to a contact list | `contacts:read`, `contacts:write` | *order:* contacts -> Filter contacts to evaluate the definition, then contact-lists -> Create a contact list or reuse one from List contact lists, then Add contacts to a contact list, then contacts -> Filter contacts by that list to reconcile what actually landed.
The freeze is genuine but is not recorded as one: nothing on the list says which definition or which as-of time produced it, so that has to be written down outside the product or the list becomes a set of people nobody can account for. Say before you start that there is no way to take people back off a list — see list_membership.remove — so a list built from the wrong filter is corrected by building another one. | +| `list.create` | `control` | `auto` | `direct` | contact-lists -> Create a contact list | `contacts:write` | Check List contact lists first — reuse beats proliferation. | +| `list.list` | `read` | `auto` | `direct` | contact-lists -> List contact lists | `contacts:read` | The first call before any list.create — reuse beats proliferation. | +| `list.get` | `read` | `auto` | `partial` | contact-lists -> Get a contact list, Get contact's lists; contacts -> Filter contacts | `contacts:read` | *missing:* What is on the list is readable; where it came from is not. Nothing records the definition, the import or the search behind a list, so the second half of the question has no answer here — and it must not be improvised from the list's name, which is the one place a wrong answer will look plausible. | +| `list_membership.add` | `control` | `auto` | `direct` | contact-lists -> Add contacts to a contact list, Move contacts to a contact list | `contacts:write` | Add and Move are different acts: Move takes people off wherever they were. Reconcile afterwards by filtering contacts by the list, because the count asked for and the count that landed differ often enough to matter. | +| `list_membership.remove` | `control` | `auto` | `absent` | contact-lists -> Move contacts to a contact list | — | *because:* not evidenced — the contact lists group documents adding and moving and nothing that takes a person off a list. Move relocates people to another list rather than removing them, so using it as a removal quietly files them somewhere else. This is the gap that makes a mis-built list expensive, and the honest response is to get the list right before it is written rather than to plan on trimming it. | +| `list.delete` | `control` | `confirm_once` | `direct` | contact-lists -> Delete a contact list | `contacts:write` | Check what still references it first — no campaign binding is reported back, and nothing after the fact will tell you what broke. | +| `audience.assess` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface judges whether a set of people is fit to work. Duplicates cannot be listed, contactability is not modelled, and address verification is a separate metered job over contacts rather than over a list. The assessment is therefore the agent's own and has to be reported as a judgement, not as something the product checked. | +| `audience.screen` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — nothing re-checks a list against the exclusion rules and takes the failures out. The blacklist rules can be read and a validation job can be run, but there is no removal from a list at all, so the second half of the operation has nowhere to land. | +| `contactability_policy.define` | `control` | `confirm_once`
*departs:* raised above the derived `auto`: it answers, per verdict and per flag, one of send, hold or never_send for every address the account will ever offer, and nothing in it has a default. | `absent` | — | — | *because:* not evidenced — the blacklist rules are individual exclusion entries for domains, addresses and exceptions, not a policy answering send, hold or never_send per verdict and per flag. Reporting them as one would leave every verdict the rules do not mention silently defaulting to send, which is exactly the failure the policy exists to prevent. | +| `contactability_policy.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — there is no policy to read, only the individual blacklist entries. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-03-audiences.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-04-import.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-04-import.md new file mode 100644 index 0000000..e1177e5 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-04-import.md @@ -0,0 +1,28 @@ + + +# Family 4 — Import · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*People and audience* · 5 operations, 5 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `source.inspect` | `read` | `auto` | `absent` | — | — | *because:* not evidenced as an API surface, and rightly so — the file is inspected locally, before any call, which is what the import ordering this skill already carried says: inspect the source locally, zero API calls. There is no upload-and-profile endpoint and there does not need to be. Do the inspection, then show the user what would land, then ask. | +| `import.apply` | `control` | `confirm_once` | `composed` | contacts -> Import contacts, Filter contacts; background-jobs -> Get a background job | `contacts:write`, `other:read` | *order:* contacts -> Import contacts, then background-jobs -> Get a background job polled to a terminal state, then contacts -> Filter contacts by the target list to reconcile created, updated, skipped and failed against what was asked for.
A large import returns a job reference, not a result: the operation completes when the job reaches a terminal state, never when the call returns. A job that ends failed gets its body read for the reason — never blind-retry a bulk write, because the first attempt may have partially succeeded. The approval gate over the file, the count, the mapping, the dedupe policy and the target list belongs before the first call. | +| `import.list` | `read` | `auto` | `partial` | background-jobs -> List background jobs | `other:read` | *missing:* There is no import history. Imports appear as background jobs among every other kind of job, and the documentation does not say the listing can be filtered to imports, so the question is answered by reading a general job list and recognising them. Anything older than that listing retains is simply gone. | +| `import.get` | `read` | `auto` | `partial` | background-jobs -> Get a background job | `other:read` | *missing:* A job is identified by its own id, not by an import record, and the documentation does not state that the result carries a per-row ledger tying each source row to the contact it created or matched. Keep that reconciliation yourself at import time — after the fact it may not be recoverable at all. | +| `import.revert` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — nothing undoes an import. Bulk deleting the contacts is not a revert: it destroys people the import updated rather than created, and it cannot put back a field the import overwrote. Say the import is not reversible before it runs, which is the only moment at which saying it helps anyone. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-04-import.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-05-campaigns.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-05-campaigns.md new file mode 100644 index 0000000..cd18e74 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-05-campaigns.md @@ -0,0 +1,49 @@ + + +# Family 5 — Campaign, schedule, windows and limits · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The programme* · 26 operations, 26 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `campaign.list` † | `read` | `auto` | `partial` | sequences -> List all sequences, Count sequences; sequence-folders -> List sequences in a folder | `sequences:read` | *missing:* State comes back; health does not. Nothing in the listing separates a campaign that is fine from one that is not progressing, degraded or blocked, so "what is running, and what is quietly broken" needs a second pass over stats and sender health — and that verdict is this adapter's judgement, not a field it read. | +| `campaign.get` † | `read` | `auto` | `direct` | sequences -> Get a sequence | `sequences:read` | The verification read after every mutation. | +| `campaign.create` | `control` | `auto` | `direct` | sequences -> Create a sequence, List all sequences | `sequences:write` | Creating never arms anything: the new sequence comes back in a new state and starting it is a separate call with a separate approval. List first — reuse is usually right, and a fourteenth near-identical campaign is how a mailbox ends up sending to the same person from three directions. | +| `campaign.clone` | `control` | `auto` | `composed` | sequences -> Save a sequence as a template, Create a sequence from a template; sequence-templates -> List all sequence templates | `sequences:write` | *order:* sequences -> Save a sequence as a template, then Create a sequence from a template. Check sequence-templates -> List all sequence templates first in case the template already exists.
The template route carries structure and content and not enrolments, history or results, which is what the contract asks of a clone. Read the new campaign back and confirm the schedule and sender bindings came with it before assuming they did. | +| `campaign.update` | `control` | `auto` | `partial` | sequences -> Update a sequence, Change sequence owner | `sequences:write` | *missing:* Owner moves through its own endpoint, so one conceptual update is two calls. Beyond that there is no declared successor and no personalisation tier on the sequence: a campaign that hands over to another one cannot say so here and has to be tracked outside the product.
The update is last-write-wins — read the campaign first, or a field nobody meant to touch is reverted by a call that only meant to change the name. The owner endpoint is separate and may carry its own scope; take it from its page. | +| `reply_policy.set` | `control` | `confirm_once`
*departs:* raised above the derived auto: turning "stop on reply" off is how a campaign keeps writing to somebody who already answered, which is simultaneously the rudest and the most reputationally damaging thing an outbound programme can do. The operation is safe to repeat; the confirmation is about the content of the decision, not the mechanics of the call. | `partial` | sequences -> Update a sequence | `sequences:write` | *missing:* One switch, not a decision per event class: a reply either finishes the person or sending continues, and that is the whole vocabulary. There is no per-event-class routing and no attribution window, so "a reply within thirty days still counts as this campaign's" cannot be expressed at all.
Continuing to send after a reply is the setting that keeps writing to somebody who already answered. The contract raises this to confirm_once for exactly that reason, and learning it is one field on an update endpoint changes nothing about the confirmation. | +| `schedule.set` | `control` | `confirm_once`
*departs:* raised above the derived auto, because a schedule change silently rewrites every future date in the campaign. | `partial` | schedules -> Create a schedule, Update a schedule, Set default schedule; sequences -> Update a sequence to attach it | `sequences:write` | *missing:* Windows per day and the timezone policy are there, including sending in the prospect's own timezone rather than the schedule's. A delay basis and an out-of-window behaviour are not: nothing states whether a touch falling outside a window defers to the next open one or is skipped, so the defer-or-skip decision the contract makes the user take has no setting to carry it. Holidays are all-or-nothing per schedule.
Two calls: create or update the schedule, then attach it through the sequence update. A schedule is a shared object, so changing one silently rewrites every future date on every campaign pointing at it — which is the damage the contract's confirm_once is guarding against. Check who else uses it before editing rather than after. | +| `pacing.set` | `control` | `auto` | `partial` | sequences -> Update a sequence | `sequences:write` | *missing:* People admitted per day, messages per day and a minimum gap between sends all exist, and so does a same-domain cap the contract does not ask for. Jitter and the cold-start ramp do not: a new campaign runs at its full configured rate from day one unless somebody raises the numbers by hand over several days, and nothing records that they intended to.
These are per-campaign, which is the point of the operation — slowing this campaign without slowing everything else on the same mailbox. Ceilings that belong to the sending capability itself are set elsewhere and are not reachable from here. | +| `sender_binding.set` | `act`
*conditional:* `control` for new entrants only; `act` where it rebinds live participations, because the prospect sees a new From address mid-thread; resolved by the preview. | `confirm_once` | `partial` | sequence-email-accounts -> Assign email account to sequence, Set sequence email accounts, Remove email account from sequence; sequence-linkedin-accounts -> Assign a LinkedIn account to a sequence | `sequences:operate` | *missing:* Binding is per campaign only — named participations cannot be bound. And the documentation does not say what happens to people already mid-campaign when the binding changes, so the preview the contract requires, the one telling a user which live threads are about to change From address, cannot be produced from this API.
Because the live-participation behaviour is undocumented, treat a rebinding on a running campaign as an act with an unknown blast radius: pause, rebind, read back, resume. Confirm the sender is healthy before binding it to anything. | +| `campaign.validate` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface answers whether a campaign is safe to turn on. The pieces a validation would read do exist separately, as steps, sender assignments, the schedule and the enrolled count, so the check is assembled by the agent out of several reads and reported as its own work. Never report it as something the product verified: an unpublished template or a schedule that never opens will not announce itself. | +| `campaign.test` | `act` | `confirm_each` | `partial` | email-templates -> Send a test email, Render an email template | `sequences:operate` | *missing:* It tests a template, not the campaign. There is no surface that sends step one exactly as a real contact would receive it, the documentation places no restriction on the recipient address, and nothing checks that the unsubscribe mechanism in the message actually works. The contract's test — receive it yourself, click the unsubscribe link, and only to an address the workspace can demonstrate it owns — is only partly reachable.
A test send is still a send and still metered, so the contract's confirm_each stands. Say which parts were tested and which were not, rather than reporting a green test. | +| `campaign.activate` | `act`
*conditional:* `act`, with magnitude equal to the enrolled population; `control` only where the campaign holds no enrolments, and even then it arms the campaign so the next enrolment sends immediately. | `confirm_once` | `direct` | sequences -> Start a sequence | `sequences:operate` | Verify the status flipped by re-reading. The contract's approval class is unchanged by the mapping: it is confirm_once with a mandatory preview naming the population, and knowing which endpoint performs it changes nothing about that. | +| `campaign.pause` † | `control` | `auto` | `direct` | sequences -> Pause a sequence | `sequences:operate` | Cheap and reversible — the protective move, and the right first response to a misfire. | +| `campaign.resume` | `act` | `confirm_once` | `direct` | sequences -> Start a sequence, Bulk start sequences | `sequences:operate` | The same endpoint as activation, so it will not refuse a campaign that was never paused the way the contract says a resume should. Read the state first and decide which operation you are actually performing: the two carry different approvals, and only one of them is a first activation. | +| `campaign.freeze` | `control` | `auto` | `partial` | sequences -> Pause a sequence; or holiday-calendars -> Create a holiday calendar with schedules -> Link a holiday calendar to a schedule | `sequences:operate`, `sequences:write` | *missing:* Neither route is a freeze. A pause carries no expiry and never resumes itself, so the thing that makes a freeze safe — that somebody forgetting about it is not a failure — is gone. A dated holiday calendar does expire by itself, but it suppresses at the schedule, and a schedule may be shared by campaigns nobody meant to stop.
Say which route was taken and what it costs. A pause leaves the resume as a human's job, so it belongs in whatever carries work across sessions rather than in someone's memory. A linked calendar needs a check of which other campaigns point at that schedule, before linking. | +| `campaign.unfreeze` | `act` | `confirm_once` | `partial` | sequences -> Start a sequence; or schedules -> Unlink a holiday calendar from a schedule | `sequences:operate`, `sequences:write` | *missing:* No preview of what letting it go early releases. The contract wants the count of messages that go out the moment the suppression lifts, and nothing here produces one, so the user is approving a release whose size nobody has been told.
Work the release out from the enrolled counts and the pacing before asking for the confirmation, and say out loud that the number is an estimate rather than a reading. | +| `campaign.archive` | `control` | `confirm_once` | `direct` | sequences -> Archive a sequence, Bulk archive sequences | `sequences:operate` | Refuses with a conflict when the campaign is already archived or in an incompatible state, and the documentation does not enumerate those states — so read the campaign back rather than inferring what the conflict meant. Stop live enrolments with a reason first, as the contract requires. | +| `campaign.unarchive` | `control` | `auto` | `direct` | sequences -> Unarchive a sequence, Bulk unarchive sequences | `sequences:operate` | Bringing it back into the working set does not start it sending. That is a separate call and a separate decision, and the contract keeps them apart for a reason. | +| `schedule.resolve` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — nothing documented returns a resolved calendar. The schedule can be read and so can a linked holiday calendar, but the day-by-day answer for a campaign or for one person, showing what a weekend, a holiday or a closed window moved, has to be computed and cannot be checked against anything. | +| `send_window.resolve` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface answers when one person may be contacted on one channel. Some inputs are readable, being the schedule's windows, its timezone policy and its linked holiday calendars, but legal quiet hours in the recipient's local time and operator blackouts are not modelled at all, so the parts that carry legal weight are the ones missing. | +| `blackout.define` | `control` | `confirm_once`
*departs:* raised above the derived auto: a blackout suppresses sending across every campaign its region and date range cover, and defer-or-skip decides whether the touches it stops come back at all. Lifting it again is itself a release of suppressed sending, so the range is agreed once, when it is drawn. | `partial` | holiday-calendars -> Create a holiday calendar, Update a holiday calendar; schedules -> Link a holiday calendar to a schedule | `sequences:write` | *missing:* Named date ranges exist, with an annual-repeat flag. Defer-or-skip does not: nothing states whether the touches a range stops come back afterwards or are lost, which is half of what the contract asks the user to decide. Nor does the create call take the region the range applies to, so whose region applies cannot be stated at the moment the range is drawn.
A calendar suppresses nothing until it is linked to a schedule, and it then applies to every campaign on that schedule. Linking is the act; creating is not, and reporting the create as the blackout is how a holiday range ends up suppressing nothing. | +| `blackout.list` | `read` | `auto` | `composed` | holiday-calendars -> List holiday calendars; schedules -> List linked holiday calendars | `sequences:read` | *order:* holiday-calendars -> List holiday calendars for everything defined, then, for each schedule a campaign in scope actually uses, schedules -> List linked holiday calendars. An unlinked calendar suppresses nothing and must not be reported as suppression in force.
This answers which ranges are in force and until when for the campaigns you name, not account-wide in one call. State the scope you checked, because the difference between "no blackouts" and "no blackouts on the two campaigns I looked at" is the whole answer. | +| `blackout.remove` | `act`
*conditional:* `act` where the removal exposes a window open now on a live campaign; `control` otherwise — resolved by the preview. | `confirm_once` | `partial` | schedules -> Unlink a holiday calendar from a schedule; holiday-calendars -> Delete a holiday calendar | `sequences:write` | *missing:* The lift itself works. The preview does not: nothing says whether removing a range opens a window that is open right now on a live campaign, or how many messages go out as a result — and that preview is what the contract uses to decide whether this is an act at all. Here it has to be reasoned out instead of read.
Unlink lifts the suppression for one schedule; delete removes the calendar from every schedule that used it. They are different-sized acts, and the user should be told which one is being proposed before they agree to it. | +| `frequency_policy.define` | `control` | `confirm_once`
*departs:* raised above the derived auto: the cap declared here is evaluated for every campaign, every channel and every sender at once, and which message classes count has no default — a policy written loosely either silences the answers people asked for or lets one person hear from us three times in a day. | `absent` | — | — | *because:* not evidenced — no documented surface caps how often one person, account or domain hears from us across campaigns. The per-campaign same-domain limit is the nearest thing and is a different promise: one campaign's contacts-per-domain-per-day, not a cross-campaign, cross-channel cap. Offering it as one would let three campaigns touch the same person in a day while the limit reports as respected. | +| `frequency_policy.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — there is no cap to read, since none can be defined, and the per-campaign same-domain limit answers a different question. | +| `capacity.estimate` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — nothing projects whether a plan can physically run. Sending capacity, pacing and existing load are each readable somewhere, but no surface puts them against a planned volume over a stated horizon. Any answer is the agent's own arithmetic over several reads and has to be reported that way, with the reads it rests on named. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-05-campaigns.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-06-steps.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-06-steps.md new file mode 100644 index 0000000..267ca69 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-06-steps.md @@ -0,0 +1,41 @@ + + +# Family 6 — Steps, content and content policy · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The programme* · 18 operations, 18 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `step.list` | `read` | `auto` | `direct` | sequence-steps -> List all sequence steps, Get a sequence step | `sequences:read` | The step carries its own execution mode, which is what tells you which steps owe a human rather than going out on their own. | +| `step.add` | `act`
*conditional:* `control` on a campaign that is not live; `act` on a live one, with magnitude equal to the enrolments at or past the insertion point. | `confirm_once`
*conditional:* auto while not live; confirm_once while live, with a mandatory statement of what happens to in-flight enrolments. | `partial` | sequence-steps -> Create a sequence step, Bulk create sequence steps | `sequences:write` | *missing:* Position is not settable. The create body has no position, order or index field, so a step lands after the ones already made and no reorder endpoint exists to correct it. Content is inline on the step rather than bound to a template version, so a step cannot reference published copy. A branch is expressed as a condition step plus a parent reference and a positive-or-negative flag, and the evaluation window and early-satisfaction behaviour the contract asks for have no field at all.
Channel and kind arrive together as one discriminated type — email, LinkedIn with its own action subtype, call, SMS, WhatsApp, task, condition — and the delay is a single minutes value, so the contract's unit and basis have to be reduced to minutes before the call. Complex step work, notably variants on a live sequence and LinkedIn steps, is often better handed to the product's own editor than approximated here. Say so and hand off rather than guessing. | +| `step.update` | `act`
*conditional:* `control` while not live, `act` while live. | `confirm_once`
*conditional:* auto while not live; confirm_once while live with the in-flight statement. | `partial` | sequence-steps -> Update a sequence step | `sequences:write` | *missing:* The step type is a discriminator and cannot be changed, so moving a step to another channel means delete and re-add, which loses the step's variants with it. Position is out of reach here for the same reason it is in step.add.
A full replacement rather than a patch — read the step first and resend every field you are not changing, or the delay and the copy you left out are gone. Nothing in the documentation restricts the call while the sequence is live, so the in-flight statement the contract requires is the agent's obligation and not the API's. | +| `step.remove` | `act`
*conditional:* `control` while not live, `act` while live. | `confirm_once` | `direct` | sequence-steps -> Delete a sequence step, Bulk delete sequence steps | `sequences:write` | Takes the step's variants and their history with it. Re-read the step list afterwards — an absent step is a completed removal, not a failure. | +| `step.reorder` | `act`
*conditional:* `control` while not live, `act` while live. | `confirm_once` | `absent` | — | — | *because:* Neither Create a sequence step nor Update a sequence step exposes a position, order or index field, and no reorder endpoint is documented. Steps sit in the order they were created. Delete and re-add is not a substitute — it destroys variants and their measurement history, which is the exact loss this operation exists to prevent. | +| `variant.add` | `act`
*conditional:* `control` while not live, `act` while live. | `confirm_once`
*conditional:* auto while not live, confirm_once while live. | `direct` | sequence-steps -> Create a step variant, Bulk create step variants | `sequences:write`, `sequences:operate` | A variant carries a subject, a message, an enabled flag and up to three attachment identifiers. There is no split share, so report the split as unsettable rather than assuming one — which is what the operation itself already requires. Enable step variants and Disable step variants govern whether the step uses variants at all and need the operate scope rather than write. | +| `variant.update` | `act`
*conditional:* `control` while not live, `act` while live. | `confirm_once`
*conditional:* auto while not live, confirm_once while live. | `direct` | sequence-steps -> Update a step variant | `sequences:write` | The enabled flag is here, which makes disabling the right move for a variant under test. | +| `variant.remove` | `control` | `confirm_once` | `direct` | sequence-steps -> Delete a step variant, Bulk delete step variants | `sequences:write` | Destroys the variant's measurement history. Disable it instead while a test is running. | +| `variant.list` | `read` | `auto` | `direct` | sequence-steps -> List step variants | `sequences:read` | Returns each variant's enabled flag. The share each runs at is not part of the model here, so report it as unavailable rather than inferring an even split. | +| `template.create` | `control` | `auto` | `partial` | email-templates -> Create an email template | `sequences:write` | *missing:* No draft state. A template exists in one state and is usable the moment it is created, so the contract's guarantee that unreviewed copy cannot be sent is not enforced by the product and has to be carried by the approval gate instead.
Folders organise templates — read List email template folders and List email templates first, because reuse beats proliferation here as much as it does for lists. | +| `template.update` | `control` | `auto` | `partial` | email-templates -> Update an email template | `sequences:write` | *missing:* No versioning. The update replaces the content in place and no earlier version is kept, so the rule that a change always produces a new draft and never mutates published copy cannot be honoured. Keep the previous text yourself if anyone may need it back.
Steps hold their copy inline, so changing a template does not change what a live campaign sends. Those are two separate edits, and which one the user actually asked for is worth settling before either. | +| `template.get` | `read` | `auto` | `partial` | email-templates -> Get an email template, Get template variables | `sequences:read` | *missing:* No version list, no published or retired state, and no list of what binds it — steps carry their own copy, so there is nothing to report as a dependent.
Get template variables is the read that says which merge fields the copy needs, before anyone renders it against a real person. | +| `template.list` | `read` | `auto` | `partial` | email-templates -> List email templates, List email template folders | `sequences:read` | *missing:* The second half of the question. Folders say where a template sits; nothing says whether its copy is draft, published or retired, because those states do not exist here. | +| `template.publish` | `control` | `confirm_once` | `absent` | — | — | *because:* No version lifecycle is documented for templates. There is no draft, no published version and no publish endpoint — a template is usable from the moment it exists. Never present creating or updating one as publishing it. | +| `template.retire` | `control` | `confirm_once` | `absent` | — | — | *because:* The same absent lifecycle. Delete an email template destroys the template rather than retiring a version, and it cannot answer the question this operation is really asking — which live campaigns still depend on this copy — so it must not be substituted. | +| `content_policy.define` | `control` | `confirm_once`
*departs:* raised above the derived auto: a rule written here blocks or permits every send in its scope, so relaxing one — or scoping it to everything by accident — changes what may leave without any other operation being called. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. The blacklist rules govern which addresses and domains may be contacted, not what the copy may say, and substituting them answers a different question entirely. | +| `content_policy.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `content_policy.check` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing takes a rendered message and returns the rules it breaks, so copy has to be checked against the account's rules outside the product before it is approved. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-06-steps.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-07-messages.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-07-messages.md new file mode 100644 index 0000000..f1b0519 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-07-messages.md @@ -0,0 +1,28 @@ + + +# Family 7 — Messages · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The programme* · 5 operations, 5 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `message.draft` † | `read` | `auto` | `partial` | email-templates -> Render an email template, Get template variables | `sequences:operate` | *missing:* The render returns a subject and a body and nothing else. The footer, the identification block and the unsubscribe mechanism the contract requires the draft to show are absent from the response, so what is previewed cannot be proved to be the whole of what would leave. Merge values that are missing or wrong are reported, which is the part it does keep.
Renders against one contact identifier, optionally in the context of a campaign and a sending identity so their variables resolve too. Two other renders exist and both carry a beta mark — Get sequence preview for a contact under sequence-contacts, and Generate an AI draft reply under inbox — so say beta out loud before planning a route through either. | +| `message.send` † | `act` | `confirm_each` | `partial` | inbox -> Send a reply within a thread | `inbox:operate` | *missing:* Inside a thread, only a reply. The contract's message.send is one message to one person on one channel, including the first one: from reply-cli 0.17.0 the direct sends (an email, a LinkedIn message, InMail or voice message) send the first one outside any campaign, where the account's Reply has the route; inside a campaign a first message is the campaign's step, with no surface here.
The reply goes out on the thread's own channel. If that channel's account is disconnected the send fails — tell the user to reconnect, and never switch channel silently. Where the runtime carrying the work passes the reserved `provider` key inside the operation's arguments, `args.provider`, and the send is a direct send by email, that object is `{"schedule_id": ""}` and nothing else: the `id` of a schedule from `reply schedule list`, written as a string of its digits. It goes as `--schedule-id` (from reply-cli 0.17.0). Another shape or another key is refused before anything is sent, with a message naming the shape; write the object in that shape and ask again. Reply refuses a schedule on every LinkedIn direct send in this version (scheduleId is not supported for LinkedIn sends in this version, a 400 on each LinkedIn route), so a schedule on a LinkedIn message is refused before any call. A message composed as a template goes by the same command, in Reply's own syntax, and Reply fills it in for the contact: a send Reply makes within the call is filled in before anything goes and refused with nothing sent where Reply cannot fill it; one held for a later moment or a schedule, or queued behind the account's other sends, is filled in when it goes and fails then. The codes, the names Reply lists, the LinkedIn sending account's two names and the formats that are never filled in are under reply-api, Direct sends, Templates. | +| `message.schedule` | `act` | `confirm_each` | `partial` | direct-outreach -> the direct sends (an email, a LinkedIn message, InMail or voice message, and Send a LinkedIn connection request to a contact), each with its send-after moment | — | *missing:* Only a send outside any campaign, and only where the account's Reply has the route. From reply-cli 0.17.0 the direct sends take `--send-after`, a moment with its offset, which the CLI sends as UTC, and Reply holds the send until then; a moment already past is sent at once. A Reply that does not keep a direct send for later answers a bare 404, and nothing is scheduled. The contract's read before repeating — the pending sends for this person on this thread — has no list surface here: a harness that keeps the reference reads and cancels by it.
From reply-cli 0.17.0, send with `--idempotency-key`, which goes as the Idempotency-Key header: the same request repeated under the same key answers the send Reply took and sends nothing twice, so a lost answer is repeated under the key rather than read around. Reply honours the key only where it has the direct-send routes, so read `reply direct-send get` of a reference first (from reply-cli 0.17.0): its own `direct_send.not_found` or `direct_send.not_owned` says the routes are there, a bare 404 says they are not, and a key sent there protects nothing. The answer names the send's `reference` and its `state`: `sent` means it went, `failed` and `cancelled` are final, and any other state means Reply holds it and it has not gone yet. Keep the reference; it is the only handle on the send, and after a lost answer `reply direct-send get` of it is read before any repeat. Reply keeps a key for a day, so a repeat goes under it only within 23 hours of the first try; past that, nothing is sent again. From reply-cli 0.17.0 an email direct send also takes `--schedule-id`, a schedule from `reply schedule list`; Reply refuses it on every LinkedIn route. Reply then holds the send until the schedule's first opening at or after the moment, or after now where none is given, and the answer names no moment: Reply estimates one only where the schedule opens within 30 days, and reply-cli does not pass the estimate. A manual-email task dated for the 14th is still queued work for a person, not a queued send. | +| `scheduled_message.list` | `read` | `auto` | `absent` | — | — | *because:* No surface lists the pending sends — not by person, campaign or sender. From reply-cli 0.17.0, `reply direct-send get ` reads one send by its reference — its state, its moment, when it went and why it failed — which answers for a send already known and never for "what is queued". A harness that keeps the reference reads and cancels by it. | +| `scheduled_message.cancel` | `control` | `auto` | `partial` | direct-outreach -> the direct send's cancel, by its reference | — | *missing:* By reference only, and only where the account's Reply has the route. From reply-cli 0.17.0, `reply direct-send cancel ` cancels one direct send still held for its moment. Nothing lists the pending sends, so a harness that keeps the reference reads and cancels by it; a send whose reference was not kept cannot be found to cancel. What is pending in a live participation is still the next touch of a campaign, and stopping that is enrollment.pause or enrollment.stop rather than this.
A cancel of a send already cancelled is a success, and one whose answer was lost is safe to run again. A send that has gone answers `direct_send.already_sent` and one that failed `direct_send.already_failed`: report it as gone or failed, never as cancelled. A bare 404 means the account's Reply does not have the route yet. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-07-messages.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-08-enrollment.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-08-enrollment.md new file mode 100644 index 0000000..816c6df --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-08-enrollment.md @@ -0,0 +1,30 @@ + + +# Family 8 — Enrollment · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The programme* · 7 operations, 7 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `campaign.enroll` † | `act`
*conditional:* bookkeeping while the campaign is not live, `act` the moment it is; resolved by the preview, never assumed. | `confirm_once`
*conditional:* confirm_once before go-live; confirm_once with a mandatory preview once live. One call over a set is one decision, and the preview is the approval artefact — it names the population, it does not count it. | `direct` | sequence-contacts -> Bulk add contacts to sequence | `sequences:operate`, `contacts:read` | Returns per-contact results. Reconcile every one — added, already in sequence, not found, forbidden, limit exceeded. Never summarise a partial result as success. | +| `enrollment.list` † | `read` | `auto` | `direct` | sequence-contacts -> List contacts in sequence, List contacts in sequence with extended state; contacts -> Get sequences for a contact | `sequences:read`, `contacts:read` | Both ends of the same read are covered — the campaign's people, and one person's campaigns. Count contacts in sequence is documented as coming soon, so count by paging the list rather than planning around it. | +| `enrollment.get` | `read` | `auto` | `direct` | sequence-contacts -> Get a contact in a sequence, List contacts in sequence with extended state | `sequences:read` | The extended-state listing is the one that carries progress detail; the single read is the cheaper check-first before a hold, a resume or a stop. Which of the fields this operation names are actually present comes from those two pages at call time, not from here. | +| `enrollment.pause` † | `control` | `auto` | `partial` | sequence-contacts -> Set contacts' status in this sequence | `sequences:operate` | *missing:* No reason is accepted and there is no dated automatic resume. The hold is a bare status, so why someone was held and when they should carry on again survive only wherever the agent chooses to write them down.
At most one hundred people per call, and only a participation that is currently active can be held. The response returns failures keyed by person and an empty object when every one succeeded — reconcile per person rather than reading that empty object as a count. | +| `enrollment.resume` | `act`
*conditional:* `act` when the campaign is live; `control` when it is not. | `confirm_once`
*conditional:* confirm_once with a mandatory preview naming who resumes while the campaign is live; auto while it is not. | `partial` | sequence-contacts -> Set contacts' status in this sequence | `sequences:operate` | *missing:* Setting a participation back to active is accepted from any current state, so the refusal the contract requires — resume only what is actually held — is not enforced by the API. The check-first read has to perform it, or a finished participation is quietly restarted and someone is written to again.
On a live campaign this sends. The preview naming who resumes is the approval artefact and knowing which endpoint performs the call softens nothing about that. | +| `enrollment.stop` † | `control` | `confirm_once` | `partial` | sequence-contacts -> Remove contact from sequence, Bulk remove contacts from sequence | `sequences:operate` | *missing:* The mandatory reason. The body carries identifiers and nothing else, so neither why someone was taken out nor that a different person was the cause can be recorded — and naming that other person is part of the operation, not a nicety. Record the reason wherever the run itself is recorded.
The bulk response counts requested, removed, not found and not in sequence, and lists the identifiers actually removed. An already-absent participation reads as a completed stop. | +| `disposition.set` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Marking someone replied or bounced records what happened to a message, and an inbox category records what a reply meant; neither is the business outcome of the participation, and pressing one into service as a stand-in corrupts the number people are measured on. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-08-enrollment.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-09-conversations.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-09-conversations.md new file mode 100644 index 0000000..dedca35 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-09-conversations.md @@ -0,0 +1,32 @@ + + +# Family 9 — Conversations and activity · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The conversation, the queue and the day* · 9 operations, 9 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `conversation.list` † | `read` | `auto` | `direct` | inbox -> List inbox categories, List and filter inbox threads | `inbox:read` | Categories carry unread counts, so reading them first gives the shape of the work. | +| `conversation.get` † | `read` | `auto` | `direct` | inbox -> Get inbox thread, List messages in an inbox thread | `inbox:read` | Two reads — the thread, then its messages in order. Note the thread's channel while you are there, because a reply has to go out on the same one. | +| `conversation.classify` † | `control` | `auto` | `partial` | inbox -> Assign or clear a thread's category, Assign threads to a category | `inbox:operate` | *missing:* The meaning is recorded, its provenance is not. No field carries who decided it, which message they decided it from, or how sure they were, so a category set by a model and one set by a person are indistinguishable afterwards.
The vocabulary is the account's own inbox categories — read List inbox categories first and map onto what exists rather than inventing a label. Re-read the thread to confirm it took. | +| `conversation.assign` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Assign threads to a category and Assign or clear a thread's category move a thread between categories, not between people, and the resemblance in the names is exactly the trap. Changing who owns the person is a different act with different consequences and is not a substitute. | +| `conversation.snooze` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing takes a thread out of the queue and brings it back on a date. | +| `conversation.close` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Mark threads as read records a read state, not a worked one, and deleting a thread destroys it. Neither says the thread was dealt with, which is the whole of what closing one means. | +| `conversation.reopen` | `control` | `auto` | `absent` | — | — | *because:* Nothing closes a thread here, so nothing reopens one. Mark threads as unread is the nearest surface and it says something else. | +| `referral.record` | `control` | `confirm_once`
*departs:* raised: it creates a person we will contact on the strength of a stranger's sentence. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. The pieces exist separately, since the named person can be created and the referrer can be taken out of the campaign, but nothing records that the one came from the other — and that link is the only fact that justifies contacting a stranger, so performing the two calls without it is not the operation. | +| `activity.log` | `control` | `auto` | `partial` | contacts -> Add a note to a contact | `contacts:operate` | *missing:* Only the note. A free-text note is one of the things this operation records; an email sent from a personal client, a conversation in a corridor, or a message on a channel we do not send from cannot be logged as an activity with its channel, direction and time, so the record stays an incomplete account of what happened to this person.
Get activities for a contact is the read that shows what the product recorded itself, and a note is not guaranteed to appear in it. Check before telling the user the record is whole. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-09-conversations.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-10-tasks.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-10-tasks.md new file mode 100644 index 0000000..db5b254 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-10-tasks.md @@ -0,0 +1,35 @@ + + +# Family 10 — Task queue and touches · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The conversation, the queue and the day* · 12 operations, 12 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `task.list` † | `read` | `auto` | `direct` | tasks -> List all tasks, Filter tasks | `tasks:read` | Filter tasks is the one that answers what is owed today, by due window and by owner. | +| `task.get` | `read` | `auto` | `direct` | tasks -> Get a task | `tasks:read` | A task carries the message it is asking for as a subject and a body, so this read gives a human what they need to do the work rather than a pointer to it. | +| `task.create` | `control` | `auto` | `composed` | tasks -> Create a task, Reassign a task | `tasks:write` | *order:* Create a task, then Reassign a task when the queue belongs to somebody else — the create body has no assignee field, so the task lands with the calling user. Work for yourself needs only the first call.
Type, start time, due time and a body are required, the type decides what the task is for, and LinkedIn work carries its own subtype. Batch reassign tasks handles a set in one call. | +| `task.complete` † | `control` | `auto` | `direct` | tasks -> Complete a task, Batch complete tasks | `tasks:operate` | Marks the work done and sends nothing, which is exactly what this operation means. Execute and complete a task is a separate endpoint that does send the message the task holds — never reach for it to satisfy this operation. If the user wants the send, that is message.send with the approval message.send requires. | +| `task.skip` | `control` | `auto` | `absent` | — | — | *because:* The documented task states are new, finished, cancelled, archived and detached from a campaign, and none of them is skipped. The update endpoint cannot set a state at all, so declining a task while recording that it was declined has no surface. Completing it instead would put a lie in the record. | +| `task.reschedule` | `control` | `auto` | `direct` | tasks -> Update a task | `tasks:write` | Start and due times are both updatable, but the call replaces the whole task — read it first and resend the type, the body and the person, or they are lost. Only a task still in its new state can be updated, so finished work cannot be pushed to tomorrow. | +| `task.cancel` | `control` | `auto` | `partial` | tasks -> Delete a task, Bulk delete tasks | `tasks:write` | *missing:* Dropping the work is possible, recording that it was deliberately dropped is not. Deletion destroys the task, and the cancelled state the documentation describes cannot be set through the update endpoint, so afterwards nothing distinguishes work called off from work that was never there.
Say the deletion is irreversible before doing it. The contract treats this operation as compensatable and on this surface it is not, which is a difference the user has to hear first rather than discover. | +| `task.reassign` | `control` | `auto` | `direct` | tasks -> Reassign a task, Batch reassign tasks | `tasks:write` | The batch form is the one for handing over a whole queue. Reconcile per task rather than assuming the entire set moved. | +| `call.place` | `act` | `confirm_each` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Execute and complete a task, the only endpoint that performs a task's action, supports manual email and SMS and rejects every other type, so a call task cannot be dialled through the API. Calls are placed in the product, and the user needs telling that plainly. | +| `call.log` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — call activity is readable through reporting, under Get calls reporting overview and List call activity, and nothing writes one. A call that happened away from the product cannot be recorded here. | +| `call_recording.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this, and none for the agreement that permitted the recording either. | +| `call_recording.discard` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. A recording that has to be destroyed must be dealt with in the product, and that has to be said out loud rather than left for the user to assume an agent handled it. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-10-tasks.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-11-meetings.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-11-meetings.md new file mode 100644 index 0000000..3cc3a7d --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-11-meetings.md @@ -0,0 +1,40 @@ + + +# Family 11 — Meetings, qualification and handoff · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The conversation, the queue and the day* · 17 operations, 17 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `meeting.propose` | `act` | `confirm_each`
*departs:* raised: it puts words and specific times in front of a named person. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing offers times and nothing hands over a way to pick one. Toggle thread meeting-intent marks that a thread is about a meeting and proposes nothing, so it must not be read as a booking surface. | +| `meeting.book` | `act`
*conditional:* `act` when the booking issues the invitation; `control` when it records a meeting invited elsewhere — resolved by the preview. | `confirm_each`
*conditional:* confirm_each when it acts, auto when the preview resolves it to `control`.
*departs:* confirm_each when the booking issues the invitation, because each invitation reaches one person's calendar and is its own decision; auto when the preview resolves it to recording a meeting invited elsewhere. Act × compensatable derives confirm_once, so the acting side sits deliberately above the table. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Meetings appear in reporting as facts that already happened; no endpoint creates one, issues an invitation, or records a meeting that was invited elsewhere. | +| `meeting.confirm` | `act` | `confirm_each`
*departs:* raised: it reaches named people. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is nothing to read a meeting's attendee responses from and nothing that chases the people who have not answered. | +| `meeting.reschedule` | `act` | `confirm_each`
*departs:* raised: the attendee is told. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. With no booking surface there is no meeting here to move. | +| `meeting.cancel` | `act` | `confirm_each`
*departs:* raised: the attendee is told. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Tell the user to cancel it in the calendar rather than leaving someone expecting a meeting nobody will attend. | +| `meeting_outcome.record` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — the meetings report carries when a booking was made, by whom, from which campaign and on which channel, and no outcome field of any kind. Held, no-show and cancelled beforehand cannot be told apart here, which also means meeting outcomes cannot be read back out of this product later. | +| `meeting.list` | `read` | `auto` | `partial` | reports -> List meetings | `reporting:read` | *missing:* A booking ledger rather than a calendar. A row gives who booked it, the channel it came from, the person, the campaign and when the booking was made — not when the meeting is, who is attending, how to join, or how it went. Nothing upcoming can be answered from it and no outcome can be read out of it.
Filterable by date window and by user, so it does answer how many meetings were booked and by whom over a stated period. Measurement is rate-limited harder than the rest of the surface — sequential calls, cached within the session, no polling. | +| `meeting.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. The reporting list is the only place a meeting appears at all and it has no per-meeting read. | +| `qualification.record` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Custom fields could be made to hold the answers, but that is a schema somebody would have to invent, and inventing it here would produce a record no other run could read back. | +| `handoff.create` | `control` | `confirm_once`
*departs:* raised: it commits another person's time and starts their clock. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Changing who owns a person moves the record; it makes no offer, starts no clock, and can be neither accepted nor refused, so it is not this operation. | +| `handoff.accept` | `control` | `auto` | `absent` | — | — | *because:* Nothing creates a handoff here, so there is nothing to accept and no commitment clock to start. | +| `handoff.reject` | `control` | `auto` | `absent` | — | — | *because:* Nothing creates a handoff here, so there is nothing to refuse. | +| `handoff.return` | `control` | `auto` | `absent` | — | — | *because:* Nothing creates or accepts a handoff here, so there is nothing to give back. | +| `handoff.withdraw` | `control` | `auto` | `absent` | — | — | *because:* Nothing creates a handoff here, so there is nothing to pull back. | +| `handoff.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing shows what has been handed over and left unanswered, in either direction. | +| `handoff.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `opportunity.create` | `control` | `confirm_once`
*departs:* raised: it is one of the four facts people are paid on, and an accidental one corrupts attainment for the period. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. A conversion into a deal is recorded wherever the pipeline lives, and this adapter has no view of that. Name the system the user should record it in rather than approximating it with a field on a person or an account. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-11-meetings.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-12-signals.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-12-signals.md new file mode 100644 index 0000000..dfdf667 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-12-signals.md @@ -0,0 +1,33 @@ + + +# Family 12 — Signals and triggers · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The conversation, the queue and the day* · 10 operations, 10 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `signal.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing reports that someone changed job, visited a page, raised funding or engaged publicly.
ai-sdr-intent-signals -> Industries typeahead, Technologies typeahead is the nearest thing and it is not this: it resolves the words a user says into values a prospect search accepts. Offering it here answers a different question than the one asked. | +| `signal.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Without a feed there is nothing to read one observation from. | +| `signal.acknowledge` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `signal_policy.define` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing arbitrates between two things firing on the same person, because nothing fires. | +| `signal_policy.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `trigger.create` | `control` | `auto` | `partial` | webhooks -> Create a webhook subscription, List supported event types | `webhooks:write`, `webhooks:read` | *missing:* Only the watching half. A subscription delivers a named event to a listener outside the product; the rule's other half — producing work in response — has no surface, so the acting side must live in the agent runtime. The watchable set is fixed and product-side (message sent, opened, clicked, replied, bounced; contact opted out or finished; connection request sent and accepted; account connection lost or erroring), so a rule that must watch something outside that set cannot be expressed at all.
Read List supported event types before promising a rule — the event names are the whole vocabulary, and a trigger written against an event that is not on that list will never fire rather than failing loudly. | +| `trigger.update` | `control` | `auto` | `partial` | webhooks -> Update a webhook subscription, Enable a webhook subscription, Disable a webhook subscription | `webhooks:write`, `webhooks:operate` | *missing:* The same half as trigger.create: what the rule watches can be changed, what it produces cannot, because production is not in the product.
"Switch it off without losing it" maps exactly onto Disable, which is the reversible move. Deleting a subscription to stop it and re-creating it later is not the same act and loses the subscription's history. | +| `trigger.list` | `read` | `auto` | `partial` | webhooks -> List webhook subscriptions, List supported event types | `webhooks:read` | *missing:* What each rule watches is listed; what it produces is not, and cannot be, since the producing half is external. Report the watch, and say plainly that the action behind it is the runtime's and not the product's. | +| `trigger.delete` | `control` | `confirm_once` | `partial` | webhooks -> Delete a webhook subscription | `webhooks:write` | *missing:* Removes the watch only. Whatever the agent runtime built on top of that event keeps existing and has to be taken down separately, or it becomes a rule waiting on an event that will never arrive again. | +| `trigger_run.list` | `read` | `auto` | `partial` | webhooks -> Get webhook delivery logs | `webhooks:read` | *missing:* Deliveries, not runs. The log says which event fired and whether it reached the listener; what work came out of it and what a policy held back are not recorded, because neither the work nor the policy exists on this side. Never report a delivery count as a count of work done. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-12-signals.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-13-inbound.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-13-inbound.md new file mode 100644 index 0000000..b5a4f1b --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-13-inbound.md @@ -0,0 +1,34 @@ + + +# Family 13 — Inbound · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The conversation, the queue and the day* · 11 operations, 11 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `inbound_lead.record` † | `control` | `auto`
*departs:* the protective floor — recording an event that already occurred outside our control is not a decision, and delaying it burns the only thing this motion is measured on. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is no inbound-lead or form-capture group: an arrival has nowhere to be recorded as an arrival, with the clock the rest of this family depends on.
Do not simulate the queue out of tasks, contact owners or inbox categories. Those entities have their own meanings and their own operations, and an arrival modelled as a task loses the one thing that made it an arrival — the response clock. | +| `inbound_lead.list` † | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `inbound_lead.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `inbound_lead.route` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is no routing rule — territory, existing owner, round-robin or availability — anywhere in the documentation.
Contact and account ownership can be changed, but changing an owner is not routing an arrival: it carries no rule, no queue and no clock, and reporting it as routing would claim a guarantee that was never made. | +| `inbound_lead.claim` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `inbound_lead.release` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `inbound_lead.triage` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing classifies what kind of request an arrival is.
Inbox categories classify reply threads on conversations we started. That is a different act on a different entity, and it is covered by its own contract operation. | +| `inbound_lead.close` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `inbound_lead.reopen` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `response_policy.define` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No response target can be stated, so none can be measured or breached. | +| `response_policy.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-13-inbound.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-14-privacy.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-14-privacy.md new file mode 100644 index 0000000..85e19b1 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-14-privacy.md @@ -0,0 +1,46 @@ + + +# Family 14 — Consent, suppression and privacy · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*Permission and capability* · 23 operations, 23 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `outreach.precheck` † | `read` | `auto` | `partial` | contacts -> Get a contact's statuses; contact-blacklist-rules -> List email blacklist rules, List domain blacklist rules, List email exception blacklist rules | `contacts:read` | *order:* Read the contact's statuses first — the opted-out state is a global flag there, and a person opted out is a stop with no further questions. Then search the email rules for the address and the domain rules for its domain. Read the exception rules as well: a match on a domain rule is not final on its own.
*missing:* It answers one question — is this person opted out or excluded on email — and the operation asks four. There is no channel dimension, so a social or phone precheck is not covered. There is no timing half, so "if not, when" cannot be answered. There is no consent basis and no external-register gate. Nothing says what would fix it. Say all of this before a user commits to a route that treats the precheck as sufficient.
The result is stale the moment it returns, here as in the contract. Nothing about knowing which endpoint answers it changes that. | +| `suppression.check` | `read` | `auto` | `partial` | contact-blacklist-rules -> List email blacklist rules, List domain blacklist rules, List email exception blacklist rules | `contacts:read` | *missing:* The "why". A rule carries its pattern and whether it is system-wide, and nothing else — no reason class comes back, so the answer is yes-or-no with no ground for it. Only email addresses and domains are covered; a number, a social profile or a whole account has no equivalent.
The listings filter by pattern, so a raw identifier can be checked without it being a contact in the system — which is the part of this operation that matters. | +| `suppression.list` | `read` | `auto` | `partial` | contact-blacklist-rules -> List email blacklist rules, List domain blacklist rules, List email exception blacklist rules | `contacts:read` | *missing:* Three separate lists rather than one, and none of the three facets the operation promises: no scope, no reason class, no record of who added the entry. Numbers, social profiles and whole accounts are not represented at all. | +| `suppression.add` † | `control` | `confirm_once`
*conditional:* auto for a single verified identifier, which is protective; confirm_once for a domain, an account pattern or a collection. | `partial` | contact-blacklist-rules -> Create an email blacklist rule, Create a domain blacklist rule, Bulk create email blacklist rules, Bulk create domain blacklist rules | `contacts:write` | *missing:* "And here is why" has nowhere to go — no reason is recorded against a rule, so the reason has to be kept in the agent's own record or it is lost, and suppression.remove later has nothing to weigh. Numbers, social profiles and whole accounts have no equivalent.
The contract's read-before-repeating has a real surface here: search the listing for the pattern first. Adding a pattern that already exists is a refusal, so a blind retry is wrong. | +| `suppression.remove` | `control` | `confirm_once` | `partial` | contact-blacklist-rules -> Delete an email blacklist rule, Delete a domain blacklist rule, Bulk delete email blacklist rules, Bulk delete domain blacklist rules | `contacts:write` | *missing:* The evidence that licenses the lift is not recorded, and no retention floor is exposed to check against — so the one guard the contract puts on this irreversible act cannot be enforced by the product and must be enforced by the agent before the call. Email addresses and domains only. | +| `optout.record` † | `control` | `auto`
*departs:* the protective floor — recording that somebody said stop is an operation whose non-performance is itself the harm, and waiting for permission to stop is the destructive choice. | `partial` | contact-blacklist-rules -> Create an email blacklist rule, Bulk create email blacklist rules | `contacts:write` | *missing:* It records the exclusion, not the act. What they said, where it arrived, when they did it and when we learned of it have nowhere to go, so the evidence that this was their decision is not retained. The product carries its own opted-out state on a contact — readable through Get a contact's statuses — but no documented surface sets it.
This is the protective floor operation: recording that somebody said stop is performed first and reported immediately. A blacklist rule stops future sends, which is the effect that matters most; keep the act itself in the agent's own record alongside it. | +| `optout.poll` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing pulls un-ingested stop signals from the channel — one-click unsubscribes, list-unsubscribe requests, blocks or stop keywords.
The notification surface carries a contact-opted-out event. That is a push about an opt-out the product has already ingested, not the backlog of ones it has not, and the two are not interchangeable: subscribing to it tells you nothing about what is waiting at the channel. | +| `optout.confirm` | `act` | `confirm_each` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No opt-out confirmation exists as its own act, and no ledger records whether one was already sent.
A direct email to a contact can be sent, and using it for this is the substitution to refuse. This confirmation is exactly-once, non-promotional and may never require anything of the recipient; with no ledger to check, a second one is a breach rather than a duplicate, and nothing here would stop it. | +| `consent.record` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is no permission record: what they were told, when, how it was captured and what it covers have nowhere to live. | +| `consent.revalidate` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. With no basis recorded there is nothing to recompute and no contactability to downgrade. | +| `consent.prove` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `notice.send` | `act` | `confirm_each` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Neither the delivery of a privacy notice nor the record that it was delivered has a surface. | +| `disclosure.check` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `disclosure.record` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing binds a disclosure to the message that carried it. | +| `dnc_registry.check` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No external do-not-contact register is reachable from here; the blacklist rules are our own list, not a jurisdiction's. | +| `privacy_request.create` | `control` | `auto`
*departs:* the protective floor — failing to open the record is itself the breach. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is no privacy-request entity, so no clock starts and nothing later can be tied to a request. | +| `privacy_request.update` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `privacy_request.refuse` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `privacy_request.fulfill` | `act`
*conditional:* `act` when it discloses data to the requester; `control` when it erases. | `confirm_each` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is no recorded request to fulfil against, and no export of everything held about a person.
Contacts can be deleted, singly and in bulk. That is contact.delete, a different contract operation with a different meaning, and performing it must never be reported as fulfilling a privacy request: the request record is the whole point of this operation and it does not exist here. | +| `deletion_feed.poll` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No external erasure register is reachable from here. | +| `deletion_feed.report` | `control` | `auto`
*departs:* the protective floor — the reporting deadline is the obligation, so not reporting is the harm. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `retention.apply` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No storage limit can be stated or enforced, and no floor is exposed to stop at. | +| `audit_log.search` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is no audit surface: who changed what, when, on our side is not answerable.
A contact's activity history is the record of outreach that touched that contact. It is not a record of our own changes, and it cannot answer why this person was contacted at all — which is the harder half of the question and the one that gets asked under pressure. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-14-privacy.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-15-sending.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-15-sending.md new file mode 100644 index 0000000..e614f0d --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-15-sending.md @@ -0,0 +1,57 @@ + + +# Family 15 — Sending capability and deliverability · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*Permission and capability* · 34 operations, 34 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `sender.list` | `read` | `auto` | `partial` | email-accounts -> List email accounts, Filter email accounts; linkedin-accounts -> List LinkedIn accounts, List pending LinkedIn accounts | `channels:read` | *missing:* Two lists rather than one, and only two of the four capability classes. Mailboxes and social accounts are covered; numbers and business messaging identities have no group at all, so a channel the user asks about may be invisible rather than empty.
Merge the two and label every row with its channel, or the caller cannot tell what it is looking at. Read the pending social list too: a half-finished connection must read as pending setup, never as absent, and leaving it out is how a sender that is nearly ready gets connected a second time. | +| `sender.get` | `read` | `auto` | `partial` | email-accounts -> Get an email account; linkedin-accounts -> Get a LinkedIn account | `channels:read` | *missing:* Identity, channel and configured pacing come back. Pool membership and registration do not, because neither concept exists here — see sender_pool.* and messaging_registration.*. Mailboxes and social accounts only. | +| `sender.health` † | `read` | `auto` | `partial` | email-accounts -> Get an email account, Test SMTP connectivity, Test IMAP connectivity; linkedin-accounts -> Get a LinkedIn account | `channels:read`, `channels:operate` | *missing:* Connection state and configured limits are readable, and the mailbox read reports whether the provider has locked or throttled the account. Warm-up position, the channel's automation sanction, and any statement of how much of today's capacity is still available are not exposed — so three of the five things this operation promises have to be tracked by the agent or left unanswered. Numbers and business messaging identities are not covered.
The connectivity tests verify the credential actively rather than reporting a cached status, which is the difference that matters when an account looks fine and is not. A disconnected or erroring account is still a hard stop: this is a core operation and the launch chain refuses on it. | +| `sender.connect` | `control` | `confirm_once` | `partial` | email-accounts -> Create an email account, Connect Gmail account via OAuth, Connect Office 365 account via OAuth; linkedin-accounts -> Create a connection link, Create a direct connection link | `channels:write` | *missing:* Mailboxes and social accounts only; numbers and business messaging identities have no surface. On the social channel the call produces a link a person has to complete, so the operation is not finished when the call returns.
Poll the pending social list until the account appears in the real one. Until then it is the contract's pending-setup state, and reporting it as connected is how a campaign gets launched against a sender that cannot send. | +| `sender.disconnect` | `control` | `confirm_once` | `partial` | email-accounts -> Delete an email account, Bulk delete email accounts; linkedin-accounts -> Delete a LinkedIn account, Bulk delete LinkedIn accounts | `channels:write` | *missing:* It deletes rather than detaches, and the guard the contract puts on this operation is absent: nothing refuses while live enrolments or open conversations still depend on the sender, and no rebind target can be supplied. The check is the caller's, and it has to happen before the call because there is nothing to undo afterwards.
What is bound to a sender is readable only one campaign at a time (sequence-email-accounts -> List email accounts in sequence; sequence-linkedin-accounts -> List LinkedIn accounts for a sequence), so the check is a scan. On the social channel sender.pause is the reversible alternative and is usually what the user actually wants. | +| `sender.reauthorize` | `control` | `auto` | `partial` | linkedin-accounts -> Reconnect a LinkedIn account; email-accounts -> Connect Gmail account via OAuth, Connect Office 365 account via OAuth | `channels:write` | *missing:* Only the social channel has a reconnect that names the existing account. On a mailbox the documented route is re-running the provider connection, and nothing states that the history behind it survives — which is the whole promise of this operation. Verify by re-reading rather than assuming, and tell the user what you could not confirm. | +| `sender.pause` | `control` | `auto` | `partial` | linkedin-accounts -> Toggle LinkedIn account status | `channels:operate` | *missing:* Social accounts only. A mailbox has no documented pause — the resume surface exists with no counterpart — so on email the protective move has to be made one level up, at campaign.pause or by removing the sender from the campaign. Say which one you used, because they are not the same blast radius.
The social call flips between enabled and disabled rather than setting a state. Read the account first: issued blind against an already-paused account it re-enables it, which turns the first move in an incident into the worst one. | +| `sender.resume` | `control` | `confirm_once`
*departs:* raised from auto: sender.pause is protective, and the restart direction of a protective pair is never auto. Platforms escalate on the frequency of restrictions, not their type, so resuming at pre-restriction volume the moment a block lifts is the standard way to turn a temporary restriction into a permanent one; a recorded restriction invalidates the current warm-up position and this operation refuses while it is invalid unless a ramp restart is supplied or an override is recorded with an actor and a reason. | `partial` | email-accounts -> Resume sending; linkedin-accounts -> Toggle LinkedIn account status | `channels:operate` | *missing:* Nothing refuses the resume on an invalid warm-up position, because no warm-up position is exposed at all — the contract's guard has to be enforced by the caller or it is not enforced. The mailbox surface is scoped to accounts the provider locked or throttled, not to an operator pause, and no operator pause exists on that channel.
Resolve the underlying problem before calling, then re-read the account to confirm the lock actually cleared. The social call flips rather than sets — read state first, same as with sender.pause. | +| `sender_limit.set` | `control` | `confirm_once`
*departs:* raised from auto: one call declares how much this capability may send, how fast and with what spacing, over limits somebody else may have declared — the read before repeating is the limits in force and who declared each. The derivation table admits confirm_once where a call may overwrite state someone else owns only in the compensatable column, so declaring it on a reversible control is a raise. | `partial` | linkedin-accounts -> Update LinkedIn account limits; email-accounts -> Update an email account | `channels:write` | *missing:* The contract's one decision is two different surfaces, one per channel, and only the social one is a dedicated limits endpoint — on a mailbox the limits ride on the account update, so a careless call can overwrite settings the caller did not intend to touch. Numbers and business messaging identities have no surface.
Read the limits in force first and re-read after: report what actually took, not what was requested. Lowering is protective; raising is the direction that needs the approval, and the mapping does not change that. | +| `warmup_plan.set` | `control` | `confirm_once`
*departs:* raised from auto: warm-up is a state machine with a position, and that position is what sender.resume refuses on — a recorded restriction invalidates it — so redefining the ramp overwrites the state that governs whether the sender may send at all. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No ramp can be defined, read or started, and no warm-up position is exposed anywhere in the API.
This is the absence that costs the most in this family: sender.resume refuses on the warm-up position, and with no position readable that refusal cannot be automated. Tell the user the ramp is theirs to hold, and hold it in the agent's own record. | +| `message_element.set` | `control` | `confirm_once`
*departs:* raised from auto: the call overwrites what every message sent afterwards is legally held to, and the unsubscribe mechanism is three separate artefacts — a header, a machine-actionable endpoint that actually honours a request, and a visible link in the body — each separately required, configured and checked, where header presence proves only the first. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. The legal identification block, the postal address, the channel's stop artefacts and the tracking domain have no per-sender configuration surface. | +| `sender.reserve` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is no allowance reservation, so two parallel runs against one sender can spend the same capacity twice and neither will be told. | +| `sender.release` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing to give back, since nothing can be claimed. | +| `sender.summarize` | `read` | `auto` | `absent` | email-accounts -> Get email account stats, Filter email account stats | — | *because:* The per-sender figures surface is documented Coming soon and is not callable today. Say that rather than reaching for something adjacent, and check the page again before planning around it.
The reporting overview is account-wide, not per sender, and answers a different question. Substituting it produces a number that looks like this sender's and is not, which is worse than having none. Even when the stats surface opens, failures by class, complaints with their publisher and denominator, deferrals and throttles are not promised by it. | +| `restriction.record` | `control` | `auto`
*departs:* the protective floor: recording an event that already happened outside our control derives auto whatever its reversibility, and waiting for permission to record a restriction is the destructive choice — the invalidated warm-up position and the recurrence count both hang off this record. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is no restriction ledger, so a restriction cannot be recorded, counted, or carried forward.
The arrival of one is observable — the notification surface carries account-alert, connection-lost and account-error events, and the mailbox read reports a provider lock. What is missing is the durable record behind them. Keep it in the agent's own record: the recurrence count and the invalidated warm-up position both hang off it, and platforms escalate on how often a sender is restricted rather than on what for. | +| `restriction.appeal` | `act` | `confirm_each`
*departs:* raised from confirm_once: an appeal is written content submitted under a named human's identity, usually with one chance. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No appeal route is exposed; where the platform offers one it is outside this API, and saying so plainly is the correct answer. | +| `sender_pool.create` | `control` | `confirm_once` | `partial` | sequence-email-accounts -> Set sequence email accounts, Assign email account to sequence; sequence-linkedin-accounts -> Assign a LinkedIn account to a sequence | `sequences:read`, `sequences:operate` | *missing:* There is no pool object. The grouping exists only as the set of senders bound to one campaign, so it cannot be named, cannot be created before the campaign exists, and cannot be reused by a second campaign without being rebuilt. Routing policy is not part of it.
Rotation across the bound senders is the product's own behaviour, so do not tell a user that sending across several senders is unavailable — that is a wrong answer, not a cautious one. What is unavailable is the reusable, named, independently routable pool. | +| `sender_pool.update` | `control` | `confirm_once`
*departs:* raised from auto: the call carries the pool's membership and its routing policy, and rotation is not a cure — where a budget's scope is the pool, the organisation or the recipient, rotating across senders moves the problem, and sticky per recipient is correctness on conversational channels rather than optimisation, so this overwrites state that live conversations depend on. | `partial` | sequence-email-accounts -> Set sequence email accounts, Assign email account to sequence, Remove email account from sequence; sequence-linkedin-accounts -> Assign a LinkedIn account to a sequence, Remove a LinkedIn account from a sequence | `sequences:read`, `sequences:operate` | *missing:* Membership changes, one campaign at a time. The routing policy does not — and sticky per recipient in particular is not selectable, which on a conversational channel is correctness rather than optimisation. Say that before a user commits to a route that needs a recipient to keep hearing from the same sender.
Setting the whole set replaces it. Read the current members first, or a call meant to add one sender silently removes the rest. | +| `sender_pool.list` | `read` | `auto` | `partial` | sequence-email-accounts -> List email accounts in sequence; sequence-linkedin-accounts -> List LinkedIn accounts for a sequence | `sequences:read` | *missing:* Pools cannot be enumerated. Every read is scoped to one campaign, so "what pools exist" is answerable only by walking every campaign, and how work routes across the members is not reported at all. | +| `sender_pool.delete` | `control` | `confirm_once` | `partial` | sequence-email-accounts -> Remove email account from sequence; sequence-linkedin-accounts -> Remove a LinkedIn account from a sequence | `sequences:read`, `sequences:operate` | *missing:* There is no pool to dissolve. Removing every binding leaves the campaign with no sender rather than dissolving a named group — nothing refuses it while the campaign is live and no replacement target can be supplied, so the campaign is left unable to send and nothing says so.
The capabilities themselves are untouched, as the contract expects: this removes bindings, not senders. | +| `sending_domain.register` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Domains are not a first-class entity here; a sender carries its address and that is all. | +| `sending_domain.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `sending_domain.retire` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `authentication_requirement.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. What has to be published for a domain to authenticate is not stated anywhere in the API. | +| `domain_compliance.check` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No verdict per publisher and per requirement is available, so a failing requirement cannot be named. | +| `domain_reputation.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No reputation signal, blocklist listing or dataset is exposed. | +| `message_compliance.check` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing evaluates a rendered message against what it will be held to: required elements, a working unsubscribe, or the reputation of the domains it links to.
The rendered message itself can be obtained (email-templates -> Render an email template, Send a test email), so the check can be performed outside the product against a real rendering rather than against the source. That is worth doing, and it is not this operation — report it as an external check. | +| `placement_test.create` | `act` | `confirm_each` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. There is no seed-list send and no per-provider placement result.
The email-validation surface estimates and schedules address validation. That answers whether an address exists, never where a message lands, and offering it here would answer a deliverability question with a data-quality one. | +| `placement_test.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `messaging_registration.submit` | `act` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No brand or use-case registration exists, because the channels that require one before any send is permitted are not represented in this API. | +| `messaging_registration.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `approved_content.submit` | `act` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No content is submitted to a platform for pre-approval.
The pending-approval surface in the AI-SDR cluster is a person inside the organisation approving generated content before it sends. This operation is a platform gating content before we are permitted to send it at all. They are different actors with different consequences for refusal, and mapping one onto the other would report an internal sign-off as a platform's permission. | +| `approved_content.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `approved_content.retire` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-15-sending.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-16-social.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-16-social.md new file mode 100644 index 0000000..6cb8d47 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-16-social.md @@ -0,0 +1,36 @@ + + +# Family 16 — Social and messaging channels · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*Permission and capability* · 13 operations, 13 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `social_invitation.send` | `act` | `confirm_each`
*departs:* raised: the note is content addressed to a named person. | `direct` | direct-outreach -> Send a LinkedIn connection request to a contact | `contacts:operate` | The optional note is supported, and that is exactly why the contract's confirm_each applies: it is content addressed to one named person, so the literal text is approved before the call, not a description of it. The person must already be a contact carrying a profile URL, and the caller names which connected social account sends it — so sender.health comes first. The send happens outside any campaign, which means campaign pacing does not apply to it and the daily invitation limit has to be respected by the caller; see linkedin-guardrails for the pacing this operation is subject to. The contract's read before repeating — the invitation state for this pair — has no surface here, because social_invitation.list is absent. Keep that ledger in the agent's own record, or a retry becomes a second invitation to somebody who already has one. | +| `social_invitation.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Invitations sent cannot be listed, so neither what is pending nor how old it is can be answered.
The pending social-account listing is a different thing despite the similar name: it is accounts waiting to finish connecting to the product, not invitations waiting on people. Confusing the two produces a confident answer to a question nobody asked. | +| `social_invitation.withdraw` | `control` | `confirm_once`
*conditional:* auto for one invitation; confirm_once for a collection. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. A sent invitation cannot be taken back through the API. | +| `social_invitation.accept` | `act` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `social_invitation.decline` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `social_relationship.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing answers, on demand, whether we are connected to this person or at what degree.
The notification surface reports connection requests sent and accepted, so a standing relationship ledger can be maintained outside the product from those events. That is a ledger the agent builds and owns; it is not a read, and it knows nothing about people we never invited. | +| `social_profile.view` | `act`
*conditional:* `act` where the channel surfaces the view to the person; `read` where the operator has declared that it does not. Where the operator has declared neither, absence resolves to `act`. | `confirm_each`
*conditional:* confirm_each while it resolves to `act`; auto where it resolves to `read`. Bulk profile research is exactly the case a standing approval exists for. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No profile read is exposed, metered or otherwise. | +| `social_profile.follow` | `act` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `social_profile.unfollow` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `social_post.react` | `act` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. | +| `social_post.comment` | `act` | `confirm_each`
*departs:* raised from confirm_once: it is published content under a named human's identity. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. No published content can be posted under a person's identity through this API. | +| `social_credit.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. The metered messaging allowance is not readable: how many credits remain, when they expire and whether a reply returns one are all unanswerable.
A metered message can be sent without any way to check the balance first, so the meter is discovered by exhausting it. Warn the user before planning volume that depends on it. | +| `conversation_window.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this. Nothing reports whether this person may be written to freely right now, only with pre-approved content, or only by spending a credit.
Both routes exist as sends — an ordinary message and a metered one — but nothing says which is permitted for a given person, so the choice is the caller's and a wrong one fails at send time rather than at planning time. That is a real cost to surface before the user commits to a social route. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-16-social.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-17-oversight.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-17-oversight.md new file mode 100644 index 0000000..e72c9ff --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-17-oversight.md @@ -0,0 +1,55 @@ + + +# Family 17 — Oversight, review and safety · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The organisation around the work* · 32 operations, 32 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `approval.request` | `control` | `auto` | `absent` | — | — | *because:* No documented surface puts an item into a queue for a human. The pending-approval endpoints list, read, send, reject and regenerate items that are already there — the AI SDR sequence generates them itself under the approval mode set on that sequence, and nothing else can be queued for review. | +| `approval.list` † | `read` | `auto` | `partial`
*documented Beta or Coming soon* | ai-sdr-pending-approvals -> List pending approvals | `ai-sdr:read` | *missing:* Only AI-generated messages inside an AI SDR sequence reach this queue, on email and LinkedIn. A bulk write, a piece of content or a policy change waiting on a human has no queue here at all, so an empty queue does not mean nothing is waiting.
Each item carries when it was created rather than how long it has waited — the age the operation reports is computed from that. The queue can be filtered by sequence and by user. | +| `approval.get` | `read` | `auto` | `partial`
*documented Beta or Coming soon* | ai-sdr-pending-approvals -> Get pending approval for a contact | `ai-sdr:read` | *missing:* The item is addressed by contact rather than by an approval identifier, and only an AI-generated message is retrievable this way. Anything else a human is being asked to approve has no item to fetch. | +| `approval.resolve` † | `act`
*conditional:* `act` on approve, `control` on reject. | `confirm_each`
*conditional:* confirm_each on approve, confirm_once on reject — and the resolution is the confirmation when a human performs it directly. | `partial`
*documented Beta or Coming soon* | ai-sdr-pending-approvals -> Send a pending approval, Send a batch of pending approvals, Reject (delete) a pending approval | `ai-sdr:write` | *missing:* Rejection records no reason and is heavier than the contract's reject: it discards the queued draft and removes the contact from the sequence, with nothing documented to bring either back. Tell the user that before they reject, and keep the reason wherever the run is recorded.
Approving is the send, exactly as the contract has it, so the approval class is unchanged by the mapping — one named recipient is confirm_each, and the batch send is confirm_once over a preview that names the population. | +| `autonomy.get` | `read` | `auto` | `partial`
*documented Beta or Coming soon* | ai-sdr-sequences -> Read AI SDR sequence settings | `ai-sdr:read` | *missing:* One AI SDR sequence's own settings — whether its generated messages need approval, and whether autopilot is on. Nothing states what a credential may do unattended across the account, and there is no queue timeout, unattended action cap or escalation target to read. Everywhere else, autonomy is the agent's own policy held outside this product. | +| `autonomy.set` | `control` | `confirm_once`
*departs:* raised, because the acts permitted under a loosened setting are not reversible even though the setting is. | `partial`
*documented Beta or Coming soon* | ai-sdr-sequences -> Set the approval mode, Enable autopilot, Disable autopilot | `ai-sdr:operate` | *missing:* The gate and the mode, on one AI SDR sequence. The queue timeout and what a timeout means, the unattended action cap, the escalation target and per-channel differences have no setting here.
Turning the gate off can also release everything already waiting, in the same call. That makes loosening the gate a send, not a settings change, and it must be previewed and approved as one. | +| `escalation.raise` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `escalation.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `escalation.resolve` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `editorial_review.record` | `control` | `confirm_once` | `absent` | — | — | *because:* not evidenced — no documented surface binds a named human's review to a sent message. A message approved out of the AI SDR queue records that it was sent, which is not the same fact and must never be reported as one. | +| `editorial_review.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — nothing records the review, so nothing can return it. The honest answer to an auditor here is that no review evidence exists in this product. | +| `review.request` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `review.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `review.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `review.score` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `feedback.record` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `review_policy.define` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `review_policy.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `scorecard.define` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `scorecard.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `scorecard.publish` | `control` | `confirm_once`
*departs:* raised, because every score taken afterwards carries this version and past scores must stay comparable. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `scorecard.retire` | `control` | `confirm_once`
*departs:* declared confirm_once where control × reversible derives auto, and the contract does not yet state why. The row's own terms are that it can be published again and everything already scored keeps its history, so the raise stops at one confirmation. Kept at the declared, stricter class until the question is settled: an unexplained confirmation costs a sentence, and lowering a class on a guess costs whatever relied on it. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `coaching.summarize` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — the reporting surfaces cover activity and performance, not coaching. Nothing records that someone attended, listened, commented, scored or gave feedback, so there is nothing to summarise per coach. | +| `budget.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface reports what is left on a meter. A meter does exist: starting a Live Data search spends the user's data allowance. That the remaining allowance cannot be read is exactly why a search is previewed before it is started. | +| `budget.set` | `control` | `confirm_once`
*departs:* raised whenever it raises a ceiling, because the spending it then permits is not reversible. | `absent` | — | — | *because:* not evidenced — checked against the endpoint index, nothing sets an allowance ceiling of the kind a pre-flight check reads. | +| `stoprule.set` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `stoprule.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `stoprule.clear` | `control` | `confirm_once`
*departs:* raised, because removing a safety rule is exactly the write that should never happen by accident. | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `stoprule_firing.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — nothing stops the work by itself here, so there are no firings to list. When sending is off in this product it was a person or an agent that stopped it, and the reason lives in the run record rather than in the API. | +| `stoprule_firing.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `outreach.hold` † | `control` | `auto` | `partial` | contact-blacklist-rules -> Create an email blacklist rule, Create a domain blacklist rule, Bulk create email blacklist rules, Bulk create domain blacklist rules | `contacts:write` | *missing:* This blocks future contact and nothing else. Live enrolments, scheduled steps, open tasks, pending approvals and outstanding meeting proposals are untouched by it, and the rule returns no per-item ledger of who was actually reached. The kill switch the contract describes is only realised once those are stopped too, through their own operations, and every one of them has to be reported.
A person is held by an email rule and a company or a domain by a domain rule. Rules are account-wide, so check the existing rules before adding one and expect the block to apply to work other people own. | +| `outreach.release` | `control` | `confirm_once`
*departs:* raised, because a restart resumes contact with people whose situation may have changed while they were held. | `partial` | contact-blacklist-rules -> Delete an email blacklist rule, Delete a domain blacklist rule, List email blacklist rules, List domain blacklist rules | `contacts:write`, `contacts:read` | *missing:* Deleting the rule lifts the block, but nothing resumes by itself: whatever was stopped when the hold went on has to be restarted deliberately, and no ledger of what was held exists to restart it from. Re-check each person's eligibility first — the contract requires it and this product will not. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-17-oversight.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-18-team.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-18-team.md new file mode 100644 index 0000000..9b91502 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-18-team.md @@ -0,0 +1,38 @@ + + +# Family 18 — The team: people, ownership, workload and targets · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The organisation around the work* · 15 operations, 15 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `actor.list` | `read` | `auto` | `partial` | user-account -> List team users | — | *missing:* Identity only — the team, the user identifier, the display name and the email address. The state the operation asks for, active, ramping, unavailable or gone, is not carried, so this read cannot tell an agent whether the person it is about to hand work to is still there.
No scope required. It covers the teams this credential can act in; people outside them do not appear, which is a different answer from not existing. | +| `actor.get` | `read` | `auto` | `partial` | user-account -> Get current user, List team users | — | *missing:* Only the calling credential has a record of its own. Anyone else is an identity row in the team listing and nothing more — no state, and none of the ceilings that apply to them. | +| `team.list` | `read` | `auto` | `direct` | user-account -> List team users | — | Every row carries the team it belongs to, so one read answers both which teams exist and who is in them. No scope required. Teams this credential cannot act in are not listed. | +| `workload.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — checked against the endpoint index, nothing reports what a person is carrying. Open tasks and live enrolments can each be listed on their own, but no surface answers the question this operation asks, and adding up two listings is not the same answer. | +| `workload_policy.define` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `workload_policy.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no ceiling is declared anywhere, so the answer here is always none declared, which the contract reads as unlimited. | +| `ownership.get` | `read` | `auto` | `partial` | accounts -> Get an account; contacts -> Filter contacts | `contacts:read` | *missing:* The owner is an attribute of the record rather than a surface of its own, so it is read with the record. The second half of the question has no answer here at all: nothing states whether acting on an unowned record would make the actor its owner, and that rule is set in the product's own settings rather than returned by any response. | +| `ownership.assign` | `control` | `auto` | `direct` | contacts -> Change contacts owner; accounts -> Update account owner | `contacts:operate`, `contacts:write` | One endpoint per subject kind — people through the contact group, companies through the account group. There is no routing rule to defer to here, so the caller names the person; check they are still on the team first, because the owner listing carries no state. | +| `assignment_policy.define` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface was found for this | +| `assignment_policy.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no routing rule is stored in this product, so there is none to read and nothing that would say who gets the next piece of work. | +| `book.transfer` | `act` | `confirm_once` | `partial` | contacts -> Change contacts owner; accounts -> Update account owner; tasks -> Batch reassign tasks | `contacts:operate`, `contacts:write`, `tasks:write` | *missing:* Three parts of the book move — contact ownership, account ownership and open tasks. The senders behind live threads, the open conversations and the authored content do not, and no surface reports the book as a whole, so the ledger the contract requires has to be built by the caller from what each call returns before anything is repeated.
Reassigning ownership does not re-point the sending account behind a live thread. Say so before the transfer: a departing person's threads keep sending from their mailbox until the sequences are changed, and that is the part users are most often surprised by. | +| `goal.define` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — checked against the endpoint index, this product stores no quota, goal or target, so there is nothing to set. | +| `goal.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no target is stored here, so there is none to read. | +| `goal.list` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no target is stored here, so there is none to list. | +| `pace.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — pace is a target measured against achievement, and no target exists in this product. Achievement alone is readable through the reporting surfaces, and reporting it as pace would invent the half that is missing. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-18-team.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-19-accounts.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-19-accounts.md new file mode 100644 index 0000000..6390eab --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-19-accounts.md @@ -0,0 +1,35 @@ + + +# Family 19 — Accounts and buying groups · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The organisation around the work* · 12 operations, 12 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `account.get` | `read` | `auto` | `direct` | accounts -> Get an account | `contacts:read` | The record carries the owner, the stage it is in and how many people are linked to it. The verification read after any account write. | +| `account.search` | `read` | `auto` | `direct` | accounts -> Filter accounts, List accounts | `contacts:read` | Companies already held, never an outside database and never metered — matching the contract exactly. The discovery family is where an outside search belongs. | +| `account.update` | `control` | `auto` | `partial` | accounts -> Update an account | `contacts:write` | *missing:* The account's stage can be moved and the rest of the record edited, but the tier the contract names has no home on the record and neither does the reason for the change. The stages are whatever this account has declared, so resolve the words the user says against them before writing — a stage that does not exist is a guess. | +| `account.claim` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — there is no lease on an account here. Ownership can be changed, which is a different and heavier act: it does not expire by itself, and using it as a claim would leave the account permanently reassigned. | +| `account.release` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — nothing claims an account, so there is nothing to release. | +| `account_membership.create` | `control` | `auto` | `direct` | accounts -> Bulk add contacts to an account | `contacts:operate` | Bulk-shaped: reconcile every person in the response rather than reporting the call. Attach deliberately, so that four spellings of one company do not become four accounts. | +| `account_membership.list` | `read` | `auto` | `partial` | accounts -> List contacts for an account | `contacts:read` | *missing:* Who is attached, and no more. How each person came to be attached is not recorded, so the basis the contract wants on every row cannot be given, and whether someone is being touched right now needs a separate read against the sequence they are in. | +| `account_membership.delete` | `control` | `auto` | `direct` | accounts -> Bulk remove contacts from an account | `contacts:operate` | Detaches the person from the company; it does not delete the person and does not stop any outreach they are in. | +| `collision.check` | `read` | `auto` | `partial` | accounts -> List contacts for an account; sequence-contacts -> List contacts in sequence with extended state, Get a contact in a sequence | `contacts:read`, `sequences:read` | *missing:* Only outreach collisions are visible, and only by assembling them: the people on the account, then each one's state in the sequences they are in, then the owner on each record. A live customer, support or opportunity motion is invisible here — it lives in the CRM — so a clean answer from this check is not evidence that the company is free.
Re-run it immediately before enrolling. Collisions appear between planning and execution, and the gap is exactly where the embarrassing double-touch happens. | +| `buying_group.define` | `control` | `auto` | `absent` | — | — | *because:* not evidenced — people can be attached to an account, but nothing records what each of them does in a decision, so a group with roles cannot be expressed here. | +| `buying_group.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no group with roles is stored, so there is none to return. | +| `buying_group.enroll` | `act`
*conditional:* bookkeeping while the campaign is not live, `act` the moment it is, with reach equal to the members it will contact; resolved by the same preview as `campaign.enroll`. | `confirm_once`
*conditional:* confirm_once before go-live; confirm_once with a mandatory preview once live. | `absent` | — | — | *because:* not evidenced — no surface enrols a group as a group. Enrolling several people from one account one by one is a different act: nothing staggers them, orders them, or reacts to one person's reply on behalf of the others, and doing it by hand while calling it this operation would hide exactly the coordination the operation exists for. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-19-accounts.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-20-measurement.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-20-measurement.md new file mode 100644 index 0000000..c19f308 --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-20-measurement.md @@ -0,0 +1,33 @@ + + +# Family 20 — Measurement · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The organisation around the work* · 10 operations, 10 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `engagement.summarize` † | `read` | `auto` | `partial` | reports -> Get email reporting overview, Get calls reporting overview, Get tasks reporting overview, Get LinkedIn reporting overview, Get channel efficiency overview, Get team performance overview; sequences -> Get stats for all sequences, Get sequence stats | `reporting:read`, `sequences:read` | *missing:* The grouping is not an argument. Each report offers the one breakdown it was built for — by channel, by sequence, by team member — and a question that needs a different grouping has to be assembled from the rows behind the numbers instead. The measure set is likewise the report's, not the caller's.
These endpoints are rate-limited harder than the rest of the API: sequential calls, cached within the session, no polling. Report the window alongside every figure — two numbers are only comparable when the window and the basis match. | +| `engagement_event.list` | `read` | `auto` | `direct` | reports -> List email activity, List call activity, List task activity, List LinkedIn activity | `reporting:read` | One listing per channel — these are the rows behind the summary, and the route to any grouping the overviews do not offer. Same stricter rate limits. | +| `funnel.summarize` | `read` | `auto` | `partial` | reports -> Get email reporting overview, Get channel efficiency overview, List meetings | `reporting:read` | *missing:* No surface returns a ladder. The stages come from separate reads, and neither the denominator a stage is measured against nor how well that stage can be known at all is stated anywhere — the caller declares both and has to say so when reporting the result. Stages past the meeting are not covered by any of these. | +| `opportunity.summarize` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — checked against the endpoint index, nothing here carries opportunities or revenue. That answer lives in the CRM, and reporting meetings as though they were the far end of the funnel would overstate what is known. | +| `attribution.explain` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no attribution model is stated anywhere, so nothing can explain why an outcome was credited where it was, or what another model would have said. | +| `response_time.summarize` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface reports time from arrival to first touch, or from a reply arriving to it being answered. | +| `metric.describe` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — checked against the endpoint index, there is no enumeration or definition surface. What a figure means here is prose on its report page, read by a human, and it says nothing about how far the figure can be trusted. | +| `metric.compare` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no surface compares two arms or reports a sample size and an interval. Two report calls placed side by side are not this operation: the arithmetic that says whether the difference means anything is the part that is missing. | +| `export.request` | `control` | `confirm_once`
*departs:* raised because an extract moves personal data out of the system where its handling rules are enforced. | `absent` | — | — | *because:* not evidenced — checked against the endpoint index, no general data export exists. The reporting listings return rows inline and paginated, which is a read rather than a bounded extract, and treating one as the other would move personal data with none of the handling an extract implies. | +| `export.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — nothing produces an extract here, so there is none to collect. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-20-measurement.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/skills/reply-adapter/reply-operations-mapping/references/mapping-21-introspection.md b/skills/reply-adapter/reply-operations-mapping/references/mapping-21-introspection.md new file mode 100644 index 0000000..4953d2e --- /dev/null +++ b/skills/reply-adapter/reply-operations-mapping/references/mapping-21-introspection.md @@ -0,0 +1,38 @@ + + +# Family 21 — Introspection and runtime · mapping + +Generated from `fulfilment.yaml` in this skill. Edit that file, not this one. + +*The organisation around the work* · 15 operations, 15 with an entry · contract 2.0.0 · adapter `reply` + +**Reading the table.** † marks a core operation. *Reach* and *approval* are the +contract's own classification, reproduced here unchanged: knowing which endpoint performs an +operation alters neither what it is nor what it needs approved, and the two columns are present so +a reader can see for themselves that the mapping changed nothing. *Fulfilment* is this adapter's +claim — `direct` (one surface performs it), `composed` (several calls in the stated order), +`partial` (performed, but not to the contract's full promise, with the unkept part named) or +`absent` (not performable here today, with the evidence). *Surface* names an endpoint group and a +documentation page, never a path: the path, its parameters and its body come from that page at call +time. An operation shown as *not assessed* has no entry at all — nobody has answered for it yet, +which is a different statement from `absent`. + +| Operation | Reach | Approval | Fulfilment | Surface | Scopes | Notes | +|---|---|---|---|---|---|---| +| `operation.search` † | `read` | `auto` | `absent` | — | — | *because:* Nothing in this product answers it, and nothing should — the thing being searched is the contract, which the core pack carries. Recorded absent because this register answers only for what this adapter performs. | +| `operation.describe` | `read` | `auto` | `absent` | — | — | *because:* As above: an operation's meaning, its refusals and its five properties come from the contract in the core pack, not from any API surface here. | +| `operation.preview` | `read` | `auto` | `partial`
*documented Beta or Coming soon* | sequence-contacts -> Get sequence preview for a contact; ai-sdr-sequences -> Preview autopilot results; live-data -> Preview a Live Data search | — | *missing:* There is no general dry run. Three specific acts can be previewed, all of them beta, and every other write is knowable only by performing it — which means that for most operations the preview an approval gate wants has to be assembled from reads before the write, not requested from the product.
Preview before Start on a Live Data search is a hard rule, not a courtesy: Start spends the user's allowance and Preview does not. | +| `plan.validate` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no surface takes a plan. Authority, ordering, preconditions and headroom are checked step by step against the reads each step needs, by the agent, before anything runs. | +| `contract.describe` | `read` | `auto` | `absent` | — | — | *because:* Nothing here describes the contract — which version is in force, what was renamed from what, and what it binds an agent to is the core pack's own answer, not this API's. | +| `capability.list` † | `read` | `auto` | `partial` | user-account -> Get current user, List team users | — | *missing:* The granted scope set is not returned by anything. Identity and the teams a credential may act in are readable; what it may actually do is discovered only by making a call and reading an insufficient_scope refusal back. For an unattended run that means the honest per-capability answer is unknown until something is attempted, and unknown is not permission.
Neither read needs a scope, so both work with any working credential. When a capability has to be known in advance, the key's scopes are visible in the product settings rather than through the API. | +| `vocabulary.list` † | `read` | `auto` | `partial` | inbox -> List inbox categories | `inbox:read` | *missing:* Only the reply categories this account has declared. Enrolment statuses, meeting outcomes, step intents, exit reasons, content-policy rule classes and the properties a branch condition may be written over have no listing at all — checked against the endpoint index, there is no enumeration surface. For those kinds the answer is unknown, which the contract allows and which is not the same as an empty list. | +| `schema.describe` | `read` | `auto` | `partial` | custom-fields -> List all custom fields, Get a custom field | `contacts:read` | *missing:* Custom fields only, and only on people. No surface describes the standard fields of a record kind or says which of them may be written; that is prose on the record's own doc pages, read at call time, and it cannot be enumerated. | +| `channel.describe` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — no documented surface states a channel's own rules: whether automation is sanctioned there, how its allowance works, how long a reply window stays open or what recording consent it expects. A sending account's configured limits are a different thing and belong to the sender operations; using them as an answer here would confuse one mailbox's ceiling with the channel's rules. | +| `adapter.describe` | `read` | `auto` | `partial` | the Rate limits guide page; background-jobs -> Get a background job | `other:read` | *missing:* Nothing returns any of this. The request ceilings and the queued-versus-inline rule are documented in prose — reporting and stats endpoints are limited harder than the rest, and a long write answers with a background job to poll — but batch ceilings, page sizes and the scope and lifetime of an idempotency key are not stated, and none of it can be read per installation. | +| `adapter.verify` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — nothing here tests fulfilment. This register is the claim, made from documentation rather than from a run, and it is the thing a verification would check rather than a substitute for one. | +| `job.get` | `read` | `auto` | `partial` | background-jobs -> Get a background job, List background jobs | `other:read` | *missing:* Status, progress and the terminal timestamps are documented, but the result payload is opaque and its shape varies by job kind, so the per-item ledger the contract requires is not guaranteed to be there. Where one outcome per item is needed, reconcile against the entities themselves rather than trusting the job to carry it.
A long write completes when the job reaches a terminal state, not when the call returns. Never blind-retry a bulk write that failed — the first attempt may have partly succeeded. | +| `job.cancel` | `control` | `confirm_once` | `direct` | background-jobs -> Cancel a background job | `other:operate` | Items already processed stay processed, exactly as the contract has it. Cancelling is not an undo: it leaves a partial result, and that result has to be reconciled and reported. | +| `invocation.get` | `read` | `auto` | `absent` | — | — | *because:* not evidenced — checked against the endpoint index, nothing looks a call up by the idempotency key it was sent with. After a lost response the only recovery is the operation's own check-first read, which is why every write in the contract names one. | +| `term.resolve` | `read` | `auto` | `absent` | — | — | *because:* Nothing here resolves a word onto a concept. The vocabularies this account declares can be listed, but mapping a colleague's shorthand or another system's label onto the right concept is the contract's own answer in the core pack. | + +The contract's own classification of these operations — the full five properties, the check before repeating, the invariants they enforce — is in `catalog-21-introspection.md`, in the `sdr-operations` skill. What this adapter does not reach, and why, is collected in [fulfilment.md](fulfilment.md). diff --git a/src/__tests__/skills/adapter-flat.test.ts b/src/__tests__/skills/adapter-flat.test.ts index 3158d1b..bb824bd 100644 --- a/src/__tests__/skills/adapter-flat.test.ts +++ b/src/__tests__/skills/adapter-flat.test.ts @@ -2,24 +2,23 @@ import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest'; import fs from 'fs'; import os from 'os'; import path from 'path'; -import {canonical, clone_repo, copy_dir, run_flat, skills_target} from '../../skills/adapter-flat'; +import {canonical, copy_dir, run_flat, skills_target} from '../../skills/adapter-flat'; import {host_by_id} from '../../skills/hosts'; -import {PACKS_FALLBACK, resolve_packs} from '../../skills/packs'; import {journal_entry, record_pack} from '../../skills/journal'; import type {Detected_host} from '../../skills/detect'; -import type {Runner} from '../../skills/types'; +import type {Pack} from '../../skills/types'; -const all = resolve_packs([], PACKS_FALLBACK); -const core_only = resolve_packs(['core'], PACKS_FALLBACK); -// reply-adapter and agentic-runtime, requested directly with no dependency -// expansion, so ai-sdr-core is absent from the set — used to put two packs -// that do not depend on each other in the same run without either blocking -// the other via ai-sdr-core (see 'run_flat abort status' below). -const adapter_and_runtime_only = resolve_packs(['adapter', 'runtime'], PACKS_FALLBACK, {dependencies: false}); +// run_flat copies whatever packs it is given from a directory of packs, so +// these tests give it several: the journal an earlier version wrote holds up +// to three per host, and `list` and `remove` still act on all of them. +const pack = (name: string): Pack=>({name, version: '0.1.0'}); +const all = [pack('ai-sdr-core'), pack('reply-adapter'), pack('agentic-runtime')]; +const core_only = [pack('ai-sdr-core')]; +const adapter_and_runtime_only = [pack('reply-adapter'), pack('agentic-runtime')]; let root: string; let home: string; -let clone_dir: string; +let source_dir: string; const env = ()=>({REPLY_CONFIG_DIR: path.join(root, 'config')}); const cursor = (): Detected_host=> @@ -31,34 +30,30 @@ const cursor = (): Detected_host=> const copilot = (): Detected_host=> ({def: host_by_id('github-copilot'), config_dir: path.join(home, '.copilot')}); -// A native host reachable by run_flat only under --project (it has no -// user_skills_dir), used to exercise the "no directory for this scope" path. -const codex = (): Detected_host=> - ({def: host_by_id('codex'), config_dir: path.join(home, '.codex')}); - -// Stands in for `git clone`: builds the pack layout the real repo has. -const fake_clone = async(): Promise<{dir: string; commit: string}>=>{ - for (const pack of all) +// Stands in for the package's `skills` directory: one directory per pack, +// one skill in each. +const make_source = (): void=>{ + for (const p of all) { - const skills = path.join(clone_dir, 'plugins', pack.name, 'skills'); - fs.mkdirSync(path.join(skills, `${pack.name}-skill`), {recursive: true}); + const skill = path.join(source_dir, p.name, `${p.name}-skill`); + fs.mkdirSync(skill, {recursive: true}); fs.writeFileSync( - path.join(skills, `${pack.name}-skill`, 'SKILL.md'), - `---\nname: ${pack.name}-skill\ndescription: d\n---\n`, + path.join(skill, 'SKILL.md'), + `---\nname: ${p.name}-skill\ndescription: d\n---\n`, ); } - return {dir: clone_dir, commit: 'deadbee'}; }; const flat_opts = (operation: 'install' | 'remove' | 'list' | 'update', packs = all)=>({ - operation, host: cursor(), packs, scope: 'user' as const, ref: 'main', - home, cwd: path.join(root, 'project'), env: env(), clone: fake_clone, + operation, host: cursor(), packs, scope: 'user' as const, + home, cwd: path.join(root, 'project'), env: env(), source: source_dir, }); beforeEach(()=>{ root = fs.mkdtempSync(path.join(os.tmpdir(), 'reply-flat-')); home = path.join(root, 'home'); - clone_dir = path.join(root, 'clone'); + source_dir = path.join(root, 'source'); + make_source(); fs.mkdirSync(path.join(home, '.cursor'), {recursive: true}); }); afterEach(()=>{ @@ -74,7 +69,8 @@ describe('skills_target', ()=>{ expect(skills_target(host_by_id('cursor'), 'project', home, '/p')).toBe(path.join('/p', '.agents', 'skills')); }); - it('sends a native host under --project to its project directory', ()=>{ + it('sends Codex to .agents/skills in both scopes', ()=>{ + expect(skills_target(host_by_id('codex'), 'user', home, '/p')).toBe(path.join(home, '.agents', 'skills')); expect(skills_target(host_by_id('codex'), 'project', home, '/p')).toBe(path.join('/p', '.agents', 'skills')); }); }); @@ -102,12 +98,12 @@ describe('run_flat install', ()=>{ expect(fs.existsSync(path.join(target, 'reply-adapter-skill'))).toBe(false); }); - it('journals the version, ref, commit and the files it wrote', async()=>{ + it('journals the version and the files it wrote, and no ref or commit', async()=>{ await run_flat(flat_opts('install', core_only)); const entry = journal_entry('cursor', 'user', 'ai-sdr-core', env()); expect(entry?.version).toBe('0.1.0'); - expect(entry?.commit).toBe('deadbee'); - expect(entry?.ref).toBe('main'); + expect(entry).not.toHaveProperty('commit'); + expect(entry).not.toHaveProperty('ref'); expect(entry?.files.some(f=>f.endsWith('SKILL.md'))).toBe(true); }); @@ -137,15 +133,12 @@ describe('run_flat install', ()=>{ expect(journal_entry('cursor', 'user', 'ai-sdr-core', env())).toBeUndefined(); }); - it('fails the host with an actionable hint when cloning fails', async()=>{ - const outcome = await run_flat({ - ...flat_opts('install'), - clone: async()=>{ throw new Error('git not found'); }, - }); + it('fails the host, rather than rejecting, when the pack cannot be read', async()=>{ + const outcome = await run_flat({...flat_opts('install', core_only), source: path.join(root, 'nowhere')}); expect(outcome.status).toBe('failed'); - expect(outcome.reason).toBe('clone-failed'); - expect(outcome.detail).toContain('git not found'); - expect(outcome.hint).toContain('git'); + expect(outcome.reason).toBe('copy-failed'); + expect(outcome.detail).toContain('nowhere'); + expect(outcome.hint).toBeDefined(); }); }); @@ -163,12 +156,9 @@ describe('run_flat remove and list', ()=>{ expect(outcome.packs).toEqual([]); }); - it('lists what the journal says is installed without cloning', async()=>{ + it('lists what the journal says is installed', async()=>{ await run_flat(flat_opts('install', core_only)); - const outcome = await run_flat({ - ...flat_opts('list'), - clone: async()=>{ throw new Error('list must not clone'); }, - }); + const outcome = await run_flat(flat_opts('list')); expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); }); @@ -211,15 +201,10 @@ describe('run_flat scope isolation', ()=>{ // must still be reported and journaled rather than orphaned. describe('run_flat copy failures', ()=>{ it('reports a failed status instead of rejecting when a per-pack copy throws, keeping earlier successes', async()=>{ - const broken_clone = async(): Promise<{dir: string; commit: string}>=>{ - const core_skills = path.join(clone_dir, 'plugins', 'ai-sdr-core', 'skills'); - fs.mkdirSync(path.join(core_skills, 'ai-sdr-core-skill'), {recursive: true}); - fs.writeFileSync(path.join(core_skills, 'ai-sdr-core-skill', 'SKILL.md'), '---\nname: x\n---\n'); - // Deliberately no plugins/reply-adapter/skills directory, so its - // readdirSync throws mid-loop. - return {dir: clone_dir, commit: 'deadbee'}; - }; - const outcome = await run_flat({...flat_opts('install', all), clone: broken_clone}); + // No reply-adapter directory in the source, so its readdirSync + // throws mid-loop. + fs.rmSync(path.join(source_dir, 'reply-adapter'), {recursive: true, force: true}); + const outcome = await run_flat(flat_opts('install', all)); expect(outcome.status).toBe('partial'); expect(outcome.reason).toBe('copy-failed'); expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'installed', version: '0.1.0'}]); @@ -256,7 +241,7 @@ describe('run_flat deletion containment', ()=>{ const outside = path.join(root, 'outside.txt'); fs.writeFileSync(outside, 'do not touch'); record_pack('cursor', 'user', 'ai-sdr-core', { - version: '0.1.0', ref: 'main', commit: 'deadbee', scope: 'user', + version: '0.1.0', scope: 'user', files: [outside], complete: true, installed_at: '2026-07-30T00:00:00.000Z', }, env()); const outcome = await run_flat(flat_opts('remove', core_only)); @@ -296,7 +281,7 @@ describe('run_flat deletion containment', ()=>{ const direct = path.join(target, 'direct.txt'); fs.writeFileSync(direct, 'x'); record_pack('cursor', 'user', 'ai-sdr-core', { - version: '0.1.0', ref: 'main', commit: 'deadbee', scope: 'user', + version: '0.1.0', scope: 'user', files: [direct], complete: true, installed_at: '2026-07-30T00:00:00.000Z', }, env()); await run_flat(flat_opts('remove', core_only)); @@ -323,56 +308,18 @@ describe('run_flat name collisions', ()=>{ expect(outcome.status).toBe('failed'); expect(fs.readFileSync(mine)).toEqual(before); expect(journal_entry('cursor', 'user', 'ai-sdr-core', env())).toBeUndefined(); - // Nothing else depends on ai-sdr-core in this run, so nothing was - // blocked — the hint is specifically for blocked dependents, not for - // the failure itself. expect(outcome.hint).toBeUndefined(); }); }); -// Required fix, raised by the controller from a concern in the original -// self-review: adapter-native.ts never lets a dependent install while its -// dependency failed (failed_names/blocked_names). run_flat must enforce the -// same invariant — a pack that fails on a collision (I3) or a copy error (I1) -// must block anything depending on it, exactly like the native adapter. -describe('run_flat dependency blocking', ()=>{ - it('blocks every pack that depends on one that failed on a collision, and never copies them', async()=>{ - const target = path.join(home, '.cursor', 'skills'); - fs.mkdirSync(path.join(target, 'ai-sdr-core-skill'), {recursive: true}); - fs.writeFileSync( - path.join(target, 'ai-sdr-core-skill', 'SKILL.md'), - '---\nname: mine\ndescription: not the pack\n---\nkeep me\n', - ); - - const outcome = await run_flat(flat_opts('install', all)); - - // reply-adapter and agentic-runtime both depend on ai-sdr-core, so - // neither is attempted — blocked packs get no outcome entry at all, - // matching adapter-native.ts's blocked_names behavior. - expect(outcome.packs).toEqual([{ - name: 'ai-sdr-core', action: 'failed', detail: 'conflicts with an existing skill: ai-sdr-core-skill', - }]); - expect(outcome.status).toBe('failed'); - expect(outcome.hint).toContain('reply-adapter'); - expect(outcome.hint).toContain('agentic-runtime'); - expect(fs.existsSync(path.join(target, 'reply-adapter-skill'))).toBe(false); - expect(fs.existsSync(path.join(target, 'agentic-runtime-skill'))).toBe(false); - expect(journal_entry('cursor', 'user', 'reply-adapter', env())).toBeUndefined(); - expect(journal_entry('cursor', 'user', 'agentic-runtime', env())).toBeUndefined(); - }); -}); - -// C1 (final review): reverse removal order is necessary but not sufficient. -// Once delete_files can report a file it could not remove, a failed removal -// must stop its dependency being removed too, or the host is left holding an -// adapter with no core — the one state this installer exists to prevent. -describe('run_flat remove dependency guard', ()=>{ - it('keeps a dependency installed when removing a pack that depends on it failed', async()=>{ +// A failed removal keeps its entry, and the packs around it are removed: +// nothing depends on anything any more, so one failure blocks nothing. +describe('run_flat remove', ()=>{ + it('keeps the entry of a pack it could not remove and removes the others', async()=>{ await run_flat(flat_opts('install', all)); const target = path.join(home, '.cursor', 'skills'); - // Removal walks [agentic-runtime, reply-adapter, ai-sdr-core]; the - // first rmSync is agentic-runtime's only file. + // The first rmSync is ai-sdr-core's only file. const rm_spy = vi.spyOn(fs, 'rmSync').mockImplementationOnce(()=>{ throw Object.assign(new Error('EPERM: operation not permitted, unlink'), {code: 'EPERM'}); }); @@ -384,26 +331,23 @@ describe('run_flat remove dependency guard', ()=>{ } expect(outcome.packs?.map(p=>[p.name, p.action])).toEqual([ - ['agentic-runtime', 'failed'], + ['ai-sdr-core', 'failed'], ['reply-adapter', 'removed'], + ['agentic-runtime', 'removed'], ]); expect(outcome.status).toBe('partial'); - expect(outcome.hint).toContain('ai-sdr-core'); - // The core survives on disk and in the journal, because a pack that - // depends on it is still installed. expect(fs.existsSync(path.join(target, 'ai-sdr-core-skill', 'SKILL.md'))).toBe(true); expect(journal_entry('cursor', 'user', 'ai-sdr-core', env())?.version).toBe('0.1.0'); - expect(journal_entry('cursor', 'user', 'agentic-runtime', env())?.version).toBe('0.1.0'); expect(journal_entry('cursor', 'user', 'reply-adapter', env())).toBeUndefined(); }); - it('removes everything, in reverse order, when nothing fails', async()=>{ + it('removes everything when nothing fails', async()=>{ await run_flat(flat_opts('install', all)); const outcome = await run_flat(flat_opts('remove', all)); expect(outcome.packs?.map(p=>[p.name, p.action])).toEqual([ - ['agentic-runtime', 'removed'], - ['reply-adapter', 'removed'], ['ai-sdr-core', 'removed'], + ['reply-adapter', 'removed'], + ['agentic-runtime', 'removed'], ]); expect(outcome.status).toBe('ok'); expect(outcome.hint).toBeUndefined(); @@ -440,7 +384,6 @@ describe('run_flat project-scope entries belong to one repository', ()=>{ await run_flat({...flat_opts('install', core_only), scope: 'project'}); const outcome = await run_flat({ ...flat_opts('list', core_only), scope: 'project', cwd: other_project(), - clone: async()=>{ throw new Error('list must not clone'); }, }); expect(outcome.packs).toEqual([]); }); @@ -484,23 +427,11 @@ describe('run_flat shared project directories across hosts', ()=>{ const list_outcome = await run_flat({ ...flat_opts('list', core_only), scope: 'project', host: copilot(), - clone: async()=>{ throw new Error('list must not clone'); }, }); expect(list_outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); }); }); -// I5: a host with no directory configured for the requested scope (a native -// host under `user` scope) must be skipped, not crashed on with a TypeError -// from joining `undefined` into a path. -describe('run_flat with no skills directory for the scope', ()=>{ - it('reports skipped instead of crashing', async()=>{ - const outcome = await run_flat({...flat_opts('install', core_only), host: codex(), scope: 'user'}); - expect(outcome.status).toBe('skipped'); - expect(outcome.reason).toBe('no-skills-dir'); - }); -}); - // The journal records what we wrote; it is not evidence the files are still // there. A directory deleted by hand, moved by a host upgrade, or eaten by a // sync tool leaves the entry untouched, and every command used to believe it: @@ -532,7 +463,7 @@ describe('run_flat when the journal outlives the files', ()=>{ it('forgets an entry whose recorded files are outside the target root and already gone', async()=>{ const moved_away = path.join(root, 'old-location', 'ai-sdr-core-skill', 'SKILL.md'); record_pack('cursor', 'user', 'ai-sdr-core', { - version: '0У.1.0', ref: 'main', commit: 'deadbee', scope: 'user', + version: '0.1.0', scope: 'user', files: [moved_away], complete: true, installed_at: '2026-07-30T00:00:00.000Z', }, env()); @@ -546,41 +477,6 @@ describe('run_flat when the journal outlives the files', ()=>{ }); }); -// Minor, requested alongside the fixes above: clone_repo must not leave its -// temp directory behind on either failure path, and must check the exit code -// of `git rev-parse HEAD` rather than journaling an empty commit. -describe('clone_repo', ()=>{ - it('throws and removes its temp directory when `git clone` fails', async()=>{ - let captured_dir = ''; - const run: Runner = async(_bin, args)=>{ - if (args[0] === 'clone') - { - captured_dir = args[args.length - 1]; - return {code: 128, stdout: '', stderr: 'fatal: repository not found'}; - } - return {code: 0, stdout: 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef\n', stderr: ''}; - }; - await expect(clone_repo({ref: 'main', run, tmp_root: root})).rejects.toThrow('repository not found'); - expect(captured_dir).not.toBe(''); - expect(fs.existsSync(captured_dir)).toBe(false); - }); - - it('throws and removes its temp directory when `git rev-parse HEAD` fails', async()=>{ - let captured_dir = ''; - const run: Runner = async(_bin, args)=>{ - if (args[0] === 'clone') - { - captured_dir = args[args.length - 1]; - return {code: 0, stdout: '', stderr: ''}; - } - return {code: 1, stdout: '', stderr: 'fatal: not a git repository'}; - }; - await expect(clone_repo({ref: 'main', run, tmp_root: root})).rejects.toThrow('not a git repository'); - expect(captured_dir).not.toBe(''); - expect(fs.existsSync(captured_dir)).toBe(false); - }); -}); - // New Important from the re-review: a failed copy journaled under the target // version reads as installed, so the hint's own suggested fix ("re-run // install") silently does nothing. Journal_entry.complete distinguishes a @@ -589,7 +485,7 @@ describe('clone_repo', ()=>{ describe('run_flat incomplete installs', ()=>{ it('really re-copies a pack whose entry is marked incomplete, even at the target version', async()=>{ record_pack('cursor', 'user', 'ai-sdr-core', { - version: '0.1.0', ref: 'main', commit: 'deadbee', scope: 'user', + version: '0.1.0', scope: 'user', files: [], complete: false, installed_at: '2026-07-30T00:00:00.000Z', }, env()); @@ -628,7 +524,8 @@ describe('run_flat incomplete installs', ()=>{ throw new Error('simulated disk failure'); }); try { - const outcome = await run_flat(flat_opts('update', core_only)); + // A newer version, so the update copies. + const outcome = await run_flat(flat_opts('update', [{name: 'ai-sdr-core', version: '0.2.0'}])); expect(outcome.status).toBe('failed'); expect(outcome.reason).toBe('copy-failed'); } finally { @@ -650,13 +547,12 @@ describe('run_flat incomplete installs', ()=>{ it('does not report an incomplete pack as current in `list`', async()=>{ record_pack('cursor', 'user', 'ai-sdr-core', { - version: '0.1.0', ref: 'main', commit: 'deadbee', scope: 'user', + version: '0.1.0', scope: 'user', files: [], complete: false, installed_at: '2026-07-30T00:00:00.000Z', }, env()); const outcome = await run_flat({ ...flat_opts('list', core_only), - clone: async()=>{ throw new Error('list must not clone'); }, }); expect(outcome.packs?.map(p=>p.action)).not.toContain('current'); @@ -664,42 +560,31 @@ describe('run_flat incomplete installs', ()=>{ }); }); -// This adapter clones a *ref*, so a new commit on `main` can rewrite every -// file while the version stays 0.1.0. Reporting `current` for that is right — -// the version really did not move — but the outcome must still record that the -// bytes did, or a run that rewrote the user's files reads as a no-op. -describe('run_flat re-copy at an unchanged version', ()=>{ - // Same layout as fake_clone, different commit — as a second `update` a day - // later would see after the ref moved. - const clone_at = (commit: string)=>async()=>{ - await fake_clone(); - return {dir: clone_dir, commit}; - }; - - it('marks the pack refreshed when the ref moved but the version did not', async()=>{ - await run_flat({...flat_opts('install', core_only), clone: clone_at('aaaaaaa')}); - const outcome = await run_flat({...flat_opts('update', core_only), clone: clone_at('bbbbbbb')}); - - expect(outcome.packs).toEqual([{ - name: 'ai-sdr-core', action: 'current', version: '0.1.0', refreshed: true, - }]); - expect(journal_entry('cursor', 'user', 'ai-sdr-core', env())?.commit).toBe('bbbbbbb'); +// The version names the bytes: the package carries one copy of the pack per +// version, so a copy already at the version is current and not re-copied. +describe('run_flat at an unchanged version', ()=>{ + it('re-copies nothing on update when the copy is complete and at the version', async()=>{ + await run_flat(flat_opts('install', core_only)); + const file = path.join(home, '.cursor', 'skills', 'ai-sdr-core-skill', 'SKILL.md'); + fs.writeFileSync(file, 'edited'); + const outcome = await run_flat(flat_opts('update', core_only)); + expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); + expect(fs.readFileSync(file, 'utf8')).toBe('edited'); }); - it('does not mark it refreshed when the same commit is re-copied', async()=>{ - await run_flat({...flat_opts('install', core_only), clone: clone_at('aaaaaaa')}); - const outcome = await run_flat({...flat_opts('update', core_only), clone: clone_at('aaaaaaa')}); - - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); + it('reports an upgrade on --dry-run and writes nothing', async()=>{ + record_pack('cursor', 'user', 'ai-sdr-core', { + version: '0.0.9', scope: 'user', files: [], complete: true, installed_at: '2026-07-30T00:00:00.000Z', + }, env()); + const outcome = await run_flat({...flat_opts('update', core_only), dry_run: true}); + expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'upgraded', version: '0.1.0', from: '0.0.9'}]); + expect(fs.existsSync(path.join(home, '.cursor', 'skills', 'ai-sdr-core-skill'))).toBe(false); }); - it('never guesses on --dry-run, which does not clone', async()=>{ - await run_flat({...flat_opts('install', core_only), clone: clone_at('aaaaaaa')}); - const outcome = await run_flat({ - ...flat_opts('update', core_only), dry_run: true, - clone: async()=>{ throw new Error('a dry run must not clone'); }, - }); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); + it('counts from the version of the plugin it adopts, on update with no copy of its own', async()=>{ + const outcome = await run_flat({...flat_opts('update', core_only), adopt: {'ai-sdr-core': '0.0.5'}}); + expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'upgraded', version: '0.1.0', from: '0.0.5'}]); + expect(fs.existsSync(path.join(home, '.cursor', 'skills', 'ai-sdr-core-skill', 'SKILL.md'))).toBe(true); }); }); @@ -743,14 +628,14 @@ describe('run_flat abort status', ()=>{ const CASE_INSENSITIVE_FS = process.platform === 'win32' || process.platform === 'darwin'; describe('run_flat differently-cased journaled paths', ()=>{ - // `update`, not `install`: the entry is already complete at the target - // version, so `install` would skip the copy entirely without ever - // reaching the collision/ownership check these tests exercise. + // An earlier version's entry, so the run reaches the collision and + // ownership check these tests exercise: a complete copy at the target + // version would be current and skip the copy entirely. const seed_differently_cased_entry = (): string=>{ const target = path.join(home, '.cursor', 'skills'); const differently_cased = path.join(target, 'AI-SDR-CORE-SKILL', 'SKILL.MD'); record_pack('cursor', 'user', 'ai-sdr-core', { - version: '0.1.0', ref: 'main', commit: 'deadbee', scope: 'user', + version: '0.0.9', scope: 'user', files: [differently_cased], complete: true, installed_at: '2026-07-30T00:00:00.000Z', }, env()); fs.mkdirSync(path.join(target, 'ai-sdr-core-skill'), {recursive: true}); @@ -763,9 +648,7 @@ describe('run_flat differently-cased journaled paths', ()=>{ const outcome = await run_flat(flat_opts('update', core_only)); - // Re-copied from a fresh clone, but at the same version — so `current`, - // and the replaced content is proof the copy itself was not skipped. - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); + expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'upgraded', version: '0.1.0', from: '0.0.9'}]); expect(fs.readFileSync(path.join(target, 'ai-sdr-core-skill', 'SKILL.md'), 'utf8')) .not.toBe('old content'); }); @@ -818,7 +701,7 @@ describe('run_flat differently-cased journaled paths', ()=>{ const outcome = await run_flat({...flat_opts('update', core_only), canonicalise: ignoring_case}); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); + expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'upgraded', version: '0.1.0', from: '0.0.9'}]); expect(fs.readFileSync(path.join(target, 'ai-sdr-core-skill', 'SKILL.md'), 'utf8')) .not.toBe('old content'); }); @@ -836,7 +719,7 @@ describe('run_flat differently-cased journaled paths', ()=>{ fs.writeFileSync(real, 'old content'); const recorded = path.join(target, 'recorded-under-another-name', 'SKILL.md'); record_pack('cursor', 'user', 'ai-sdr-core', { - version: '0.1.0', ref: 'main', commit: 'deadbee', scope: 'user', + version: '0.1.0', scope: 'user', files: [recorded], complete: true, installed_at: '2026-07-30T00:00:00.000Z', }, env()); diff --git a/src/__tests__/skills/adapter-native.test.ts b/src/__tests__/skills/adapter-native.test.ts deleted file mode 100644 index 4d6fc54..0000000 --- a/src/__tests__/skills/adapter-native.test.ts +++ /dev/null @@ -1,376 +0,0 @@ -import {describe, it, expect, vi} from 'vitest'; -import {run_native, installed_versions} from '../../skills/adapter-native'; -import {host_by_id} from '../../skills/hosts'; -import {PACKS_FALLBACK, resolve_packs} from '../../skills/packs'; -import type {Detected_host} from '../../skills/detect'; -import type {Pack, Run_result, Runner} from '../../skills/types'; - -const ok = (stdout = ''): Run_result=>({code: 0, stdout, stderr: ''}); -const fail = (stderr = 'boom'): Run_result=>({code: 1, stdout: '', stderr}); - -const claude = (bin?: string): Detected_host=> - ({def: host_by_id('claude-code'), bin: bin ?? '/usr/bin/claude', config_dir: '/home/a/.claude'}); -const claude_no_bin = (): Detected_host=> - ({def: host_by_id('claude-code'), bin: undefined, config_dir: '/home/a/.claude'}); -const codex = (): Detected_host=> - ({def: host_by_id('codex'), bin: 'C:\\codex.exe', config_dir: 'C:\\Users\\a\\.codex'}); - -const all = resolve_packs([], PACKS_FALLBACK); -const core_only = resolve_packs(['core'], PACKS_FALLBACK); -const adapter = resolve_packs(['adapter'], PACKS_FALLBACK); - -// `claude plugin list --json` shape, trimmed to what the adapter reads. -const claude_list = (packs: {name: string; version: string}[]): string=>JSON.stringify({ - plugins: packs.map(p=>({name: p.name, marketplace: 'reply-skills', version: p.version, enabled: true})), -}); - -// Claude Code's *current* `plugin list --json` shape: a direct array of rows -// with an `id` of the form "@" instead of separate `name`/ -// `marketplace` fields. Captured for real from `claude plugin list --json` -// (Claude Code 2.1.220) on 2026-07-30, trimmed to the fields the adapter -// reads (`id`, `version`); the real output also carries `scope`, `enabled`, -// `installPath`, `installedAt`, `lastUpdated`, which installed_versions never -// looks at. Real row seen: {"id":"elastic-elasticsearch@elastic-agent-skills", -// "version":"0.2.4","scope":"user","enabled":true,...} — a plugin from a -// marketplace ('elastic-agent-skills') other than ours ('reply-skills'). -const claude_list_direct = (rows: {id: string; version: string}[]): string=>JSON.stringify( - rows.map(r=>({id: r.id, version: r.version, scope: 'user', enabled: true})), -); - -const runner_of = (results: Run_result[]): {run: Runner; calls: string[][]}=>{ - const calls: string[][] = []; - let i = 0; - const run: Runner = async(bin, args)=>{ - calls.push([bin, ...args]); - return results[i++] ?? ok(); - }; - return {run, calls}; -}; - -describe('installed_versions', ()=>{ - it('maps pack name to version from the host list', async()=>{ - const {run} = runner_of([ok(claude_list([{name: 'ai-sdr-core', version: '0.1.0'}]))]); - const result = await installed_versions(claude(), run); - expect(result).toEqual({ok: true, versions: {'ai-sdr-core': '0.1.0'}}); - }); - - it('returns failure when the host prints nothing usable', async()=>{ - const {run} = runner_of([ok('not json')]); - const result = await installed_versions(claude(), run); - expect(result).toEqual({ok: false}); - }); - - it('reads installed versions from the direct-array id shape Claude Code now returns', async()=>{ - const {run} = runner_of([ok(claude_list_direct([{id: 'ai-sdr-core@reply-skills', version: '0.1.0'}]))]); - const result = await installed_versions(claude(), run); - expect(result).toEqual({ok: true, versions: {'ai-sdr-core': '0.1.0'}}); - }); - - it('excludes a foreign-marketplace row in the direct-array id shape (real row, elastic-agent-skills)', async()=>{ - const {run} = runner_of([ok(claude_list_direct([ - {id: 'elastic-elasticsearch@elastic-agent-skills', version: '0.2.4'}, - ]))]); - const result = await installed_versions(claude(), run); - expect(result).toEqual({ok: true, versions: {}}); - }); -}); - -describe('run_native install', ()=>{ - it('registers the marketplace once, then installs core first', async()=>{ - const {run, calls} = runner_of([ok(), ok(claude_list([])), ok(), ok(), ok()]); - const outcome = await run_native({operation: 'install', host: claude(), packs: all, scope: 'user', run}); - expect(calls[0]).toEqual(['/usr/bin/claude', 'plugin', 'marketplace', 'add', 'reply-team/reply-skills']); - expect(calls.slice(2).map(c=>c[3])).toEqual([ - 'ai-sdr-core@reply-skills', 'reply-adapter@reply-skills', 'agentic-runtime@reply-skills', - ]); - expect(outcome.status).toBe('ok'); - expect(outcome.packs?.map(p=>p.action)).toEqual(['installed', 'installed', 'installed']); - }); - - it('passes the scope through', async()=>{ - const {run, calls} = runner_of([ok(), ok(claude_list([])), ok()]); - await run_native({operation: 'install', host: claude(), packs: core_only, scope: 'project', run}); - expect(calls[2]).toContain('--scope'); - expect(calls[2]).toContain('project'); - }); - - it('reports a pack already at the target version as current and runs no install', async()=>{ - const {run, calls} = runner_of([ok(), ok(claude_list([{name: 'ai-sdr-core', version: '0.1.0'}]))]); - const outcome = await run_native({operation: 'install', host: claude(), packs: core_only, scope: 'user', run}); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); - expect(calls).toHaveLength(2); - }); - - it('reports an older installed version as upgraded and records where it came from', async()=>{ - const {run} = runner_of([ok(), ok(claude_list([{name: 'ai-sdr-core', version: '0.0.9'}])), ok()]); - const outcome = await run_native({operation: 'install', host: claude(), packs: core_only, scope: 'user', run}); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'upgraded', version: '0.1.0', from: '0.0.9'}]); - }); - - it('never attempts a dependent pack when its dependency failed', async()=>{ - const {run, calls} = runner_of([ok(), ok(claude_list([])), fail('core exploded')]); - const outcome = await run_native({operation: 'install', host: claude(), packs: adapter, scope: 'user', run}); - expect(calls).toHaveLength(3); - expect(outcome.status).toBe('failed'); - expect(outcome.packs?.map(p=>[p.name, p.action])).toEqual([['ai-sdr-core', 'failed']]); - expect(outcome.hint).toContain('reply-adapter'); - }); - - it('is partial when an independent pack fails but the core succeeded', async()=>{ - const {run} = runner_of([ok(), ok(claude_list([])), ok(), fail(), ok()]); - const outcome = await run_native({operation: 'install', host: claude(), packs: all, scope: 'user', run}); - expect(outcome.status).toBe('partial'); - expect(outcome.packs?.map(p=>p.action)).toEqual(['installed', 'failed', 'installed']); - }); - - it('skips a host whose binary could not be resolved, with a fix', async()=>{ - const {run, calls} = runner_of([]); - const outcome = await run_native({operation: 'install', host: claude_no_bin(), packs: all, scope: 'user', run}); - expect(outcome.status).toBe('skipped'); - expect(outcome.reason).toBe('cli-not-resolved'); - expect(outcome.hint).toContain('PATH'); - expect(calls).toEqual([]); - }); - - it('fails the host when marketplace registration fails', async()=>{ - const {run, calls} = runner_of([fail('no network')]); - const outcome = await run_native({operation: 'install', host: claude(), packs: all, scope: 'user', run}); - expect(outcome.status).toBe('failed'); - expect(outcome.detail).toContain('no network'); - expect(calls).toHaveLength(1); - }); - - it('uses the Codex verb spelling', async()=>{ - const {run, calls} = runner_of([ok('{}'), ok('{"installed":[]}'), ok('{}')]); - await run_native({operation: 'install', host: codex(), packs: core_only, scope: 'user', run}); - expect(calls[0]).toEqual(['C:\\codex.exe', 'plugin', 'marketplace', 'add', 'reply-team/reply-skills', '--json']); - expect(calls[2]).toEqual(['C:\\codex.exe', 'plugin', 'add', 'ai-sdr-core@reply-skills', '--json']); - }); - - it('reads installed versions from the Codex list shape', async()=>{ - const listing = JSON.stringify({installed: [{name: 'ai-sdr-core', version: '0.1.0', marketplaceName: 'reply-skills'}]}); - const {run} = runner_of([ok('{}'), ok(listing)]); - const outcome = await run_native({operation: 'install', host: codex(), packs: core_only, scope: 'user', run}); - expect(outcome.packs?.[0].action).toBe('current'); - }); - - it('changes nothing on --dry-run but still reports the plan', async()=>{ - const {run, calls} = runner_of([ok(claude_list([]))]); - const outcome = await run_native({ - operation: 'install', host: claude(), packs: core_only, scope: 'user', run, dry_run: true, - }); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'installed', version: '0.1.0'}]); - expect(calls.map(c=>c.slice(1, 3))).toEqual([['plugin', 'list']]); - }); -}); - -describe('run_native remove', ()=>{ - it('removes dependents before their dependency', async()=>{ - const installed = claude_list([ - {name: 'ai-sdr-core', version: '0.1.0'}, {name: 'reply-adapter', version: '0.1.0'}, - ]); - const {run, calls} = runner_of([ok(installed), ok(), ok()]); - const outcome = await run_native({operation: 'remove', host: claude(), packs: adapter, scope: 'user', run}); - expect(calls.slice(1).map(c=>c[3])).toEqual(['reply-adapter@reply-skills', 'ai-sdr-core@reply-skills']); - expect(outcome.packs?.map(p=>p.action)).toEqual(['removed', 'removed']); - }); - - it('ignores a pack that is not installed', async()=>{ - const {run, calls} = runner_of([ok(claude_list([]))]); - const outcome = await run_native({operation: 'remove', host: claude(), packs: core_only, scope: 'user', run}); - expect(outcome.packs).toEqual([]); - expect(calls).toHaveLength(1); - }); - - // C1 (final review): reverse order alone is not enough. A failed - // `plugin uninstall reply-adapter` followed by a successful - // `plugin uninstall ai-sdr-core` leaves the host with an adapter and no - // core — the state this installer exists to prevent. - it('never removes a dependency once removing a pack that depends on it failed', async()=>{ - const installed = claude_list([ - {name: 'ai-sdr-core', version: '0.1.0'}, {name: 'reply-adapter', version: '0.1.0'}, - ]); - const {run, calls} = runner_of([ok(installed), fail('file is locked')]); - const outcome = await run_native({operation: 'remove', host: claude(), packs: adapter, scope: 'user', run}); - // The listing, then the dependent's uninstall — and nothing else. - expect(calls.slice(1).map(c=>c[3])).toEqual(['reply-adapter@reply-skills']); - expect(outcome.packs).toEqual([ - {name: 'reply-adapter', action: 'failed', detail: 'file is locked'}, - ]); - expect(outcome.status).toBe('failed'); - expect(outcome.hint).toContain('ai-sdr-core'); - }); - - it('propagates the block down a dependency chain when the outermost removal failed', async()=>{ - const chain_a: Pack = {name: 'chainA', display_name: 'A', version: '1.0.0', description: '', dependencies: []}; - const chain_b: Pack = {name: 'chainB', display_name: 'B', version: '1.0.0', description: '', dependencies: ['chainA']}; - const chain_c: Pack = {name: 'chainC', display_name: 'C', version: '1.0.0', description: '', dependencies: ['chainB']}; - const listing = JSON.stringify({plugins: [chain_a, chain_b, chain_c].map(p=> - ({name: p.name, marketplace: 'reply-skills', version: p.version}))}); - const {run, calls} = runner_of([ok(listing), fail('C is locked')]); - const outcome = await run_native({ - operation: 'remove', host: claude(), packs: [chain_a, chain_b, chain_c], scope: 'user', run, - }); - expect(calls.filter(c=>c[2] === 'uninstall').map(c=>c[3])).toEqual(['chainC@reply-skills']); - expect(outcome.hint).toContain('chainB'); - expect(outcome.hint).toContain('chainA'); - }); - - it('reports no hint and removes everything when nothing fails', async()=>{ - const installed = claude_list([ - {name: 'ai-sdr-core', version: '0.1.0'}, {name: 'reply-adapter', version: '0.1.0'}, - ]); - const {run} = runner_of([ok(installed), ok(), ok()]); - const outcome = await run_native({operation: 'remove', host: claude(), packs: adapter, scope: 'user', run}); - expect(outcome.packs?.map(p=>p.action)).toEqual(['removed', 'removed']); - expect(outcome.status).toBe('ok'); - expect(outcome.hint).toBeUndefined(); - }); -}); - -describe('run_native list and update', ()=>{ - it('list reports installed versions without mutating anything', async()=>{ - const {run, calls} = runner_of([ok(claude_list([{name: 'ai-sdr-core', version: '0.0.9'}]))]); - const outcome = await run_native({operation: 'list', host: claude(), packs: all, scope: 'user', run}); - expect(calls).toHaveLength(1); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'upgraded', version: '0.1.0', from: '0.0.9'}]); - }); - - it('update runs the host update verb only for installed packs', async()=>{ - const {run, calls} = runner_of([ok(), ok(claude_list([{name: 'ai-sdr-core', version: '0.0.9'}])), ok()]); - const outcome = await run_native({operation: 'update', host: claude(), packs: all, scope: 'user', run}); - expect(calls[0]).toEqual(['/usr/bin/claude', 'plugin', 'marketplace', 'add', 'reply-team/reply-skills']); - expect(calls[2]).toEqual(['/usr/bin/claude', 'plugin', 'update', 'ai-sdr-core@reply-skills']); - expect(outcome.packs?.map(p=>p.name)).toEqual(['ai-sdr-core']); - }); - - it('update on Codex fires marketplace upgrade once for all installed packs', async()=>{ - const listing_before = JSON.stringify({installed: [ - {name: 'ai-sdr-core', version: '0.0.9', marketplaceName: 'reply-skills'}, - {name: 'reply-adapter', version: '0.0.8', marketplaceName: 'reply-skills'}, - {name: 'agentic-runtime', version: '0.0.7', marketplaceName: 'reply-skills'}, - ]}); - const listing_after = JSON.stringify({installed: [ - {name: 'ai-sdr-core', version: '0.1.0', marketplaceName: 'reply-skills'}, - {name: 'reply-adapter', version: '0.1.0', marketplaceName: 'reply-skills'}, - {name: 'agentic-runtime', version: '0.1.0', marketplaceName: 'reply-skills'}, - ]}); - const {run, calls} = runner_of([ok('{}'), ok(listing_before), ok('{}'), ok(listing_after)]); - const outcome = await run_native({operation: 'update', host: codex(), packs: all, scope: 'user', run}); - expect(calls.filter(c=>c[1] === 'plugin' && c[2] === 'marketplace' && c[3] === 'upgrade')).toHaveLength(1); - expect(outcome.packs?.map(p=>[p.name, p.action])).toEqual([['ai-sdr-core', 'upgraded'], ['reply-adapter', 'upgraded'], ['agentic-runtime', 'upgraded']]); - }); - - // I3 (final review): the marketplace path exits 0 whether or not anything - // moved, and used to hardcode `upgraded`. On a machine with Claude Code - // and Codex that printed "already current" and "updated" for one fact. - it('update on Codex reports current when the marketplace upgrade moved nothing', async()=>{ - const listing = JSON.stringify({installed: [ - {name: 'ai-sdr-core', version: '0.1.0', marketplaceName: 'reply-skills'}, - {name: 'reply-adapter', version: '0.1.0', marketplaceName: 'reply-skills'}, - ]}); - // Same versions before and after — the upgrade succeeded, nothing moved. - const {run} = runner_of([ok('{}'), ok(listing), ok('{}'), ok(listing)]); - const outcome = await run_native({operation: 'update', host: codex(), packs: adapter, scope: 'user', run}); - expect(outcome.packs).toEqual([ - {name: 'ai-sdr-core', action: 'current', version: '0.1.0'}, - {name: 'reply-adapter', action: 'current', version: '0.1.0'}, - ]); - }); - - it('update on Codex reports current on --dry-run when every pack is already at the target version', async()=>{ - const listing = JSON.stringify({installed: [ - {name: 'ai-sdr-core', version: '0.1.0', marketplaceName: 'reply-skills'}, - ]}); - // A dry run registers no marketplace, so the listing is the first call. - const {run} = runner_of([ok(listing)]); - const outcome = await run_native({ - operation: 'update', host: codex(), packs: core_only, scope: 'user', run, dry_run: true, - }); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); - }); - - it('update reports current when the host update verb exits 0 without moving the version', async()=>{ - // Registry target 0.1.0, host on 0.0.9, `plugin update` succeeds but - // the post-update listing still says 0.0.9 — nothing changed, so the - // report must not claim an upgrade happened. - const stale = claude_list([{name: 'ai-sdr-core', version: '0.0.9'}]); - const {run} = runner_of([ok(), ok(stale), ok(), ok(stale)]); - const outcome = await run_native({operation: 'update', host: claude(), packs: core_only, scope: 'user', run}); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.0.9'}]); - }); - - it('update reports current for pack already at target version', async()=>{ - const {run, calls} = runner_of([ok(), ok(claude_list([{name: 'ai-sdr-core', version: '0.1.0'}])), ok(claude_list([{name: 'ai-sdr-core', version: '0.1.0'}]))]); - const outcome = await run_native({operation: 'update', host: claude(), packs: core_only, scope: 'user', run}); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}]); - expect(calls).toHaveLength(2); - }); - - it('failed list on remove returns failed status with list-failed reason', async()=>{ - const {run, calls} = runner_of([fail('network error')]); - const outcome = await run_native({operation: 'remove', host: claude(), packs: core_only, scope: 'user', run}); - expect(outcome.status).toBe('failed'); - expect(outcome.reason).toBe('list-failed'); - expect(outcome.detail).toContain('network error'); - expect(calls).toHaveLength(1); - }); - - it('failed list on update returns failed status with list-failed reason', async()=>{ - const {run, calls} = runner_of([ok(), fail('network error')]); - const outcome = await run_native({operation: 'update', host: claude(), packs: core_only, scope: 'user', run}); - expect(outcome.status).toBe('failed'); - expect(outcome.reason).toBe('list-failed'); - expect(calls).toHaveLength(2); - }); - - it('failed list on list returns failed status with list-failed reason', async()=>{ - const {run, calls} = runner_of([fail('network error')]); - const outcome = await run_native({operation: 'list', host: claude(), packs: all, scope: 'user', run}); - expect(outcome.status).toBe('failed'); - expect(outcome.reason).toBe('list-failed'); - expect(calls).toHaveLength(1); - }); - - it('plugin from different marketplace is treated as installed, not current', async()=>{ - const other_marketplace_list = JSON.stringify({plugins: [{name: 'ai-sdr-core', version: '0.1.0', marketplace: 'someone-else', enabled: true}]}); - const {run} = runner_of([ok(), ok(other_marketplace_list)]); - const outcome = await run_native({operation: 'install', host: claude(), packs: core_only, scope: 'user', run}); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'installed', version: '0.1.0'}]); - }); - - it('same pack name from a different marketplace, in the direct-array id shape, is treated as installed, not current', async()=>{ - // Same pack name as ours but a foreign marketplace suffix on the id — - // marketplace filtering must still apply in the new shape, not just the - // old {plugins:[...]} envelope. - const other_marketplace_list = claude_list_direct([{id: 'ai-sdr-core@someone-else', version: '0.1.0'}]); - const {run} = runner_of([ok(), ok(other_marketplace_list)]); - const outcome = await run_native({operation: 'install', host: claude(), packs: core_only, scope: 'user', run}); - expect(outcome.packs).toEqual([{name: 'ai-sdr-core', action: 'installed', version: '0.1.0'}]); - }); - - it('transitive dependency chain: A fails, B depends on A, C depends on B', async()=>{ - // Build a synthetic three-pack chain: chainA -> chainB -> chainC - const chainA: Pack = {name: 'chainA', display_name: 'Chain A', version: '1.0.0', description: '', dependencies: []}; - const chainB: Pack = {name: 'chainB', display_name: 'Chain B', version: '1.0.0', description: '', dependencies: ['chainA']}; - const chainC: Pack = {name: 'chainC', display_name: 'Chain C', version: '1.0.0', description: '', dependencies: ['chainB']}; - const chain_packs = [chainA, chainB, chainC]; - const {run, calls} = runner_of([ok(), ok(claude_list([])), fail('A failed')]); - const outcome = await run_native({operation: 'install', host: claude(), packs: chain_packs, scope: 'user', run}); - // Should have calls: marketplace add, list json, chainA install. No chainB or chainC install. - const install_calls = calls.filter(c=>c[2] === 'install'); - expect(install_calls).toHaveLength(1); - expect(install_calls[0][3]).toEqual('chainA@reply-skills'); - expect(outcome.status).toBe('failed'); - expect(outcome.hint).toContain('chainB'); - expect(outcome.hint).toContain('chainC'); - }); - - it('failure that blocks nothing produces no hint', async()=>{ - // reply-adapter fails but nothing depends on it, so no hint - const {run} = runner_of([ok(), ok(claude_list([])), ok(), fail(), ok()]); - const outcome = await run_native({operation: 'install', host: claude(), packs: all, scope: 'user', run}); - expect(outcome.status).toBe('partial'); - expect(outcome.hint).toBeUndefined(); - }); -}); diff --git a/src/__tests__/skills/hosts.test.ts b/src/__tests__/skills/hosts.test.ts index d0843c5..b8e700d 100644 --- a/src/__tests__/skills/hosts.test.ts +++ b/src/__tests__/skills/hosts.test.ts @@ -23,24 +23,26 @@ describe('host registry', ()=>{ expect(HOSTS.filter(h=>!h.needs_new_session).map(h=>h.id)).toEqual(['antigravity']); }); - it('gives every native host a CLI and every flat host a skills directory', ()=>{ + it('gives every host a user and a project skills directory, and a binary to any host with a plugin CLI', ()=>{ for (const host of HOSTS) { - if (host.kind === 'native-plugin') + expect(host.kind, host.id).toBe('flat-skills-dir'); + expect(host.user_skills_dir, host.id).toBeTruthy(); + expect(host.project_skills_dir, host.id).toBeTruthy(); + if (host.plugin_cli) { - expect(host.cli, host.id).toBeDefined(); expect(host.binaries.length, host.id).toBeGreaterThan(0); } - else - { - expect(host.user_skills_dir, host.id).toBeDefined(); - } - // Every host needs a project target: flat hosts use theirs directly, - // native hosts fall back to it when --project cannot be expressed. - expect(host.project_skills_dir, host.id).toBeDefined(); } }); - + + it('copies into the directories Claude Code and Codex read skills from', ()=>{ + expect(host_by_id('claude-code').user_skills_dir).toBe(path.join('.claude', 'skills')); + expect(host_by_id('claude-code').project_skills_dir).toBe(path.join('.claude', 'skills')); + expect(host_by_id('codex').user_skills_dir).toBe(path.join('.agents', 'skills')); + expect(host_by_id('codex').project_skills_dir).toBe(path.join('.agents', 'skills')); + }); + it('never lets one host\'s config directory contain another\'s', ()=>{ const dirs = HOSTS.flatMap(h=>h.config_dirs.map(dir=>({id: h.id, dir}))); for (const a of dirs) @@ -53,23 +55,24 @@ describe('host registry', ()=>{ } }); - it('builds Claude Code argument vectors', ()=>{ - const cli = host_by_id('claude-code').cli!; - expect(cli.marketplace_add('reply-team/reply-skills')) - .toEqual(['plugin', 'marketplace', 'add', 'reply-team/reply-skills']); - expect(cli.install('ai-sdr-core', 'reply-skills', 'user')) - .toEqual(['plugin', 'install', 'ai-sdr-core@reply-skills', '--scope', 'user']); - expect(cli.remove('ai-sdr-core', 'reply-skills')).toEqual(['plugin', 'uninstall', 'ai-sdr-core@reply-skills']); + it('builds Claude Code argument vectors, user scope being its default', ()=>{ + const cli = host_by_id('claude-code').plugin_cli!; expect(cli.list_json()).toEqual(['plugin', 'list', '--json']); + expect(cli.remove('reply-adapter@reply-skills', 'user')) + .toEqual(['plugin', 'uninstall', 'reply-adapter@reply-skills']); + expect(cli.remove('reply-adapter@reply-skills', 'project')) + .toEqual(['plugin', 'uninstall', 'reply-adapter@reply-skills', '--scope', 'project']); }); it('builds Codex argument vectors, which spell the verbs differently', ()=>{ - const cli = host_by_id('codex').cli!; - expect(cli.marketplace_add('reply-team/reply-skills')) - .toEqual(['plugin', 'marketplace', 'add', 'reply-team/reply-skills', '--json']); - expect(cli.install('ai-sdr-core', 'reply-skills', 'user')) - .toEqual(['plugin', 'add', 'ai-sdr-core@reply-skills', '--json']); - expect(cli.remove('ai-sdr-core', 'reply-skills')).toEqual(['plugin', 'remove', 'ai-sdr-core@reply-skills', '--json']); + const cli = host_by_id('codex').plugin_cli!; + expect(cli.list_json()).toEqual(['plugin', 'list', '--json']); + expect(cli.remove('reply-adapter@reply-skills', 'user')) + .toEqual(['plugin', 'remove', 'reply-adapter@reply-skills', '--json']); + }); + + it('asks no other host for plugins', ()=>{ + expect(HOSTS.filter(h=>h.plugin_cli).map(h=>h.id)).toEqual(['claude-code', 'codex']); }); it('knows Codex ships off PATH on Windows', ()=>{ diff --git a/src/__tests__/skills/journal.test.ts b/src/__tests__/skills/journal.test.ts index ece42a7..6d34c20 100644 --- a/src/__tests__/skills/journal.test.ts +++ b/src/__tests__/skills/journal.test.ts @@ -10,7 +10,7 @@ let dir: string; const env = ()=>({REPLY_CONFIG_DIR: dir}); const entry = (version = '0.1.0', files: string[] = ['a/SKILL.md']): Journal_entry=>({ - version, ref: 'main', commit: 'abc1234', scope: 'user', files, complete: true, installed_at: '2026-07-30T00:00:00.000Z', + version, scope: 'user', files, complete: true, installed_at: '2026-07-30T00:00:00.000Z', }); beforeEach(()=>{ @@ -31,6 +31,20 @@ describe('skills journal', ()=>{ expect(journal_entry('cursor', 'user', 'ai-sdr-core', env())).toEqual(entry()); }); + it('reads an entry an earlier version wrote, with the ref and commit it copied from', ()=>{ + const earlier = { + version: 1, + hosts: {cursor: {user: {'reply-adapter': { + version: '0.1.0', ref: 'main', commit: 'abc1234', scope: 'user', + files: ['a/SKILL.md'], complete: true, installed_at: '2026-07-30T00:00:00.000Z', + }}}}, + }; + fs.writeFileSync(skills_file(env()), JSON.stringify(earlier)); + expect(journal_entry('cursor', 'user', 'reply-adapter', env())).toMatchObject({ + version: '0.1.0', commit: 'abc1234', files: ['a/SKILL.md'], complete: true, + }); + }); + it('writes the journal next to the other config files', ()=>{ record_pack('cursor', 'user', 'ai-sdr-core', entry(), env()); expect(fs.existsSync(skills_file(env()))).toBe(true); diff --git a/src/__tests__/skills/orchestrate.test.ts b/src/__tests__/skills/orchestrate.test.ts index be6749a..225601d 100644 --- a/src/__tests__/skills/orchestrate.test.ts +++ b/src/__tests__/skills/orchestrate.test.ts @@ -1,7 +1,8 @@ -import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest'; +import {describe, it, expect, beforeEach, afterEach} from 'vitest'; import fs from 'fs'; import os from 'os'; import path from 'path'; +import {cli_version} from '../../config'; import {HOSTS} from '../../skills/hosts'; import {record_pack} from '../../skills/journal'; import {run_skills} from '../../skills/orchestrate'; @@ -13,7 +14,7 @@ import {UsageError} from '../../utils/errors'; let root: string; let home: string; -// A machine with Claude Code (native, on PATH) and Cursor (flat). +// A machine with Claude Code (its CLI on PATH) and Cursor. const detect_deps = (): Detect_deps=>({ home, platform: 'linux', @@ -22,26 +23,19 @@ const detect_deps = (): Detect_deps=>({ glob_first: ()=>undefined, }); +// Plugin rows for `claude plugin list --json`, in its direct-array shape. +let listed: {id: string; version: string; scope: string}[] = []; const calls: string[][] = []; const run: Runner = async(bin, args)=>{ calls.push([bin, ...args]); if (args.includes('list')) { - return {code: 0, stdout: JSON.stringify({plugins: []}), stderr: ''}; + return {code: 0, stdout: JSON.stringify(listed), stderr: ''}; } return {code: 0, stdout: '', stderr: ''}; }; -const fake_clone = async()=>{ - const dir = fs.mkdtempSync(path.join(root, 'clone-')); - for (const name of ['ai-sdr-core', 'reply-adapter', 'agentic-runtime']) - { - const skills = path.join(dir, 'plugins', name, 'skills', `${name}-skill`); - fs.mkdirSync(skills, {recursive: true}); - fs.writeFileSync(path.join(skills, 'SKILL.md'), `---\nname: ${name}-skill\ndescription: d\n---\n`); - } - return {dir, commit: 'cafe123'}; -}; +const env = ()=>({REPLY_CONFIG_DIR: path.join(root, 'config')}); const opts = (over: Record = {})=>({ operation: 'install' as const, @@ -51,18 +45,18 @@ const opts = (over: Record = {})=>({ deps: { detect: detect_deps(), run, - clone: fake_clone, home, cwd: path.join(root, 'project'), - tmp_root: root, - env: {REPLY_CONFIG_DIR: path.join(root, 'config')}, - fetch_impl: vi.fn().mockRejectedValue(new TypeError('offline')) as unknown as typeof fetch, + env: env(), }, ...over, }); +const skill_file = (...dir: string[])=>path.join(...dir, 'reply-api', 'SKILL.md'); + beforeEach(()=>{ calls.length = 0; + listed = []; root = fs.mkdtempSync(path.join(os.tmpdir(), 'reply-orch-')); home = path.join(root, 'home'); fs.mkdirSync(path.join(home, '.claude'), {recursive: true}); @@ -73,22 +67,21 @@ afterEach(()=>{ }); describe('run_skills', ()=>{ - it('installs all three packs into both host classes', async()=>{ + it('copies the pack into every detected host and asks Claude Code only for its plugin list', async()=>{ const report = await run_skills(opts()); expect(report.hosts.map(h=>h.host)).toEqual(['claude-code', 'cursor']); - expect(report.resolved).toEqual(['ai-sdr-core', 'reply-adapter', 'agentic-runtime']); + expect(report.resolved).toEqual(['reply-adapter']); expect(report.hosts.every(h=>h.status === 'ok')).toBe(true); expect(report.summary).toEqual({installed: 2, skipped: 0, failed: 0}); - // Native host went through its own CLI… - expect(calls[0]).toEqual(['/usr/bin/claude', 'plugin', 'marketplace', 'add', 'reply-team/reply-skills']); - // …and the flat host got real files. - expect(fs.existsSync(path.join(home, '.cursor', 'skills', 'ai-sdr-core-skill', 'SKILL.md'))).toBe(true); + expect(calls).toEqual([['/usr/bin/claude', 'plugin', 'list', '--json']]); + expect(fs.existsSync(skill_file(home, '.claude', 'skills'))).toBe(true); + expect(fs.existsSync(skill_file(home, '.cursor', 'skills'))).toBe(true); }); - it('records requested separately from resolved on a selective install', async()=>{ + it('reports the pack under its canonical name when asked for by its alias', async()=>{ const report = await run_skills(opts({requested: ['adapter']})); expect(report.requested).toEqual(['reply-adapter']); - expect(report.resolved).toEqual(['ai-sdr-core', 'reply-adapter']); + expect(report.resolved).toEqual(['reply-adapter']); }); it('narrows to one host with --agent', async()=>{ @@ -112,18 +105,20 @@ describe('run_skills', ()=>{ await expect(run_skills(opts({requested: ['ghost']}))).rejects.toThrow(UsageError); }); - it('keeps a native host on its own CLI under --project when it can express project scope', async()=>{ + it('copies into the repository under --project, and removes an old project-scope plugin in that scope', async()=>{ + listed = [ + {id: 'reply-adapter@reply-skills', version: '0.3.0', scope: 'project'}, + {id: 'reply-adapter@reply-skills', version: '0.3.0', scope: 'user'}, + ]; const report = await run_skills(opts({agents: ['claude-code'], project: true})); expect(report.hosts[0].scope).toBe('project'); - // Claude Code expresses project scope natively, so it stays native. - expect(calls.some(c=>c.includes('--scope') && c.includes('project'))).toBe(true); + expect(fs.existsSync(skill_file(root, 'project', '.claude', 'skills'))).toBe(true); + expect(calls.filter(c=>c[2] === 'uninstall')).toEqual([ + ['/usr/bin/claude', 'plugin', 'uninstall', 'reply-adapter@reply-skills', '--scope', 'project'], + ]); }); - it('routes Codex through the flat adapter under --project, and reports scope honestly', async()=>{ - // Codex's plugin mechanism is user-scoped only, so a project-scoped run - // must fall back to the flat adapter (.agents/skills), never run_native, - // and the outcome must still say 'project' rather than silently - // dropping the request back to 'user'. + it('copies Codex into .agents/skills under --project and never asks its user-scoped plugin CLI', async()=>{ fs.mkdirSync(path.join(home, '.codex'), {recursive: true}); const base_deps = opts().deps; const report = await run_skills(opts({ @@ -141,51 +136,48 @@ describe('run_skills', ()=>{ }, })); expect(report.hosts.map(h=>h.host)).toEqual(['codex']); - expect(report.hosts[0].kind).toBe('flat-skills-dir'); expect(report.hosts[0].scope).toBe('project'); - // No native CLI call ever reached the Codex binary. expect(calls.some(c=>c[0] === '/usr/bin/codex')).toBe(false); - expect(fs.existsSync( - path.join(root, 'project', '.agents', 'skills', 'ai-sdr-core-skill', 'SKILL.md'), - )).toBe(true); + expect(fs.existsSync(skill_file(root, 'project', '.agents', 'skills'))).toBe(true); }); - it('reports the source ref and the resolved commit for flat installs', async()=>{ + it('reports the version it copied as the source', async()=>{ const report = await run_skills(opts({agents: ['cursor']})); - expect(report.source).toEqual({repo: 'reply-team/reply-skills', ref: 'main', commit: 'cafe123'}); + expect(report.source).toEqual({version: cli_version()}); }); - it('changes nothing on --dry-run', async()=>{ + it('changes nothing on --dry-run, the old plugin included', async()=>{ + listed = [{id: 'reply-adapter@reply-skills', version: '0.3.0', scope: 'user'}]; const report = await run_skills(opts({dry_run: true})); - expect(fs.existsSync(path.join(home, '.cursor', 'skills', 'ai-sdr-core-skill'))).toBe(false); - expect(calls.some(c=>c.includes('install'))).toBe(false); + expect(fs.existsSync(path.join(home, '.cursor', 'skills', 'reply-api'))).toBe(false); + expect(fs.existsSync(path.join(home, '.claude', 'skills', 'reply-api'))).toBe(false); + expect(calls.some(c=>c.includes('uninstall'))).toBe(false); expect(report.hosts.every(h=>h.status === 'ok')).toBe(true); + expect(report.hosts[0].old_plugin).toEqual({id: 'reply-adapter@reply-skills', action: 'removed'}); }); - it('refuses to remove a pack that another pack depends on', async()=>{ - await run_skills(opts({agents: ['cursor']})); - await expect(run_skills(opts({operation: 'remove', requested: ['core'], agents: ['cursor']}))) - .rejects.toThrow(UsageError); - }); - - it('allows removing a pack nothing depends on', async()=>{ + it('removes the copy when remove is given no pack', async()=>{ await run_skills(opts({agents: ['cursor']})); - const report = await run_skills(opts({operation: 'remove', requested: ['runtime'], agents: ['cursor']})); - expect(report.hosts[0].packs?.map(p=>p.name)).toEqual(['agentic-runtime']); + const report = await run_skills(opts({operation: 'remove', agents: ['cursor']})); + expect(report.hosts[0].packs).toEqual([{name: 'reply-adapter', action: 'removed', version: cli_version()}]); + expect(fs.existsSync(path.join(home, '.cursor', 'skills', 'reply-api'))).toBe(false); }); - it('removes everything when remove is given no pack', async()=>{ - await run_skills(opts({agents: ['cursor']})); - const report = await run_skills(opts({operation: 'remove', agents: ['cursor']})); - expect(report.hosts[0].packs?.map(p=>p.action)).toEqual(['removed', 'removed', 'removed']); - expect(fs.existsSync(path.join(home, '.cursor', 'skills', 'ai-sdr-core-skill'))).toBe(false); + it('copies anyway, and says so, when the host cannot list its plugins', async()=>{ + const failing_list: Runner = async(bin, args)=>{ + calls.push([bin, ...args]); + return {code: 1, stdout: '', stderr: 'not signed in'}; + }; + const report = await run_skills(opts({agents: ['claude-code'], deps: {...opts().deps, run: failing_list}})); + expect(report.hosts[0].status).toBe('ok'); + expect(fs.existsSync(skill_file(home, '.claude', 'skills'))).toBe(true); + expect(report.hosts[0].hint).toContain('not signed in'); + expect(calls.some(c=>c.includes('uninstall'))).toBe(false); }); it('keeps other hosts working when one host throws unexpectedly', async()=>{ - // run_native has no try/catch of its own around its process calls, so - // an injected Runner that rejects escapes it — exactly the kind of - // surprise (a journal write racing an antivirus scanner, a flaky - // network call) the orchestrator itself must contain per host. + // An injected Runner that rejects escapes the plugin listing — the kind + // of surprise run_skills itself must contain per host. const flaky_run: Runner = async(bin, args)=>{ if (bin === '/usr/bin/claude') { @@ -201,69 +193,35 @@ describe('run_skills', ()=>{ expect(report.hosts[0]).toEqual(expect.objectContaining({ host: 'claude-code', status: 'failed', reason: 'host-error', detail: 'ECONNRESET', })); - // The second host was never touched by the first host's failure. expect(report.hosts[1].status).toBe('ok'); - expect(fs.existsSync(path.join(home, '.cursor', 'skills', 'ai-sdr-core-skill', 'SKILL.md'))).toBe(true); - }); - - it('reports no commit when nothing was cloned this run (native-only)', async()=>{ - const report = await run_skills(opts({agents: ['claude-code']})); - expect(report.source).toEqual({repo: 'reply-team/reply-skills', ref: 'main'}); + expect(fs.existsSync(skill_file(home, '.cursor', 'skills'))).toBe(true); }); - // I3 (final review): `update` was never exercised through run_skills at - // all, which is exactly where the disagreement showed — one native host - // and one flat host answering "already at the target version" two - // different ways in a single report. - it('reports current from both adapters when update finds every pack already at the target version', async()=>{ - // The host reports all three packs installed at the registry version, - // so neither adapter has anything to move. - const installed_run: Runner = async(bin, args)=>{ - calls.push([bin, ...args]); - if (args.includes('list')) - { - return { - code: 0, - stdout: JSON.stringify({plugins: ['ai-sdr-core', 'reply-adapter', 'agentic-runtime'] - .map(name=>({name, marketplace: 'reply-skills', version: '0.1.0'}))}), - stderr: '', - }; - } - return {code: 0, stdout: '', stderr: ''}; - }; - const with_run = (): Record=>({...opts().deps, run: installed_run}); - - await run_skills(opts({deps: with_run()})); - const report = await run_skills(opts({operation: 'update', deps: with_run()})); + it('reports current on every host when update finds the copy already at this version', async()=>{ + await run_skills(opts()); + const report = await run_skills(opts({operation: 'update'})); expect(report.hosts.map(h=>h.host)).toEqual(['claude-code', 'cursor']); for (const host of report.hosts) { - expect(host.packs?.map(p=>[p.name, p.action])).toEqual([ - ['ai-sdr-core', 'current'], - ['reply-adapter', 'current'], - ['agentic-runtime', 'current'], - ]); + expect(host.packs?.map(p=>[p.name, p.action])).toEqual([['reply-adapter', 'current']]); } // Nothing changed, so the "start a new session" advice must not fire. expect(human_lines(report).join('\n')).not.toMatch(/new session/i); }); - // The flat adapter clones a ref, so `update` can rewrite every file while - // the version stays 0.1.0. That still reports `current` — the version did - // not move — but the user must reload to pick the new files up. - it('still advises a new session when update rewrote files at an unchanged version', async()=>{ - const clone_at = (commit: string)=>async()=>{ - const {dir} = await fake_clone(); - return {dir, commit}; - }; - await run_skills(opts({agents: ['cursor'], deps: {...opts().deps, clone: clone_at('aaaaaaa')}})); - const report = await run_skills(opts({ - operation: 'update', agents: ['cursor'], - deps: {...opts().deps, clone: clone_at('bbbbbbb')}, - })); - - expect(report.hosts[0].packs?.map(p=>p.action)).toEqual(['current', 'current', 'current']); + // A copy that never finished is repaired at an unchanged version: still + // `current`, but the files moved and the user must reload. + it('still advises a new session when update repaired a copy at an unchanged version', async()=>{ + record_pack('cursor', 'user', 'reply-adapter', { + version: cli_version(), scope: 'user', files: [], complete: false, + installed_at: '2026-07-30T00:00:00.000Z', + }, env()); + const report = await run_skills(opts({operation: 'update', agents: ['cursor']})); + + expect(report.hosts[0].packs).toEqual([ + {name: 'reply-adapter', action: 'current', version: cli_version(), refreshed: true}, + ]); expect(human_lines(report).join('\n')).toMatch(/new session/i); }); @@ -306,7 +264,7 @@ describe('run_skills', ()=>{ it('reports packs recorded for a host the registry no longer has', async()=>{ const orphan_file = path.join(home, '.gemini', 'skills', 'ai-sdr-core-skill', 'SKILL.md'); record_pack('gemini-cli', 'user', 'ai-sdr-core', { - version: '0.3.0', ref: 'main', commit: 'deadbee', scope: 'user', + version: '0.3.0', scope: 'user', files: [orphan_file], complete: true, installed_at: '2026-07-30T00:00:00.000Z', }, {REPLY_CONFIG_DIR: path.join(root, 'config')}); @@ -326,16 +284,4 @@ describe('run_skills', ()=>{ expect(report.orphans).toBeUndefined(); expect(human_lines(report).join('\n')).not.toContain('no longer supports'); }); - - it('reports no commit when the clone failed', async()=>{ - const failing_clone = async()=>{ - throw new Error('git not found'); - }; - const report = await run_skills(opts({ - agents: ['cursor'], - deps: {...opts().deps, clone: failing_clone}, - })); - expect(report.hosts[0]).toEqual(expect.objectContaining({status: 'failed', reason: 'clone-failed'})); - expect(report.source).toEqual({repo: 'reply-team/reply-skills', ref: 'main'}); - }); }); diff --git a/src/__tests__/skills/package-pack.test.ts b/src/__tests__/skills/package-pack.test.ts new file mode 100644 index 0000000..102be12 --- /dev/null +++ b/src/__tests__/skills/package-pack.test.ts @@ -0,0 +1,343 @@ +import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest'; +import {execSync} from 'child_process'; +import fs from 'fs'; +import os from 'os'; +import path from 'path'; +import {cli_version} from '../../config'; +import {read_journal, record_pack} from '../../skills/journal'; +import {MOVED, pack_dir, resolve_packs} from '../../skills/packs'; +import {run_skills} from '../../skills/orchestrate'; +import {human_lines} from '../../skills/report'; +import type {Detect_deps} from '../../skills/detect'; +import type {Runner, Run_result} from '../../skills/types'; +import {UsageError} from '../../utils/errors'; + +// The pack the package carries, and how every operation reaches it: from the +// package's own files, at the CLI's own version, with no network and no git. + +const REPO_ROOT = path.resolve(__dirname, '..', '..', '..'); +const SKILLS = ['reply-api', 'reply-auth', 'reply-cli', 'reply-mcp', 'reply-operations-mapping']; + +const files_under = (dir: string): string[]=>fs.readdirSync(dir, {withFileTypes: true}).flatMap(e=> + e.isDirectory() + ? files_under(path.join(dir, e.name)).map(f=>path.join(e.name, f)) + : [e.name]); + +let root: string; +let home: string; +let env: Record; + +const ok = (stdout = ''): Run_result=>({code: 0, stdout, stderr: ''}); + +// `claude plugin list --json` in the direct-array shape, rows of the +// marketplace an earlier version registered, plus one foreign row. +const claude_listing = (ids: string[]): string=>JSON.stringify([ + ...ids.map(id=>({id, version: '0.3.0', scope: 'user', enabled: true})), + {id: 'elastic-elasticsearch@elastic-agent-skills', version: '0.2.4', scope: 'user', enabled: true}, +]); + +// A runner that answers the plugin CLI and refuses everything else, git +// included: an install that reaches for anything but the host's plugin +// listing and uninstall fails the test. +const plugin_runner = (opts: {listed?: string[]; uninstall_fails?: boolean} = {})=>{ + const calls: string[][] = []; + const run: Runner = async(bin, args)=>{ + calls.push([bin, ...args]); + if (bin !== '/usr/bin/claude') + { + throw new Error(`unexpected process: ${bin} ${args.join(' ')}`); + } + if (args.join(' ') === 'plugin list --json') + { + return ok(claude_listing(opts.listed ?? [])); + } + if (args[0] === 'plugin' && args[1] === 'uninstall') + { + return opts.uninstall_fails + ? {code: 1, stdout: '', stderr: 'Plugin is locked by another process'} + : ok(); + } + throw new Error(`unexpected command: ${bin} ${args.join(' ')}`); + }; + return {run, calls}; +}; + +const detect = (bins: Record = {claude: '/usr/bin/claude'}): Detect_deps=>({ + home, + platform: 'linux', + exists: (p: string)=>fs.existsSync(p), + find_on_path: (name: string)=>bins[name], + glob_first: ()=>undefined, +}); + +const opts = (over: Record = {}, run?: Runner)=>({ + operation: 'install' as const, + requested: [] as string[], + project: false, + dry_run: false, + deps: {detect: detect(), run: run ?? plugin_runner().run, home, cwd: path.join(root, 'project'), env}, + ...over, +}); + +beforeEach(()=>{ + root = fs.mkdtempSync(path.join(os.tmpdir(), 'reply-pack-')); + home = path.join(root, 'home'); + fs.mkdirSync(path.join(home, '.claude'), {recursive: true}); + env = {REPLY_CONFIG_DIR: path.join(root, 'config')}; + // Any network read fails the test that makes it. + vi.stubGlobal('fetch', ()=>{ + throw new Error('network read'); + }); +}); +afterEach(()=>{ + vi.unstubAllGlobals(); + fs.rmSync(root, {recursive: true, force: true}); +}); + +describe('the pack in the package', ()=>{ + it('is found from the source layout: the five skills, each with its SKILL.md', ()=>{ + const dir = pack_dir(); + expect(path.resolve(dir)).toBe(path.join(REPO_ROOT, 'skills', 'reply-adapter')); + expect(fs.readdirSync(dir).sort()).toEqual(SKILLS); + for (const skill of SKILLS) + { + expect(fs.existsSync(path.join(dir, skill, 'SKILL.md'))).toBe(true); + } + }); + + it('is found from the built layout, which sits at the same depth under dist', ()=>{ + expect(path.resolve(pack_dir(path.join(REPO_ROOT, 'dist', 'skills')))) + .toBe(path.join(REPO_ROOT, 'skills', 'reply-adapter')); + // The build itself, where one exists (CI builds before it tests). + const built = path.join(REPO_ROOT, 'dist', 'skills', 'packs.js'); + if (fs.existsSync(built)) + { + // eslint-disable-next-line @typescript-eslint/no-require-imports + const mod = require(built) as {pack_dir: ()=>string}; + expect(path.resolve(mod.pack_dir())).toBe(path.join(REPO_ROOT, 'skills', 'reply-adapter')); + } + }); + + it('is in what npm publishes, every file of it', ()=>{ + const out = execSync('npm pack --dry-run --json --ignore-scripts', { + cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], + }); + const published = new Set((JSON.parse(out)[0].files as {path: string}[]).map(f=>f.path)); + const expected = files_under(pack_dir()).map(f=>`skills/reply-adapter/${f.split(path.sep).join('/')}`); + expect(expected.length).toBeGreaterThan(SKILLS.length); + for (const file of expected) + { + expect(published.has(file), file).toBe(true); + } + }, 120_000); + + it('is installed at the CLI\'s own version', ()=>{ + expect(resolve_packs([], 'install')).toEqual([{name: 'reply-adapter', version: cli_version()}]); + expect(resolve_packs(['adapter'], 'update')).toEqual([{name: 'reply-adapter', version: cli_version()}]); + }); +}); + +describe('the names this CLI no longer offers', ()=>{ + for (const name of ['core', 'ai-sdr-core', 'runtime', 'agentic-runtime']) + { + for (const operation of ['install', 'update'] as const) + { + it(`refuses ${name} on ${operation} with the one sentence and exit code 2`, async()=>{ + const attempt = run_skills(opts({operation, requested: [name]})); + await expect(attempt).rejects.toThrow(UsageError); + await expect(attempt).rejects.toMatchObject({message: MOVED, exit_code: 2}); + }); + } + } + + it('says it in one sentence that names Jason', ()=>{ + expect(MOVED.split(/(?<=\.)\s/)).toHaveLength(1); + expect(MOVED).toContain('github.com/reply-team/jason-ai'); + }); +}); + +describe('install from the package', ()=>{ + it('copies every file of the pack into Claude Code\'s user skills directory, byte for byte, with no network and no git', async()=>{ + const report = await run_skills(opts()); + const target = path.join(home, '.claude', 'skills'); + for (const file of files_under(pack_dir())) + { + expect(fs.readFileSync(path.join(target, file)).equals(fs.readFileSync(path.join(pack_dir(), file))), file) + .toBe(true); + } + expect(report.hosts[0]).toMatchObject({ + host: 'claude-code', scope: 'user', status: 'ok', + packs: [{name: 'reply-adapter', action: 'installed', version: cli_version()}], + }); + }); + + it('copies into Codex\'s user directory, .agents/skills', async()=>{ + fs.mkdirSync(path.join(home, '.codex'), {recursive: true}); + const report = await run_skills(opts({agents: ['codex']})); + expect(report.hosts[0]).toMatchObject({host: 'codex', status: 'ok'}); + expect(fs.existsSync(path.join(home, '.agents', 'skills', 'reply-cli', 'SKILL.md'))).toBe(true); + }); + + it('journals the version and no repository ref or commit, and reports neither', async()=>{ + const report = await run_skills(opts()); + const entry = read_journal(env).hosts['claude-code'].user['reply-adapter']; + expect(entry.version).toBe(cli_version()); + expect(entry).not.toHaveProperty('ref'); + expect(entry).not.toHaveProperty('commit'); + expect(report.source).toEqual({version: cli_version()}); + expect(report.hosts[0]).not.toHaveProperty('commit'); + }); + + it('removes the old reply-adapter plugin through the host CLI, that plugin alone', async()=>{ + const {run, calls} = plugin_runner({listed: [ + 'ai-sdr-core@reply-skills', 'reply-adapter@reply-skills', 'agentic-runtime@reply-skills', + ]}); + const report = await run_skills(opts({}, run)); + const uninstalls = calls.filter(c=>c[2] === 'uninstall'); + expect(uninstalls).toEqual([['/usr/bin/claude', 'plugin', 'uninstall', 'reply-adapter@reply-skills']]); + expect(calls.some(c=>c.includes('marketplace'))).toBe(false); + expect(report.hosts[0]).toMatchObject({ + status: 'ok', + packs: [{name: 'reply-adapter', action: 'upgraded', from: '0.3.0', version: cli_version()}], + old_plugin: {id: 'reply-adapter@reply-skills', action: 'removed'}, + }); + }); + + it('says in one line that the other two old plugins stay and are no longer offered', async()=>{ + const {run} = plugin_runner({listed: [ + 'ai-sdr-core@reply-skills', 'reply-adapter@reply-skills', 'agentic-runtime@reply-skills', + ]}); + const report = await run_skills(opts({}, run)); + expect(report.hosts[0].retired_plugins).toEqual(['ai-sdr-core@reply-skills', 'agentic-runtime@reply-skills']); + const lines = human_lines(report).filter(l=>l.includes('no longer offers')); + expect(lines).toHaveLength(1); + expect(lines[0]).toContain('ai-sdr-core@reply-skills'); + expect(lines[0]).toContain('agentic-runtime@reply-skills'); + }); + + it('proceeds when the old plugin cannot be removed, and says it is still there beside the copy', async()=>{ + const {run} = plugin_runner({listed: ['reply-adapter@reply-skills'], uninstall_fails: true}); + const report = await run_skills(opts({}, run)); + expect(fs.existsSync(path.join(home, '.claude', 'skills', 'reply-api', 'SKILL.md'))).toBe(true); + expect(report.hosts[0]).toMatchObject({ + status: 'ok', + old_plugin: {id: 'reply-adapter@reply-skills', action: 'failed', detail: 'Plugin is locked by another process'}, + }); + expect(report.summary.installed).toBe(1); + expect(human_lines(report).join('\n')).toMatch(/reply-adapter@reply-skills plugin is still installed/); + }); + + it('refuses a personal skill of the same name in Claude Code\'s user directory and leaves the old plugin alone', async()=>{ + const mine = path.join(home, '.claude', 'skills', 'reply-api', 'SKILL.md'); + fs.mkdirSync(path.dirname(mine), {recursive: true}); + fs.writeFileSync(mine, 'my own skill\n'); + const {run, calls} = plugin_runner({listed: ['reply-adapter@reply-skills']}); + const report = await run_skills(opts({}, run)); + expect(fs.readFileSync(mine, 'utf8')).toBe('my own skill\n'); + expect(fs.existsSync(path.join(home, '.claude', 'skills', 'reply-cli'))).toBe(false); + expect(report.hosts[0]).toMatchObject({ + status: 'failed', + packs: [{name: 'reply-adapter', action: 'failed', detail: 'conflicts with an existing skill: reply-api'}], + }); + expect(calls.some(c=>c[2] === 'uninstall')).toBe(false); + }); +}); + +describe('update from the package', ()=>{ + it('replaces the old plugin with the copy on a host that has only the plugin', async()=>{ + const {run, calls} = plugin_runner({listed: ['reply-adapter@reply-skills']}); + const report = await run_skills(opts({operation: 'update'}, run)); + expect(fs.existsSync(path.join(home, '.claude', 'skills', 'reply-mcp', 'SKILL.md'))).toBe(true); + expect(calls.filter(c=>c[2] === 'uninstall')).toEqual([ + ['/usr/bin/claude', 'plugin', 'uninstall', 'reply-adapter@reply-skills'], + ]); + expect(report.hosts[0]).toMatchObject({ + packs: [{name: 'reply-adapter', action: 'upgraded', from: '0.3.0'}], + old_plugin: {action: 'removed'}, + }); + }); + + it('brings a copy an earlier version made from a repository to this version', async()=>{ + fs.mkdirSync(path.join(home, '.cursor'), {recursive: true}); + const old = path.join(home, '.cursor', 'skills', 'reply-api', 'SKILL.md'); + fs.mkdirSync(path.dirname(old), {recursive: true}); + fs.writeFileSync(old, 'old text\n'); + record_pack('cursor', 'user', 'reply-adapter', { + version: '0.1.0', ref: 'main', commit: 'cafe123', scope: 'user', + files: [old], complete: true, installed_at: '2026-10-01T00:00:00.000Z', + }, env); + const report = await run_skills(opts({operation: 'update', agents: ['cursor']})); + expect(report.hosts[0].packs).toEqual([ + {name: 'reply-adapter', action: 'upgraded', from: '0.1.0', version: cli_version()}, + ]); + expect(fs.readFileSync(old).equals(fs.readFileSync(path.join(pack_dir(), 'reply-api', 'SKILL.md')))).toBe(true); + }); +}); + +describe('list and remove over what an earlier version installed', ()=>{ + // The shape 0.18.0 journaled: a copy of the three packs, from a ref and a commit. + const seed_old_copy = ()=>{ + fs.mkdirSync(path.join(home, '.cursor'), {recursive: true}); + const files: Record = {}; + for (const [pack, skill] of [['ai-sdr-core', 'sdr-operations'], ['reply-adapter', 'reply-api'], ['agentic-runtime', 'durable-work']]) + { + const file = path.join(home, '.cursor', 'skills', skill, 'SKILL.md'); + fs.mkdirSync(path.dirname(file), {recursive: true}); + fs.writeFileSync(file, `${skill}\n`); + files[pack] = file; + record_pack('cursor', 'user', pack, { + version: '0.1.0', ref: 'main', commit: 'cafe123', scope: 'user', + files: [file], complete: true, installed_at: '2026-10-01T00:00:00.000Z', + }, env); + } + return files; + }; + + it('lists a journal entry of the earlier shape, the retired packs marked as no longer offered', async()=>{ + seed_old_copy(); + const report = await run_skills(opts({operation: 'list', agents: ['cursor']})); + expect(report.hosts[0].packs).toEqual([ + {name: 'reply-adapter', action: 'upgraded', version: cli_version(), from: '0.1.0'}, + {name: 'ai-sdr-core', action: 'current', version: '0.1.0', retired: true}, + {name: 'agentic-runtime', action: 'current', version: '0.1.0', retired: true}, + ]); + expect(human_lines(report).join('\n')).toContain('ai-sdr-core, agentic-runtime installed, no longer offered'); + }); + + it('removes a journal entry of the earlier shape under its old name, and everything with no name', async()=>{ + const files = seed_old_copy(); + const one = await run_skills(opts({operation: 'remove', requested: ['core'], agents: ['cursor']})); + expect(one.hosts[0].packs).toEqual([{name: 'ai-sdr-core', action: 'removed', version: '0.1.0'}]); + expect(fs.existsSync(files['ai-sdr-core'])).toBe(false); + expect(fs.existsSync(files['reply-adapter'])).toBe(true); + + const all = await run_skills(opts({operation: 'remove', agents: ['cursor']})); + expect(all.hosts[0].packs?.map(p=>p.name).sort()).toEqual(['agentic-runtime', 'reply-adapter']); + expect(read_journal(env).hosts).toEqual({}); + }); + + it('lists the @reply-skills plugins an earlier version installed', async()=>{ + const {run} = plugin_runner({listed: ['ai-sdr-core@reply-skills', 'reply-adapter@reply-skills']}); + const report = await run_skills(opts({operation: 'list'}, run)); + expect(report.hosts[0].packs).toEqual([ + {name: 'reply-adapter@reply-skills', action: 'upgraded', version: cli_version(), from: '0.3.0'}, + {name: 'ai-sdr-core@reply-skills', action: 'current', version: '0.3.0', retired: true}, + ]); + }); + + it('removes the @reply-skills plugins through the host CLI, under any old name', async()=>{ + const {run, calls} = plugin_runner({listed: [ + 'ai-sdr-core@reply-skills', 'reply-adapter@reply-skills', 'agentic-runtime@reply-skills', + ]}); + const one = await run_skills(opts({operation: 'remove', requested: ['runtime']}, run)); + expect(one.hosts[0].packs).toEqual([{name: 'agentic-runtime@reply-skills', action: 'removed', version: '0.3.0'}]); + expect(calls.filter(c=>c[2] === 'uninstall').map(c=>c[3])).toEqual(['agentic-runtime@reply-skills']); + + calls.length = 0; + await run_skills(opts({operation: 'remove'}, run)); + expect(calls.filter(c=>c[2] === 'uninstall').map(c=>c[3]).sort()).toEqual([ + 'agentic-runtime@reply-skills', 'ai-sdr-core@reply-skills', 'reply-adapter@reply-skills', + ]); + expect(calls.some(c=>c.includes('marketplace'))).toBe(false); + }); +}); diff --git a/src/__tests__/skills/packs.test.ts b/src/__tests__/skills/packs.test.ts index 69887cd..46a7475 100644 --- a/src/__tests__/skills/packs.test.ts +++ b/src/__tests__/skills/packs.test.ts @@ -1,120 +1,67 @@ -import {describe, it, expect, vi} from 'vitest'; -import {parse_packs, load_packs, resolve_packs, packs_url, PACKS_FALLBACK, DEFAULT_REF} from '../../skills/packs'; -import {UsageError, RuntimeError} from '../../utils/errors'; +import {describe, it, expect} from 'vitest'; +import {cli_version} from '../../config'; +import {MOVED, plugin_id, resolve_packs} from '../../skills/packs'; +import {UsageError} from '../../utils/errors'; -const registry = PACKS_FALLBACK; const names = (packs: {name: string}[]): string[]=>packs.map(p=>p.name); describe('resolve_packs', ()=>{ - it('returns every pack, core first, when nothing is requested', ()=>{ - expect(names(resolve_packs([], registry))).toEqual(['ai-sdr-core', 'reply-adapter', 'agentic-runtime']); - }); - - it('expands the short aliases', ()=>{ - expect(names(resolve_packs(['core'], registry))).toEqual(['ai-sdr-core']); - expect(names(resolve_packs(['runtime'], registry))).toEqual(['ai-sdr-core', 'agentic-runtime']); - }); - - it('accepts canonical names too', ()=>{ - expect(names(resolve_packs(['ai-sdr-core'], registry))).toEqual(['ai-sdr-core']); - }); - - it('pulls the dependency and keeps it first', ()=>{ - expect(names(resolve_packs(['adapter'], registry))).toEqual(['ai-sdr-core', 'reply-adapter']); - }); - - it('de-duplicates a pack requested twice or pulled twice', ()=>{ - expect(names(resolve_packs(['adapter', 'runtime', 'core'], registry))) - .toEqual(['ai-sdr-core', 'reply-adapter', 'agentic-runtime']); - }); - - it('rejects an unknown name with a usage error listing the valid ones', ()=>{ - expect(()=>resolve_packs(['nope'], registry)).toThrow(UsageError); - try { resolve_packs(['nope'], registry); } - catch (e) { expect((e as UsageError).hint).toContain('ai-sdr-core'); } - }); - - // Removal must not expand the graph: `remove runtime` means that pack and - // nothing else. Expanding would drag the core out from under the adapter. - it('does not pull dependencies when dependencies are switched off', ()=>{ - expect(names(resolve_packs(['runtime'], registry, {dependencies: false}))).toEqual(['agentic-runtime']); - expect(names(resolve_packs(['adapter'], registry, {dependencies: false}))).toEqual(['reply-adapter']); - }); - - it('still returns everything, dependency-ordered, when nothing is requested', ()=>{ - expect(names(resolve_packs([], registry, {dependencies: false}))) - .toEqual(['ai-sdr-core', 'reply-adapter', 'agentic-runtime']); - }); - - it('keeps registry order when dependencies are off, so reversing gives dependents first', ()=>{ - expect(names(resolve_packs(['runtime', 'core'], registry, {dependencies: false}))) - .toEqual(['ai-sdr-core', 'agentic-runtime']); + it('means the one pack for install and update when nothing is requested', ()=>{ + for (const operation of ['install', 'update'] as const) + { + expect(resolve_packs([], operation)).toEqual([{name: 'reply-adapter', version: cli_version()}]); + } + }); + + it('means everything an earlier version installed for list and remove when nothing is requested', ()=>{ + for (const operation of ['list', 'remove'] as const) + { + expect(resolve_packs([], operation)).toEqual([ + {name: 'reply-adapter', version: cli_version()}, + {name: 'ai-sdr-core', version: '', retired: true}, + {name: 'agentic-runtime', version: '', retired: true}, + ]); + } + }); + + it('accepts the canonical name and the alias, once', ()=>{ + expect(names(resolve_packs(['adapter', 'reply-adapter'], 'install'))).toEqual(['reply-adapter']); + }); + + it('reaches the retired packs by their old names for list and remove', ()=>{ + expect(resolve_packs(['core'], 'remove')).toEqual([{name: 'ai-sdr-core', version: '', retired: true}]); + expect(resolve_packs(['runtime', 'agentic-runtime'], 'list')) + .toEqual([{name: 'agentic-runtime', version: '', retired: true}]); + }); + + it('refuses a retired name for install with the one sentence', ()=>{ + let caught: unknown; + try { + resolve_packs(['adapter', 'core'], 'install'); + } catch (error) { + caught = error; + } + expect(caught).toBeInstanceOf(UsageError); + expect((caught as UsageError).message).toBe(MOVED); + expect((caught as UsageError).code).toBe('usage.skills_pack_moved'); + }); + + it('rejects an unknown name with a usage error naming the pack', ()=>{ + let caught: unknown; + try { + resolve_packs(['nope'], 'install'); + } catch (error) { + caught = error; + } + expect(caught).toBeInstanceOf(UsageError); + expect((caught as UsageError).message).toContain('nope'); + expect((caught as UsageError).hint).toContain('reply-adapter'); + expect((caught as UsageError).hint).toContain('adapter'); }); }); -describe('parse_packs', ()=>{ - it('reads marketplace name and packs', ()=>{ - const parsed = parse_packs({ - marketplace: {name: 'reply-skills'}, - packs: [{name: 'a', displayName: 'A', version: '1.0.0', description: 'd', dependencies: []}], - }); - expect(parsed.marketplace).toBe('reply-skills'); - expect(parsed.packs[0]).toEqual({name: 'a', display_name: 'A', version: '1.0.0', description: 'd', dependencies: []}); - }); - - it('defaults a missing dependencies array to empty', ()=>{ - const parsed = parse_packs({ - marketplace: {name: 'm'}, - packs: [{name: 'a', version: '1.0.0'}], - }); - expect(parsed.packs[0].dependencies).toEqual([]); - }); - - it('rejects the whole document when a pack has no name', ()=>{ - expect(()=>parse_packs({marketplace: {name: 'm'}, packs: [{version: '1.0.0'}]})).toThrow(RuntimeError); - }); - - it('rejects a document with no packs array', ()=>{ - expect(()=>parse_packs({marketplace: {name: 'm'}})).toThrow(RuntimeError); - }); - - it('rejects a dependency that names a pack not in the document', ()=>{ - expect(()=>parse_packs({ - marketplace: {name: 'm'}, - packs: [{name: 'a', version: '1.0.0', dependencies: ['ghost']}], - })).toThrow(RuntimeError); - }); -}); - -describe('load_packs', ()=>{ - it('builds the raw URL from the ref', ()=>{ - expect(packs_url('v1.2.3')).toBe( - 'https://raw.githubusercontent.com/reply-team/reply-skills/v1.2.3/packs.json'); - expect(packs_url(DEFAULT_REF)).toContain('/main/packs.json'); - }); - - it('uses the fetched document when the request succeeds', async()=>{ - const body = {marketplace: {name: 'reply-skills'}, packs: [{name: 'solo', version: '9.9.9'}]}; - const fetch_impl = vi.fn().mockResolvedValue(new Response(JSON.stringify(body), {status: 200})); - const parsed = await load_packs({fetch_impl: fetch_impl as unknown as typeof fetch}); - expect(names(parsed.packs)).toEqual(['solo']); - }); - - it('falls back to the embedded copy when the network fails', async()=>{ - const fetch_impl = vi.fn().mockRejectedValue(new TypeError('offline')); - const parsed = await load_packs({fetch_impl: fetch_impl as unknown as typeof fetch}); - expect(names(parsed.packs)).toEqual(names(PACKS_FALLBACK.packs)); - }); - - it('falls back on a non-200 response', async()=>{ - const fetch_impl = vi.fn().mockResolvedValue(new Response('nope', {status: 404})); - const parsed = await load_packs({fetch_impl: fetch_impl as unknown as typeof fetch}); - expect(names(parsed.packs)).toEqual(names(PACKS_FALLBACK.packs)); - }); - - it('falls back when the fetched document is malformed rather than throwing', async()=>{ - const fetch_impl = vi.fn().mockResolvedValue(new Response('{"packs":[{"no":"name"}]}', {status: 200})); - const parsed = await load_packs({fetch_impl: fetch_impl as unknown as typeof fetch}); - expect(names(parsed.packs)).toEqual(names(PACKS_FALLBACK.packs)); +describe('plugin_id', ()=>{ + it('names a plugin of the marketplace an earlier version registered', ()=>{ + expect(plugin_id('reply-adapter')).toBe('reply-adapter@reply-skills'); }); }); diff --git a/src/__tests__/skills/plugins.test.ts b/src/__tests__/skills/plugins.test.ts new file mode 100644 index 0000000..0f046a4 --- /dev/null +++ b/src/__tests__/skills/plugins.test.ts @@ -0,0 +1,109 @@ +import {describe, it, expect} from 'vitest'; +import {host_by_id} from '../../skills/hosts'; +import {old_plugins, remove_plugin} from '../../skills/plugins'; +import type {Detected_host} from '../../skills/detect'; +import type {Run_result, Runner} from '../../skills/types'; + +const ok = (stdout = ''): Run_result=>({code: 0, stdout, stderr: ''}); +const fail = (stderr = 'boom'): Run_result=>({code: 1, stdout: '', stderr}); + +const claude = (): Detected_host=> + ({def: host_by_id('claude-code'), bin: '/usr/bin/claude', config_dir: '/home/a/.claude'}); +const codex = (): Detected_host=> + ({def: host_by_id('codex'), bin: 'C:\\codex.exe', config_dir: 'C:\\Users\\a\\.codex'}); + +// The older `claude plugin list --json` shape, rows with `name` and +// `marketplace` wrapped in {plugins:[…]}. +const claude_list = (packs: {name: string; version: string; marketplace?: string}[]): string=>JSON.stringify({ + plugins: packs.map(p=>({ + name: p.name, marketplace: p.marketplace ?? 'reply-skills', version: p.version, enabled: true, + })), +}); + +// Claude Code's current `plugin list --json` shape: a direct array of rows +// with an `id` of the form "@" and the scope the plugin +// was installed in. The foreign row is the shape of a real one, a plugin of a +// marketplace other than the one an earlier version of this CLI registered. +const claude_list_direct = (rows: {id: string; version: string; scope?: string}[]): string=>JSON.stringify( + rows.map(r=>({id: r.id, version: r.version, scope: r.scope ?? 'user', enabled: true})), +); + +const runner_of = (results: Run_result[]): {run: Runner; calls: string[][]}=>{ + const calls: string[][] = []; + let i = 0; + const run: Runner = async(bin, args)=>{ + calls.push([bin, ...args]); + return results[i++] ?? ok(); + }; + return {run, calls}; +}; + +describe('old_plugins', ()=>{ + it('maps pack name to version from the older wrapped shape', async()=>{ + const {run, calls} = runner_of([ok(claude_list([{name: 'ai-sdr-core', version: '0.1.0'}]))]); + expect(await old_plugins(claude(), run, 'user')).toEqual({ok: true, versions: {'ai-sdr-core': '0.1.0'}}); + expect(calls).toEqual([['/usr/bin/claude', 'plugin', 'list', '--json']]); + }); + + it('reads the direct-array id shape Claude Code now returns', async()=>{ + const {run} = runner_of([ok(claude_list_direct([{id: 'reply-adapter@reply-skills', version: '0.3.0'}]))]); + expect(await old_plugins(claude(), run, 'user')).toEqual({ok: true, versions: {'reply-adapter': '0.3.0'}}); + }); + + it('takes no plugin of another marketplace, even one of the same name', async()=>{ + const {run} = runner_of([ok(claude_list_direct([ + {id: 'elastic-elasticsearch@elastic-agent-skills', version: '0.2.4'}, + {id: 'reply-adapter@somebody-else', version: '9.9.9'}, + ]))]); + expect(await old_plugins(claude(), run, 'user')).toEqual({ok: true, versions: {}}); + }); + + it('takes a row only for the scope this run acts on', async()=>{ + const listing = claude_list_direct([ + {id: 'reply-adapter@reply-skills', version: '0.3.0', scope: 'project'}, + {id: 'ai-sdr-core@reply-skills', version: '0.3.0', scope: 'user'}, + ]); + const {run} = runner_of([ok(listing), ok(listing)]); + expect(await old_plugins(claude(), run, 'user')).toEqual({ok: true, versions: {'ai-sdr-core': '0.3.0'}}); + expect(await old_plugins(claude(), run, 'project')).toEqual({ok: true, versions: {'reply-adapter': '0.3.0'}}); + }); + + it('reads the Codex shape, whose rows name no scope', async()=>{ + const listing = JSON.stringify({installed: [ + {name: 'reply-adapter', version: '0.3.0', marketplaceName: 'reply-skills'}, + {name: 'other', version: '1.0.0', marketplaceName: 'elsewhere'}, + ]}); + const {run} = runner_of([ok(listing)]); + expect(await old_plugins(codex(), run, 'user')).toEqual({ok: true, versions: {'reply-adapter': '0.3.0'}}); + }); + + it('fails with the host\'s own words when the listing fails or is not JSON', async()=>{ + const {run} = runner_of([fail('not logged in'), ok('not json')]); + expect(await old_plugins(claude(), run, 'user')).toEqual({ok: false, detail: 'not logged in'}); + expect(await old_plugins(claude(), run, 'user')).toEqual({ok: false, detail: 'the plugin listing was not JSON'}); + }); +}); + +describe('remove_plugin', ()=>{ + it('removes one plugin through Claude Code, in the scope asked', async()=>{ + const {run, calls} = runner_of([ok(), ok()]); + expect(await remove_plugin(claude(), run, 'reply-adapter@reply-skills', 'user')).toEqual({ok: true}); + expect(await remove_plugin(claude(), run, 'reply-adapter@reply-skills', 'project')).toEqual({ok: true}); + expect(calls).toEqual([ + ['/usr/bin/claude', 'plugin', 'uninstall', 'reply-adapter@reply-skills'], + ['/usr/bin/claude', 'plugin', 'uninstall', 'reply-adapter@reply-skills', '--scope', 'project'], + ]); + }); + + it('removes one plugin through Codex, with its own verb', async()=>{ + const {run, calls} = runner_of([ok()]); + await remove_plugin(codex(), run, 'reply-adapter@reply-skills', 'user'); + expect(calls).toEqual([['C:\\codex.exe', 'plugin', 'remove', 'reply-adapter@reply-skills', '--json']]); + }); + + it('reports the host\'s words when removal fails', async()=>{ + const {run} = runner_of([fail('Plugin is locked by another process')]); + expect(await remove_plugin(claude(), run, 'reply-adapter@reply-skills', 'user')) + .toEqual({ok: false, detail: 'Plugin is locked by another process'}); + }); +}); diff --git a/src/__tests__/skills/report.test.ts b/src/__tests__/skills/report.test.ts index 6f8cc9f..5ae6d30 100644 --- a/src/__tests__/skills/report.test.ts +++ b/src/__tests__/skills/report.test.ts @@ -1,13 +1,13 @@ import {describe, it, expect} from 'vitest'; import {HOSTS} from '../../skills/hosts'; -import {human_lines, exit_code_for, summarize, dependency_note} from '../../skills/report'; +import {human_lines, exit_code_for, summarize} from '../../skills/report'; import type {Host_outcome, Report} from '../../skills/types'; const strip = (s: string): string=>s.replace(/\x1b\[[0-9;]*m/g, ''); const text = (report: Report): string=>human_lines(report).map(strip).join('\n'); const host = (over: Partial = {}): Host_outcome=>({ - host: 'claude-code', label: 'Claude Code', kind: 'native-plugin', scope: 'user', status: 'ok', + host: 'claude-code', label: 'Claude Code', kind: 'flat-skills-dir', scope: 'user', status: 'ok', packs: [ {name: 'ai-sdr-core', action: 'installed', version: '0.1.0'}, {name: 'reply-adapter', action: 'installed', version: '0.1.0'}, @@ -19,7 +19,7 @@ const report = (hosts: Host_outcome[], over: Partial = {}): Report=>{ const action = over.action ?? 'install'; return { action, - source: {repo: 'reply-team/reply-skills', ref: 'main'}, + source: {version: '0.1.0'}, requested: ['ai-sdr-core', 'reply-adapter'], resolved: ['ai-sdr-core', 'reply-adapter'], hosts, @@ -152,10 +152,37 @@ describe('human_lines', ()=>{ expect(out).not.toContain('paths not yet verified'); }); - it('reports a pulled dependency once', ()=>{ - expect(dependency_note(['reply-adapter'], ['ai-sdr-core', 'reply-adapter'])) - .toBe('ai-sdr-core added — required by reply-adapter'); - expect(dependency_note(['ai-sdr-core'], ['ai-sdr-core'])).toBeUndefined(); + it('says a retired pack found by list is installed and no longer offered', ()=>{ + const out = text(report([host({packs: [ + {name: 'reply-adapter', action: 'current', version: '0.1.0'}, + {name: 'ai-sdr-core', action: 'current', version: '0.0.9', retired: true}, + ]})], {action: 'list'})); + expect(out).toMatch(/Claude Code +· reply-adapter already current; ai-sdr-core installed, no longer offered/); + }); + + it('says the old plugin was replaced by the copy', ()=>{ + const out = text(report([host({old_plugin: {id: 'reply-adapter@reply-skills', action: 'removed'}})])); + expect(out).toContain('replaced the reply-adapter@reply-skills plugin with this copy'); + }); + + it('says the old plugin still loads beside the copy, and how to remove it, when it could not be removed', ()=>{ + const out = text(report([host({ + scope: 'project', + old_plugin: {id: 'reply-adapter@reply-skills', action: 'failed', detail: 'locked'}, + })])); + expect(out).toContain('the reply-adapter@reply-skills plugin is still installed and loads beside this copy: locked'); + expect(out).toContain('fix: claude plugin uninstall reply-adapter@reply-skills --scope project'); + }); + + it('names the old plugins it leaves in one line for the whole run', ()=>{ + const lines = human_lines(report([ + host({retired_plugins: ['ai-sdr-core@reply-skills', 'agentic-runtime@reply-skills']}), + host({host: 'codex', label: 'Codex', retired_plugins: ['ai-sdr-core@reply-skills']}), + ])).map(strip).filter(l=>l.includes('no longer offers')); + expect(lines).toEqual([ + 'ai-sdr-core@reply-skills, agentic-runtime@reply-skills stay installed in Claude Code and Codex;' + + ' this CLI no longer offers them.', + ]); }); it('tells the user a new session is needed after a successful install', ()=>{ @@ -167,9 +194,9 @@ describe('human_lines', ()=>{ expect(out).not.toMatch(/new session/i); }); - // An unchanged version reports `current` in every adapter, which is right — - // but a flat host that re-copied a newer commit at that same version did - // rewrite the files, and the user has to reload to pick them up. + // An unchanged version reports `current`, which is right — but a host + // whose unfinished copy was repaired at that same version did rewrite the + // files, and the user has to reload to pick them up. it('asks for a new session when files were rewritten at an unchanged version', ()=>{ const out = text(report([host({ packs: [{name: 'ai-sdr-core', action: 'current', version: '0.1.0', refreshed: true}], diff --git a/src/commands/skills.ts b/src/commands/skills.ts index c3e4cc5..143f254 100644 --- a/src/commands/skills.ts +++ b/src/commands/skills.ts @@ -94,7 +94,7 @@ const handle_skills = async( }; const skills_command = new Command('skills') - .description('Install and manage Reply skill packs in your AI assistants'); + .description('Install and manage the Reply skills in your AI assistants'); const with_flags = (cmd: Command): Command=>cmd .option('-a, --agent ', 'Target these assistants instead of auto-detecting') @@ -102,19 +102,18 @@ const with_flags = (cmd: Command): Command=>cmd .option('--dry-run', 'Show what would happen and change nothing'); const packs_help = ` -Packs: ai-sdr-core (alias core) · reply-adapter (adapter) · agentic-runtime (runtime). -No pack means all three; dependencies are resolved for you.`; +Pack: reply-adapter (alias adapter), the skills this CLI ships, at its own version. +No pack means it.`; with_flags(skills_command .command('install') - .argument('[packs...]', 'Packs to install (default: all three)') - .description('Install Reply skill packs into every detected assistant')) + .argument('[packs...]', 'Pack to install (default: reply-adapter)') + .description('Copy the Reply skills from this package into every detected assistant')) .addHelpText('after', `${packs_help} Examples: ${PROGRAM_NAME} skills install - ${PROGRAM_NAME} skills install core - ${PROGRAM_NAME} skills install adapter runtime + ${PROGRAM_NAME} skills install --project ${PROGRAM_NAME} skills install --agent codex --json`) .action(async function(this: Command, packs: string[]) { await handle_skills('install', packs, read_globals(this)); @@ -135,8 +134,8 @@ Examples: with_flags(skills_command .command('update') - .argument('[packs...]', 'Packs to update (default: all installed)') - .description('Update installed packs to the latest published version')) + .argument('[packs...]', 'Pack to update (default: reply-adapter, where installed)') + .description('Bring the installed skills to the version of this CLI')) .addHelpText('after', `${packs_help} Examples: @@ -148,15 +147,15 @@ Examples: with_flags(skills_command .command('remove') - .argument('[packs...]', 'Packs to remove (default: all of them)') - .description('Remove Reply skill packs from your assistants')) + .argument('[packs...]', 'Packs to remove (default: everything this CLI installed)') + .description('Remove the Reply skills from your assistants')) .addHelpText('after', `${packs_help} -Removing a pack that another installed pack depends on is refused — remove both, -or run \`${PROGRAM_NAME} skills remove\` with no pack to remove everything. +Remove also takes the names of packs an earlier version installed, and with no +pack removes everything this CLI ever installed. Examples: ${PROGRAM_NAME} skills remove - ${PROGRAM_NAME} skills remove runtime`) + ${PROGRAM_NAME} skills remove adapter --project`) .action(async function(this: Command, packs: string[]) { await handle_skills('remove', packs, read_globals(this)); }); diff --git a/src/skills/adapter-flat.ts b/src/skills/adapter-flat.ts index 23de7f0..8b077b4 100644 --- a/src/skills/adapter-flat.ts +++ b/src/skills/adapter-flat.ts @@ -1,48 +1,22 @@ import fs from 'fs'; import os from 'os'; import path from 'path'; -import {default_runner} from './adapter-native'; import {forget_pack, journal_entry, read_journal, record_pack} from './journal'; -import {DEFAULT_REF, REPO} from './packs'; +import {pack_dir} from './packs'; import type {Env} from '../config'; import type {Detected_host} from './detect'; import type {Journal_entry} from './journal'; -import type {Host_def, Host_outcome, Operation, Pack, Pack_outcome, Runner, Scope} from './types'; +import type {Host_def, Host_outcome, Operation, Pack, Pack_outcome, Scope} from './types'; -// For hosts with no plugin mechanism: a pack is just a directory of skills, so -// installing is a copy. `git` is required here; both native hosts already need -// it for `marketplace add`, and the resolved commit lands in the journal. +// Every host receives a pack as a directory of skills, so installing is a +// copy: from the pack's directory in this CLI's own package into the host's +// skills directory. Nothing is downloaded and no other program is run. -type Clone_result = {dir: string; commit: string}; -type Clone_fn = (opts: {ref: string; run: Runner; tmp_root: string})=>Promise; - -const clone_repo: Clone_fn = async({ref, run, tmp_root})=>{ - const dir = fs.mkdtempSync(path.join(tmp_root, 'reply-skills-')); - const url = `https://github.com/${REPO}.git`; - const cloned = await run('git', ['clone', '--depth', '1', '--branch', ref, url, dir]); - if (cloned.code !== 0) - { - fs.rmSync(dir, {recursive: true, force: true}); - throw new Error((cloned.stderr || cloned.stdout).trim() || `git clone failed for ${url}`); - } - const head = await run('git', ['-C', dir, 'rev-parse', 'HEAD']); - if (head.code !== 0) - { - fs.rmSync(dir, {recursive: true, force: true}); - throw new Error((head.stderr || head.stdout).trim() || `git rev-parse HEAD failed for ${url}`); - } - return {dir, commit: head.stdout.trim().slice(0, 7)}; -}; - -// Where this host reads skills from, for the requested scope. A native host -// only lands here under --project, because its plugin mechanism is user-scoped. -// Returns undefined when the host has no directory configured for this scope -// (e.g. a native host under `user` scope) so the caller can report a status -// instead of joining `undefined` into a path. -const skills_target = (def: Host_def, scope: Scope, home: string, cwd: string): string | undefined=>{ - const rel = scope === 'project' ? def.project_skills_dir : def.user_skills_dir; - return rel === undefined ? undefined : path.join(scope === 'project' ? cwd : home, rel); -}; +// Where this host reads skills from, for the requested scope. +const skills_target = (def: Host_def, scope: Scope, home: string, cwd: string): string=> + scope === 'project' + ? path.join(cwd, def.project_skills_dir) + : path.join(home, def.user_skills_dir); // Mutates `written` as it goes, rather than returning a fresh array, so that // a throw partway through (a read-only destination, a full disk) still leaves @@ -245,10 +219,8 @@ const owns_dir = ( return false; }; -// Mirrors adapter-native.ts's status_of: 'ok' with no failures, 'failed' when -// every pack in this operation failed, 'partial' otherwise. Kept local rather -// than shared, since the two adapters are twin, independent implementations -// of the same rule. +// 'ok' with no failures, 'failed' when every pack in this operation failed, +// 'partial' otherwise. const status_of = (packs: Pack_outcome[]): Host_outcome['status']=>{ const failed = packs.filter(p=>p.action === 'failed'); if (!failed.length) @@ -258,55 +230,31 @@ const status_of = (packs: Pack_outcome[]): Host_outcome['status']=>{ return failed.length === packs.length ? 'failed' : 'partial'; }; -// Twins of adapter-native.ts's pair, for the same reason status_of is a twin: -// install refuses a pack whose dependency failed, remove refuses a pack whose -// dependent failed, and the user reads the identical sentence either way. -const blocked_hint = (names: Iterable): string | undefined=>{ - const list = [...names]; - return list.length - ? `packs ${list.join(', ')} were not attempted because their dependencies failed; fix those installs and re-run` - : undefined; -}; - -const kept_hint = (names: Iterable): string | undefined=>{ - const list = [...names]; - return list.length - ? `packs ${list.join(', ')} were kept because packs that depend on them could not be removed; fix those removals and re-run` - : undefined; -}; - -// A copy that landed at the version the pack was already on is not an upgrade, -// even though this adapter really did re-copy from a fresh clone — the commit -// carries that difference, the version does not. Mirrors -// adapter-native.ts's updated_outcome so `current` means one thing everywhere. +// A copy that landed at the version the pack was already on is not an +// upgrade, so `current` means one thing everywhere. But "the version moved" +// and "the bytes moved" are two different facts: repairing an install that +// never finished rewrites files at an unchanged version. `current` cannot say +// that, so `refreshed` does — otherwise a run that really did rewrite the +// user's files reads as a no-op and the reporter never tells them to start a +// new session. // -// But "the version moved" and "the bytes moved" are two different facts, and -// this adapter clones a *ref*: a new commit on `main` can rewrite every file -// at an unchanged 0.1.0, and so can repairing an install that never finished. -// `current` cannot say that, so `refreshed` does — otherwise a run that really -// did rewrite the user's files reads as a no-op and the reporter never tells -// them to start a new session. -// -// `commit` is the commit these files were copied from, and is passed only by -// the path that actually copied: a dry run never clones, so it cannot know -// whether the ref moved and must not guess. +// `from` is the version the host had before — a journal entry's, or the old +// plugin's this copy replaces — and undefined when it had none. const copied_outcome = ( pack_name: string, version: string, - previous: Journal_entry | undefined, - commit?: string, + from: string | undefined, + repaired = false, ): Pack_outcome=>{ - if (previous === undefined) + if (from === undefined) { return {name: pack_name, action: 'installed', version}; } - if (previous.version !== version) + if (from !== version) { - return {name: pack_name, action: 'upgraded', version, from: previous.version}; + return {name: pack_name, action: 'upgraded', version, from}; } - const refreshed = commit !== undefined - && (previous.commit !== commit || !previous.complete); - return refreshed + return repaired ? {name: pack_name, action: 'current', version, refreshed: true} : {name: pack_name, action: 'current', version}; }; @@ -316,14 +264,16 @@ type Flat_opts = { host: Detected_host; packs: Pack[]; scope: Scope; - ref?: string; - run?: Runner; home?: string; cwd?: string; - tmp_root?: string; env?: Env; dry_run?: boolean; - clone?: Clone_fn; + // The directory holding each pack's directory of skills; the package's + // own `skills` by default. + source?: string; + // Packs the host has as a plugin an earlier version installed, by name and + // version: `update` copies them too, and an outcome counts from there. + adopt?: Record; // Injected like detect.ts's `exists`, so case handling is assertable without // depending on the runner's filesystem. Defaults to asking the OS. canonicalise?: (target: string)=>string; @@ -331,14 +281,12 @@ type Flat_opts = { const run_flat = async(opts: Flat_opts): Promise=>{ const {operation, host, packs, scope} = opts; - const run = opts.run ?? default_runner; - const ref = opts.ref ?? DEFAULT_REF; const home = opts.home ?? os.homedir(); const cwd = opts.cwd ?? process.cwd(); - const tmp_root = opts.tmp_root ?? os.tmpdir(); const dry_run = opts.dry_run === true; const canonicalise = opts.canonicalise ?? canonical; - const clone = opts.clone ?? clone_repo; + const source = opts.source ?? path.dirname(pack_dir()); + const adopt = opts.adopt ?? {}; const id = host.def.id; const base: Host_outcome = { host: id, label: host.def.label, kind: 'flat-skills-dir', scope, status: 'ok', @@ -365,7 +313,7 @@ const run_flat = async(opts: Flat_opts): Promise=>{ const entry = journal_entry(id, scope, pack_name, opts.env); return entry && belongs_here(entry) ? entry : undefined; }; - + const previous_for = (pack_name: string): Journal_entry | undefined=>{ const entry = entry_for(pack_name); return entry && entry_files_present(entry, canonicalise) ? entry : undefined; @@ -397,10 +345,17 @@ const run_flat = async(opts: Flat_opts): Promise=>{ outcomes.push({ name: pack.name, action: 'failed', - detail: 'installation incomplete; run `reply skills install` to repair', + detail: pack.retired + ? 'installation incomplete; this CLI no longer offers the pack, so `reply skills remove` clears it' + : 'installation incomplete; run `reply skills install` to repair', }); continue; } + if (pack.retired) + { + outcomes.push({name: pack.name, action: 'current', version: entry.version, retired: true}); + continue; + } outcomes.push(entry.version === pack.version ? {name: pack.name, action: 'current', version: entry.version} : {name: pack.name, action: 'upgraded', version: pack.version, from: entry.version}); @@ -408,44 +363,12 @@ const run_flat = async(opts: Flat_opts): Promise=>{ return {...base, packs: outcomes, status: status_of(outcomes)}; } - // Every other operation touches the filesystem, so a host with no - // directory configured for this scope (a native host under `user` scope) - // is reported, not crashed on. const target_root = skills_target(host.def, scope, home, cwd); - if (!target_root) - { - return { - ...base, - status: 'skipped', - reason: 'no-skills-dir', - detail: `${host.def.label} has no ${scope} skills directory`, - }; - } if (operation === 'remove') { - // Reverse dependency order, and — since delete_files can now report a - // file it could not remove — the same transposed guard as - // adapter-native.ts: a dependency is never dropped once a pack that - // depends on it failed to be removed, so no host is left holding an - // adapter with no core. Reverse order means every dependent has - // already been visited, so the block propagates down the chain. - const failed_names = new Set(); - const blocked_names = new Set(); - const kept_names = new Set(); - for (const pack of [...packs].reverse()) + for (const pack of packs) { - const blocker = packs.find(p=>p.dependencies.includes(pack.name) - && (failed_names.has(p.name) || blocked_names.has(p.name))); - if (blocker) - { - blocked_names.add(pack.name); - if (entry_for(pack.name)) - { - kept_names.add(pack.name); - } - continue; - } const entry = entry_for(pack.name); if (!entry) { @@ -464,24 +387,23 @@ const run_flat = async(opts: Flat_opts): Promise=>{ { // The entry stays: forgetting it would strand whatever is // still on disk with nothing left tracking it. - failed_names.add(pack.name); outcomes.push({name: pack.name, action: 'failed', detail: refusal}); continue; } forget_for(pack.name); outcomes.push({name: pack.name, action: 'removed', version: entry.version}); } - return {...base, packs: outcomes, status: status_of(outcomes), hint: kept_hint(kept_names)}; + return {...base, packs: outcomes, status: status_of(outcomes)}; } - // install and update both need the repository contents. update only touches - // packs the journal already knows about. + // install and update both copy. update only touches packs the host + // already has: a journal entry, or the old plugin this copy replaces. const targets = operation === 'update' - ? packs.filter(p=>entry_for(p.name)) + ? packs.filter(p=>entry_for(p.name) || adopt[p.name] !== undefined) : packs; const pending = targets.filter(p=>{ const entry = entry_for(p.name); - return operation === 'update' || !entry || !entry.complete || entry.version !== p.version + return !entry || !entry.complete || entry.version !== p.version || !entry_files_present(entry, canonicalise); }); for (const pack of targets) @@ -491,6 +413,14 @@ const run_flat = async(opts: Flat_opts): Promise=>{ outcomes.push({name: pack.name, action: 'current', version: pack.version}); } } + // The version the host had before this copy: our own complete copy's, or + // the old plugin's this copy replaces. + const from_for = (pack_name: string): {from?: string; repaired: boolean}=>{ + const previous = previous_for(pack_name); + return previous + ? {from: previous.version, repaired: !previous.complete} + : {from: adopt[pack_name], repaired: false}; + }; if (!pending.length) { return {...base, packs: outcomes}; @@ -499,63 +429,33 @@ const run_flat = async(opts: Flat_opts): Promise=>{ { for (const pack of pending) { - outcomes.push(copied_outcome(pack.name, pack.version, previous_for(pack.name))); + outcomes.push(copied_outcome(pack.name, pack.version, from_for(pack.name).from)); } return {...base, packs: outcomes}; } - let cloned: Clone_result; - try { - cloned = await clone({ref, run, tmp_root}); - } catch (error) { - return { - ...base, - status: 'failed', - reason: 'clone-failed', - detail: (error as Error).message, - hint: 'install git (the flat-directory install clones the skills repository), then re-run', - }; - } - // Stamped only now that a clone actually happened this run — every - // return past this point reports the commit this run cloned, never a - // journal entry from some earlier run or a sibling host. - const cloned_base: Host_outcome = {...base, commit: cloned.commit}; - - // A per-host filesystem failure here (a read-only destination, a corrupt - // clone layout, a journal write error) must become a Host_outcome, never - // a rejected promise — one host failing must never abort the others, and - // any pack already installed and journaled before the failure still counts. - // - // A pack whose dependency failed (or was itself blocked) must never be - // attempted — mirrors adapter-native.ts's failed_names/blocked_names, so - // the invariant "never reply-adapter without ai-sdr-core" holds the same - // way regardless of which adapter is doing the installing. - const failed_names = new Set(); - const blocked_names = new Set(); + // A per-host filesystem failure here (a read-only destination, a package + // missing its pack, a journal write error) must become a Host_outcome, + // never a rejected promise — one host failing must never abort the + // others, and any pack already installed and journaled before the failure + // still counts. try { for (const pack of pending) { - const blocker = pack.dependencies.find(d=>failed_names.has(d) || blocked_names.has(d)); - if (blocker) - { - blocked_names.add(pack.name); - continue; - } - const from = path.join(cloned.dir, 'plugins', pack.name, 'skills'); const previous = entry_for(pack.name); - const previously_installed = previous_for(pack.name); + const {from, repaired} = from_for(pack.name); const elsewhere = others_claim(pack.name); const known_files = previous ? [...previous.files.map(f=>path.resolve(f)), ...elsewhere] : [...elsewhere]; - const skill_dirs = fs.readdirSync(from, {withFileTypes: true}).filter(e=>e.isDirectory()); + const pack_source = path.join(source, pack.name); + const skill_dirs = fs.readdirSync(pack_source, {withFileTypes: true}).filter(e=>e.isDirectory()); const collision = skill_dirs.find(skill=>{ const dst_dir = path.join(target_root, skill.name); return fs.existsSync(dst_dir) && !owns_dir(dst_dir, known_files, canonicalise); }); if (collision) { - failed_names.add(pack.name); outcomes.push({ name: pack.name, action: 'failed', @@ -574,7 +474,7 @@ const run_flat = async(opts: Flat_opts): Promise=>{ try { for (const skill of skill_dirs) { - copy_dir(path.join(from, skill.name), path.join(target_root, skill.name), written); + copy_dir(path.join(pack_source, skill.name), path.join(target_root, skill.name), written); } } catch (copy_error) { // Whatever landed before the failure — possibly nothing — is @@ -582,44 +482,35 @@ const run_flat = async(opts: Flat_opts): Promise=>{ // alone must never read as installed when the copy did not // finish, or `install`'s own hint to re-run would do nothing. record_for(pack.name, { - version: pack.version, ref, commit: cloned.commit, scope, + version: pack.version, scope, files: written, complete: false, installed_at: new Date().toISOString(), }); throw copy_error; } record_for(pack.name, { version: pack.version, - ref, - commit: cloned.commit, scope, files: written, complete: true, installed_at: new Date().toISOString(), }); - outcomes.push(copied_outcome(pack.name, pack.version, previously_installed, cloned.commit)); + outcomes.push(copied_outcome(pack.name, pack.version, from, repaired)); } } catch (error) { // outcomes.length is not "something landed" — every entry pushed so // far could itself be a collision failure, so check the actions. const landed = outcomes.some(p=>p.action !== 'failed'); return { - ...cloned_base, + ...base, status: landed ? 'partial' : 'failed', packs: outcomes, reason: 'copy-failed', detail: (error as Error).message, - hint: blocked_hint(blocked_names) ?? 'check filesystem permissions for the skills directory, then re-run', + hint: 'check filesystem permissions for the skills directory, then re-run', }; - } finally { - try { - fs.rmSync(cloned.dir, {recursive: true, force: true}); - } catch { - // Best-effort cleanup of the clone's temp directory — never masks - // the result computed above. - } } - return {...cloned_base, packs: outcomes, status: status_of(outcomes), hint: blocked_hint(blocked_names)}; + return {...base, packs: outcomes, status: status_of(outcomes)}; }; -export {canonical, clone_repo, copy_dir, skills_target, run_flat}; -export type {Clone_fn, Clone_result, Flat_opts}; +export {canonical, copy_dir, skills_target, status_of, run_flat}; +export type {Flat_opts}; diff --git a/src/skills/adapter-native.ts b/src/skills/adapter-native.ts deleted file mode 100644 index c64f87f..0000000 --- a/src/skills/adapter-native.ts +++ /dev/null @@ -1,422 +0,0 @@ -import {execFile} from 'child_process'; -import {MARKETPLACE, REPO} from './packs'; -import type {Detected_host} from './detect'; -import type {Host_outcome, Operation, Pack, Pack_outcome, Runner, Run_result, Scope} from './types'; - -// Drives a host's own plugin CLI rather than copying files, so Claude Code's -// marketplace update channel keeps working and Codex installs natively. - -const default_runner: Runner = (bin, args)=>new Promise(resolve=>{ - execFile(bin, args, {encoding: 'utf8', windowsHide: true}, (error, stdout, stderr)=>{ - const code = error && typeof (error as {code?: unknown}).code === 'number' - ? (error as unknown as {code: number}).code - : (error ? 1 : 0); - resolve({code, stdout: stdout ?? '', stderr: stderr ?? ''}); - }); -}); - -// Returns {ok: false, detail} if the listing failed or is unparseable. -// Returns {ok: true, versions} with only plugins from MARKETPLACE if the listing succeeded. -// Both hosts print a JSON listing, with different envelopes: Claude Code uses -// {plugins:[…]}, Codex uses {installed:[…]}. Rows carry marketplace metadata -// ('marketplace' for Claude Code, 'marketplaceName' for Codex) — only rows -// matching MARKETPLACE are included. -type Listing_result = {ok: true; versions: Record} | {ok: false; detail?: string}; - -const installed_versions = async(host: Detected_host, run: Runner): Promise=>{ - const bin = host.bin as string; - const result = await run(bin, host.def.cli!.list_json()); - if (result.code !== 0) - { - return {ok: false, detail: (result.stderr || result.stdout).trim()}; - } - let parsed: unknown; - try { - parsed = JSON.parse(result.stdout); - } catch { - return {ok: false}; - } - // Claude Code returns an array directly; older versions wrapped it in {plugins:[…]}. - // Codex wraps it in {installed:[…]}. - const doc = (parsed ?? {}) as Record; - const rows = Array.isArray(parsed) - ? parsed - : [doc.plugins, doc.installed].find(Array.isArray) as Record[] | undefined; - const out: Record = {}; - for (const row of rows ?? []) - { - // Claude Code uses 'id' (e.g. "agentic-runtime@reply-skills") instead of 'name'. - // Extract name from id if present, falling back to name field. - let name = (row.name ?? row.id) as string | undefined; - if (name && name.includes('@')) - { - const id_parts = name.split('@'); - const pack_name = id_parts[0]; - const marketplace = id_parts[1]; - // Only accept if marketplace matches or is empty - if (marketplace === MARKETPLACE || marketplace === undefined) - { - name = pack_name; - } - else - { - continue; - } - } - const version = row.version; - // Check marketplace: accept rows that declare MARKETPLACE, or rows with no marketplace field. - const marketplace = (row.marketplace ?? row.marketplaceName) as string | undefined; - if (typeof name === 'string' && typeof version === 'string') - { - // If marketplace is declared, it must match MARKETPLACE; if not declared, accept it. - if (marketplace === undefined || marketplace === MARKETPLACE) - { - out[name] = version; - } - } - } - return {ok: true, versions: out}; -}; - -type Native_opts = { - operation: Operation; - host: Detected_host; - packs: Pack[]; - scope: Scope; - run?: Runner; - dry_run?: boolean; -}; - -const skipped = (host: Detected_host): Host_outcome=>({ - host: host.def.id, - label: host.def.label, - kind: host.def.kind, - status: 'skipped', - reason: 'cli-not-resolved', - detail: `${host.def.label} config found at ${host.config_dir} but its CLI could not be resolved`, - hint: `add ${host.def.binaries[0]} to PATH, then re-run`, -}); - -const status_of = (packs: Pack_outcome[]): Host_outcome['status']=>{ - const failed = packs.filter(p=>p.action === 'failed'); - if (!failed.length) - { - return 'ok'; - } - return failed.length === packs.length ? 'failed' : 'partial'; -}; - -// The two dependency guards report the same way: name the packs the guard held -// back, so the user is told what is still to do rather than left to infer it. -// Install refuses a pack whose dependency failed; remove refuses a pack whose -// dependent failed. adapter-flat.ts carries the same pair verbatim — the two -// adapters are twin implementations of one rule, like status_of above. -const blocked_hint = (names: Iterable): string | undefined=>{ - const list = [...names]; - return list.length - ? `packs ${list.join(', ')} were not attempted because their dependencies failed; fix those installs and re-run` - : undefined; -}; - -const kept_hint = (names: Iterable): string | undefined=>{ - const list = [...names]; - return list.length - ? `packs ${list.join(', ')} were kept because packs that depend on them could not be removed; fix those removals and re-run` - : undefined; -}; - -// A version that did not move is `current`, never `upgraded`. Every update -// path in both adapters answers this question through a helper like this one, -// so one machine can never report "already current" and "updated 0.1.0 → -// 0.1.0" for the same fact side by side. -const updated_outcome = (name: string, from: string, to: string): Pack_outcome=> - from === to - ? {name, action: 'current', version: to} - : {name, action: 'upgraded', version: to, from}; - -const run_native = async(opts: Native_opts): Promise=>{ - const {operation, host, packs, scope} = opts; - const run = opts.run ?? default_runner; - const dry_run = opts.dry_run === true; - const base: Host_outcome = { - host: host.def.id, label: host.def.label, kind: host.def.kind, scope, status: 'ok', - }; - if (!host.bin) - { - return skipped(host); - } - const cli = host.def.cli!; - - // Registering the marketplace is the precondition for every mutating - // operation; it is idempotent on both hosts. - if ((operation === 'install' || operation === 'update') && !dry_run) - { - const added = await run(host.bin, cli.marketplace_add(REPO)); - if (added.code !== 0) - { - return { - ...base, - status: 'failed', - reason: 'marketplace-add-failed', - detail: (added.stderr || added.stdout).trim(), - hint: `run \`${host.def.binaries[0]} ${cli.marketplace_add(REPO).join(' ')}\` manually to see why`, - }; - } - } - - const listing = await installed_versions(host, run); - const outcomes: Pack_outcome[] = []; - - if (operation === 'list') - { - if (!listing.ok) - { - return { - ...base, - status: 'failed', - reason: 'list-failed', - detail: listing.detail || 'failed to list installed plugins', - hint: `run \`${host.def.binaries[0]} ${cli.list_json().join(' ')}\` manually to see why`, - }; - } - const installed = listing.versions; - for (const pack of packs) - { - const have = installed[pack.name]; - if (!have) - { - continue; - } - outcomes.push(have === pack.version - ? {name: pack.name, action: 'current', version: have} - : {name: pack.name, action: 'upgraded', version: pack.version, from: have}); - } - return {...base, packs: outcomes}; - } - - if (operation === 'remove') - { - if (!listing.ok) - { - return { - ...base, - status: 'failed', - reason: 'list-failed', - detail: listing.detail || 'failed to list installed plugins', - hint: `run \`${host.def.binaries[0]} ${cli.list_json().join(' ')}\` manually to see why`, - }; - } - const installed = listing.versions; - // Reverse dependency order: a dependent never outlives its dependency. - // Ordering alone is not enough, though — if a dependent's removal - // fails, removing its dependency anyway leaves the host holding an - // adapter with no core, the one state this installer exists to - // prevent. So the install guard below is mirrored here, transposed: - // install refuses a pack whose dependency failed, remove refuses a - // pack whose dependent did. Reverse order means every dependent has - // already been visited by the time its dependency comes up, so the - // block propagates transitively down the chain. - const failed_names = new Set(); - const blocked_names = new Set(); - const kept_names = new Set(); - for (const pack of [...packs].reverse()) - { - const blocker = packs.find(p=>p.dependencies.includes(pack.name) - && (failed_names.has(p.name) || blocked_names.has(p.name))); - if (blocker) - { - blocked_names.add(pack.name); - // Only a pack that is actually here is "kept" — blocking one - // the host never had is bookkeeping for the chain, not news. - if (installed[pack.name]) - { - kept_names.add(pack.name); - } - continue; - } - if (!installed[pack.name]) - { - continue; - } - if (dry_run) - { - outcomes.push({name: pack.name, action: 'removed', version: installed[pack.name]}); - continue; - } - const result = await run(host.bin, cli.remove(pack.name, MARKETPLACE)); - if (result.code !== 0) - { - failed_names.add(pack.name); - outcomes.push({name: pack.name, action: 'failed', detail: (result.stderr || result.stdout).trim()}); - continue; - } - outcomes.push({name: pack.name, action: 'removed', version: installed[pack.name]}); - } - return {...base, packs: outcomes, status: status_of(outcomes), hint: kept_hint(kept_names)}; - } - - if (operation === 'update') - { - if (!listing.ok) - { - return { - ...base, - status: 'failed', - reason: 'list-failed', - detail: listing.detail || 'failed to list installed plugins', - hint: `run \`${host.def.binaries[0]} ${cli.list_json().join(' ')}\` manually to see why`, - }; - } - const installed = listing.versions; - const pre_update_versions = new Map(Object.entries(installed)); - - // Deduplicate updates: if update_scope is 'marketplace', run once and apply to all packs. - if (cli.update_scope === 'marketplace') - { - const installed_packs = packs.filter(p=>installed[p.name]); - if (installed_packs.length > 0) - { - if (dry_run) - { - for (const pack of installed_packs) - { - outcomes.push(updated_outcome(pack.name, installed[pack.name], pack.version)); - } - } - else - { - // Run the marketplace-wide update once - const result = await run(host.bin, cli.update(installed_packs[0].name, MARKETPLACE)); - if (result.code === 0) - { - // Re-read listing to get actual versions. A whole- - // marketplace upgrade exits 0 whether or not any pack - // moved, so the post-update versions — not the exit - // code — decide between `upgraded` and `current`. - const post_listing = await installed_versions(host, run); - if (post_listing.ok) - { - const post_installed = post_listing.versions; - for (const pack of installed_packs) - { - const have = pre_update_versions.get(pack.name); - outcomes.push(updated_outcome( - pack.name, have ?? '', post_installed[pack.name] ?? pack.version, - )); - } - } - else - { - // Re-read failed; use target version from registry - for (const pack of installed_packs) - { - const have = pre_update_versions.get(pack.name); - outcomes.push(updated_outcome(pack.name, have ?? '', pack.version)); - } - } - } - else - { - // Update failed; report all packs as failed with the same detail - for (const pack of installed_packs) - { - outcomes.push({name: pack.name, action: 'failed', detail: (result.stderr || result.stdout).trim()}); - } - } - } - } - } - else - { - // Per-pack updates (Claude Code) - for (const pack of packs) - { - const have = installed[pack.name]; - if (!have) - { - continue; - } - // Check if already at target version - if (have === pack.version) - { - outcomes.push({name: pack.name, action: 'current', version: have}); - continue; - } - if (dry_run) - { - outcomes.push({name: pack.name, action: 'upgraded', version: pack.version, from: have}); - continue; - } - const result = await run(host.bin, cli.update(pack.name, MARKETPLACE)); - if (result.code === 0) - { - // Re-read listing to get actual version. `plugin update` - // can exit 0 without moving the version, so this reports - // `current` rather than `upgraded 0.1.0 -> 0.1.0`. - const post_listing = await installed_versions(host, run); - if (post_listing.ok) - { - outcomes.push(updated_outcome( - pack.name, have, post_listing.versions[pack.name] ?? pack.version, - )); - } - else - { - // Re-read failed; use target version from registry - outcomes.push(updated_outcome(pack.name, have, pack.version)); - } - } - else - { - outcomes.push({name: pack.name, action: 'failed', detail: (result.stderr || result.stdout).trim()}); - } - } - } - return {...base, packs: outcomes, status: status_of(outcomes)}; - } - - // install — dependency order, and a failed dependency stops its dependents - // so the host is never left with an adapter and no core. Track both failed - // and blocked packs to handle transitive dependency chains. - const installed = listing.ok ? listing.versions : {}; - const failed_names = new Set(); - const blocked_names = new Set(); - for (const pack of packs) - { - const blocker = pack.dependencies.find(d=>failed_names.has(d) || blocked_names.has(d)); - if (blocker) - { - blocked_names.add(pack.name); - continue; - } - const have = installed[pack.name]; - if (have === pack.version) - { - outcomes.push({name: pack.name, action: 'current', version: have}); - continue; - } - const action: Pack_outcome['action'] = have ? 'upgraded' : 'installed'; - if (dry_run) - { - outcomes.push(have - ? {name: pack.name, action, version: pack.version, from: have} - : {name: pack.name, action, version: pack.version}); - continue; - } - const result = await run(host.bin, cli.install(pack.name, MARKETPLACE, scope)); - if (result.code !== 0) - { - failed_names.add(pack.name); - outcomes.push({name: pack.name, action: 'failed', detail: (result.stderr || result.stdout).trim()}); - continue; - } - outcomes.push(have - ? {name: pack.name, action, version: pack.version, from: have} - : {name: pack.name, action, version: pack.version}); - } - - return {...base, packs: outcomes, status: status_of(outcomes), hint: blocked_hint(blocked_names)}; -}; - -export {default_runner, installed_versions, run_native}; -export type {Native_opts}; diff --git a/src/skills/detect.ts b/src/skills/detect.ts index 9b6265c..e195ade 100644 --- a/src/skills/detect.ts +++ b/src/skills/detect.ts @@ -7,8 +7,9 @@ import type {Host_def} from './types'; type Detected_host = { def: Host_def; - // Resolved binary for a native host; undefined means "present but not - // runnable", which the adapter turns into an actionable skip. + // Resolved binary of a host's plugin CLI; undefined means the plugins an + // earlier version installed there cannot be reached this run. The copy + // itself never needs it. bin?: string; config_dir: string; }; @@ -89,9 +90,8 @@ const resolve_bin = (def: Host_def, deps: Detect_deps): string | undefined=>{ return undefined; }; -// Presence is decided by the host's configuration directory. A native host -// whose binary cannot be resolved is still detected — that is a fixable -// situation the user needs to hear about, not an absence. +// Presence is decided by the host's configuration directory. A host whose +// binary cannot be resolved is still detected: the copy needs no binary. const detect_hosts = (deps: Detect_deps = default_detect_deps()): Detected_host[]=>{ const found: Detected_host[] = []; for (const def of HOSTS) diff --git a/src/skills/hosts.ts b/src/skills/hosts.ts index ee42d95..06840e7 100644 --- a/src/skills/hosts.ts +++ b/src/skills/hosts.ts @@ -1,6 +1,6 @@ import path from 'path'; import {UsageError} from '../utils/errors'; -import type {Host_cli, Host_def} from './types'; +import type {Host_def, Plugin_cli} from './types'; // One entry per assistant. Adding a host is a data change plus a verification // run — never a branch inside an adapter. `verified: false` means the paths come @@ -9,34 +9,33 @@ import type {Host_cli, Host_def} from './types'; // {home} in binary_paths is expanded by detect.ts; a leading '~/' is not used // so the strings stay platform-agnostic. -const claude_cli: Host_cli = { - marketplace_add: (repo)=>['plugin', 'marketplace', 'add', repo], +// Claude Code and Codex keep a plugin CLI, which an earlier version of this +// CLI installed through; it is only asked to list and remove those plugins. +// Claude Code's uninstall acts on user scope unless told another one. +const claude_cli: Plugin_cli = { list_json: ()=>['plugin', 'list', '--json'], - install: (pack, marketplace, scope)=>['plugin', 'install', `${pack}@${marketplace}`, '--scope', scope], - update: (pack, marketplace)=>['plugin', 'update', `${pack}@${marketplace}`], - remove: (pack, marketplace)=>['plugin', 'uninstall', `${pack}@${marketplace}`], - update_scope: 'pack', + remove: (id, scope)=>scope === 'project' + ? ['plugin', 'uninstall', id, '--scope', 'project'] + : ['plugin', 'uninstall', id], }; // Codex spells the same operations differently and takes --json on all of them. -const codex_cli: Host_cli = { - marketplace_add: (repo)=>['plugin', 'marketplace', 'add', repo, '--json'], +const codex_cli: Plugin_cli = { list_json: ()=>['plugin', 'list', '--json'], - install: (pack, marketplace)=>['plugin', 'add', `${pack}@${marketplace}`, '--json'], - update: (_pack, marketplace)=>['plugin', 'marketplace', 'upgrade', marketplace, '--json'], - remove: (pack, marketplace)=>['plugin', 'remove', `${pack}@${marketplace}`, '--json'], - update_scope: 'marketplace', + remove: (id)=>['plugin', 'remove', id, '--json'], }; const HOSTS: Host_def[] = [ { id: 'claude-code', label: 'Claude Code', - kind: 'native-plugin', + kind: 'flat-skills-dir', config_dirs: ['.claude'], binaries: ['claude'], binary_paths: [], - cli: claude_cli, + plugin_cli: claude_cli, + // Its personal and project skills directories, per its skills page. + user_skills_dir: path.join('.claude', 'skills'), project_skills_dir: path.join('.claude', 'skills'), needs_new_session: true, verified: true, @@ -44,15 +43,16 @@ const HOSTS: Host_def[] = [ { id: 'codex', label: 'Codex', - kind: 'native-plugin', + kind: 'flat-skills-dir', config_dirs: ['.codex'], binaries: ['codex'], // Windows ships Codex with the desktop app, off PATH; the hash segment // varies, so detect.ts globs one level. binary_paths: [path.join('{home}', 'AppData', 'Local', 'OpenAI', 'Codex', 'bin', '*', 'codex.exe')], - cli: codex_cli, - // Codex's plugin mechanism is user-scoped, so --project falls back to - // copying into the repository's .agents/skills. + plugin_cli: codex_cli, + // Its user directory is $HOME/.agents/skills, and in a repository it + // reads .agents/skills from the working directory up to the root. + user_skills_dir: path.join('.agents', 'skills'), project_skills_dir: path.join('.agents', 'skills'), needs_new_session: true, verified: true, diff --git a/src/skills/journal.ts b/src/skills/journal.ts index e92ba3f..5cd8807 100644 --- a/src/skills/journal.ts +++ b/src/skills/journal.ts @@ -5,14 +5,15 @@ import {RuntimeError} from '../utils/errors'; import type {Env} from '../config'; import type {Scope} from './types'; -// Installer-side state, and only for flat-directory hosts: native hosts are -// asked directly (`plugin list --json`), so there is no second copy of the -// truth to drift. This records what we wrote so `update` is idempotent and -// `remove` deletes our files and nothing else. +// Installer-side state: what we wrote into each host's skills directory, so +// `update` is idempotent and `remove` deletes our files and nothing else. type Journal_entry = { version: string; - ref: string; + // Written by earlier versions, which copied the packs from a repository: + // the ref and commit they copied. Read and tolerated, never written now; + // the version alone says what a copy from the package is. + ref?: string; commit?: string; scope: Scope; // The resolved project root a project-scope entry belongs to. The key diff --git a/src/skills/orchestrate.ts b/src/skills/orchestrate.ts index 261b555..dfa9dcb 100644 --- a/src/skills/orchestrate.ts +++ b/src/skills/orchestrate.ts @@ -1,31 +1,30 @@ -import os from 'os'; -import {run_flat, type Clone_fn} from './adapter-flat'; -import {run_native} from './adapter-native'; -import {default_detect_deps, select_hosts, type Detect_deps} from './detect'; +import {run_flat, status_of} from './adapter-flat'; +import {default_detect_deps, select_hosts, type Detect_deps, type Detected_host} from './detect'; import {host_ids} from './hosts'; import {read_journal} from './journal'; -import {DEFAULT_REF, REPO, load_packs, resolve_packs} from './packs'; +import {PACK_NAME, RETIRED_PACKS, plugin_id, resolve_packs} from './packs'; +import {default_runner, old_plugins, remove_plugin} from './plugins'; import {summarize} from './report'; -import {UsageError} from '../utils/errors'; +import {cli_version} from '../config'; import type {Env} from '../config'; import type { - Host_def, Host_outcome, Operation, Orphaned_packs, Pack, Report, Runner, Scope, + Host_def, Host_outcome, Operation, Orphaned_packs, Pack, Pack_outcome, Report, Runner, Scope, } from './types'; -// The one flow all four commands share: detect hosts, resolve packs in -// dependency order, run the right adapter per host, collect outcomes. Every -// external dependency is injectable so the whole thing is testable offline. +// The one flow all four commands share: detect hosts, resolve the pack, copy +// it into each host, and reach the plugins an earlier version installed +// through a host's own CLI. Every external dependency is injectable so the +// whole thing is testable offline. type Skills_deps = { detect?: Detect_deps; run?: Runner; - clone?: Clone_fn; home?: string; cwd?: string; - tmp_root?: string; env?: Env; - fetch_impl?: typeof fetch; - ref?: string; + // The directory holding each pack's directory; the package's own + // `skills` by default. + source?: string; }; type Skills_opts = { @@ -37,35 +36,6 @@ type Skills_opts = { deps?: Skills_deps; }; -// A dependency may not be removed while something that needs it could stay -// behind: that is exactly the adapter-without-core state the installer exists to -// avoid. Deliberately conservative — it refuses based on the dependency graph -// alone, without first asking every host what it has installed. A selective -// removal is the rare path, the fix is one flag away, and being wrong in this -// direction only costs an extra keystroke, while being wrong in the other -// direction breaks a working assistant. -const guard_remove = (packs: Pack[], all: Pack[]): void=>{ - const going = new Set(packs.map(p=>p.name)); - for (const pack of all) - { - if (going.has(pack.name)) - { - continue; - } - const needed = pack.dependencies.filter(d=>going.has(d)); - if (needed.length) - { - throw new UsageError( - `${pack.name} depends on ${needed.join(', ')}; removing it alone can leave that pack broken.`, - { - code: 'usage.skills_remove', - hint: `remove ${pack.name} too, or run \`reply skills remove\` to remove everything`, - }, - ); - } - } -}; - const not_detected = (def: Host_def): Host_outcome=>({ host: def.id, label: def.label, kind: def.kind, status: 'skipped', reason: 'not-detected', detail: `${def.label} was requested with --agent but is not installed on this machine`, @@ -105,45 +75,112 @@ const orphaned_packs = (env?: Env): Orphaned_packs[]=>{ return orphans; }; -const run_skills = async(opts: Skills_opts): Promise=>{ +// Whether this run can ask the host's own CLI about the plugins an earlier +// version installed: the host has one, it resolved, and its plugins live in +// the scope this run acts on (Codex's are user-scoped only). +const reaches_plugins = (host: Detected_host, scope: Scope): boolean=> + !!host.def.plugin_cli && !!host.bin && !(scope === 'project' && host.def.id === 'codex'); + +// The plugin rows `list` adds beside the copies, under the plugin's own id. +const listed_plugins = (packs: Pack[], plugins: Record): Pack_outcome[]=>packs + .filter(pack=>plugins[pack.name] !== undefined) + .map(pack=>{ + const name = plugin_id(pack.name); + const version = plugins[pack.name]; + if (pack.retired) + { + return {name, action: 'current', version, retired: true}; + } + return version === pack.version + ? {name, action: 'current', version} + : {name, action: 'upgraded', version: pack.version, from: version}; + }); + +const run_host = async( + opts: Skills_opts, + host: Detected_host, + packs: Pack[], + scope: Scope, + detect: Detect_deps, +): Promise=>{ const deps = opts.deps ?? {}; - const detect = deps.detect ?? default_detect_deps(); - const ref = deps.ref ?? DEFAULT_REF; - const registry = await load_packs({ref, fetch_impl: deps.fetch_impl}); - // Install and update pull dependencies; remove must not — see resolve_packs. - const packs = resolve_packs(opts.requested, registry, { - dependencies: opts.operation !== 'remove', + const run = deps.run ?? default_runner; + const {operation, dry_run} = opts; + const listing = reaches_plugins(host, scope) ? await old_plugins(host, run, scope) : undefined; + const plugins = listing?.ok ? listing.versions : {}; + const copying = operation === 'install' || operation === 'update'; + const adopt: Record = copying && plugins[PACK_NAME] !== undefined + ? {[PACK_NAME]: plugins[PACK_NAME]} + : {}; + + const outcome = await run_flat({ + operation, host, packs, scope, dry_run, adopt, + home: deps.home ?? detect.home, cwd: deps.cwd, env: deps.env, source: deps.source, }); - const scope: Scope = opts.project ? 'project' : 'user'; + const rows = [...outcome.packs ?? []]; + const extra: Partial = {}; + + if (copying) + { + // The old plugin goes only once the copy that replaces it is in + // place, so a refused or failed copy never leaves the host with + // neither. + const copied = rows.find(p=>p.name === PACK_NAME); + if (plugins[PACK_NAME] !== undefined && copied && copied.action !== 'failed') + { + const id = plugin_id(PACK_NAME); + const removed = dry_run ? {ok: true as const} : await remove_plugin(host, run, id, scope); + extra.old_plugin = removed.ok + ? {id, action: 'removed'} + : {id, action: 'failed', detail: removed.detail}; + } + const retired = RETIRED_PACKS.filter(name=>plugins[name] !== undefined).map(plugin_id); + if (retired.length) + { + extra.retired_plugins = retired; + } + } + else if (operation === 'list') + { + rows.push(...listed_plugins(packs, plugins)); + } + else + { + for (const pack of packs.filter(p=>plugins[p.name] !== undefined)) + { + const id = plugin_id(pack.name); + const removed = dry_run ? {ok: true as const} : await remove_plugin(host, run, id, scope); + rows.push(removed.ok + ? {name: id, action: 'removed', version: plugins[pack.name]} + : {name: id, action: 'failed', detail: removed.detail}); + } + } - if (opts.operation === 'remove' && opts.requested.length) + if (listing && !listing.ok && !outcome.hint) { - guard_remove(packs, registry.packs); + extra.hint = `${host.def.label} did not list its plugins (${listing.detail}), so a` + + ` ${plugin_id(PACK_NAME)} plugin an earlier version installed, if there is one, was not reached`; } + // A copy that failed outright keeps its own status; anything else is + // recomputed over the plugin rows too. + const status = outcome.reason ? outcome.status : status_of(rows); + return {...outcome, ...extra, packs: rows, status}; +}; + +const run_skills = async(opts: Skills_opts): Promise=>{ + const deps = opts.deps ?? {}; + const detect = deps.detect ?? default_detect_deps(); + const packs = resolve_packs(opts.requested, opts.operation); + const scope: Scope = opts.project ? 'project' : 'user'; const {selected, missing} = select_hosts(opts.agents, detect); const hosts: Host_outcome[] = []; for (const host of selected) { - // A native host under --project falls back to the flat adapter only - // when its plugin mechanism cannot express project scope; Claude Code - // can, Codex cannot. - const native = host.def.kind === 'native-plugin' - && !(scope === 'project' && host.def.id === 'codex'); let outcome: Host_outcome; try { - outcome = native - ? await run_native({ - operation: opts.operation, host, packs, scope, - run: deps.run, dry_run: opts.dry_run, - }) - : await run_flat({ - operation: opts.operation, host, packs, scope, ref, - run: deps.run, clone: deps.clone, dry_run: opts.dry_run, - home: deps.home ?? detect.home, cwd: deps.cwd, - tmp_root: deps.tmp_root ?? os.tmpdir(), env: deps.env, - }); + outcome = await run_host(opts, host, packs, scope, detect); } catch (error) { // An adapter is expected to turn every failure it knows about // into a Host_outcome; this is the backstop for the ones it @@ -171,37 +208,21 @@ const run_skills = async(opts: Skills_opts): Promise=>{ hosts.push(not_detected(def)); } - // The commit is only known when this run itself cloned something: a flat - // host stamps its own outcome with the commit it cloned (see - // adapter-flat.ts), and only then — never on a native host, a skip, or a - // failure that never reached a clone. Reading it off the outcomes (rather - // than the journal) means a stale entry from an earlier run, or one that - // belongs to a different host, can never be attributed to this run. If - // flat hosts somehow disagree — cloning at different moments within the - // same run — no commit is reported rather than an arbitrary one. - const commits = new Set(hosts.map(h=>h.commit).filter((c): c is string=>!!c)); - const commit = commits.size === 1 ? [...commits][0] : undefined; - - // `requested` is what the user asked for in canonical form; `resolved` is - // that plus dependencies. Both are reported so an agent sees the pull - // without parsing prose. resolve_packs puts dependencies first, so the - // requested pack itself is always the last element. - const canonical = opts.requested.map(r=>resolve_packs([r], registry).slice(-1)[0].name); - // `list` alone: it answers "what is installed where". The other operations // act on hosts, and can do nothing about one they no longer know. const orphans = opts.operation === 'list' ? orphaned_packs(deps.env) : []; + const names = packs.map(p=>p.name); return { action: opts.operation, - source: commit ? {repo: REPO, ref, commit} : {repo: REPO, ref}, - requested: opts.requested.length ? canonical : packs.map(p=>p.name), - resolved: packs.map(p=>p.name), + source: {version: cli_version()}, + requested: names, + resolved: names, hosts, summary: summarize(hosts, opts.operation), ...(orphans.length ? {orphans} : {}), }; }; -export {guard_remove, run_skills}; +export {run_skills}; export type {Skills_deps, Skills_opts}; diff --git a/src/skills/packs.ts b/src/skills/packs.ts index ba5a3b7..8188906 100644 --- a/src/skills/packs.ts +++ b/src/skills/packs.ts @@ -1,174 +1,82 @@ -import {UsageError, RuntimeError} from '../utils/errors'; -import type {Pack, Pack_registry} from './types'; +import path from 'path'; +import {cli_version} from '../config'; +import {UsageError} from '../utils/errors'; +import type {Operation, Pack} from './types'; -// Identity of the knowledge repository. packs.json in that repo is the -// host-neutral source of truth for pack identity and the dependency graph; -// PACKS_FALLBACK is a build-time copy so `install` still works offline. -const REPO = 'reply-team/reply-skills'; -const MARKETPLACE = 'reply-skills'; -const DEFAULT_REF = 'main'; +// The one pack this CLI ships: Reply's own skills, carried in the package +// beside dist/ and installed at the CLI's own version, so a skill that +// describes a release's commands is released with them. +const PACK_NAME = 'reply-adapter'; const ALIASES: Record = { - core: 'ai-sdr-core', - adapter: 'reply-adapter', - runtime: 'agentic-runtime', + adapter: PACK_NAME, }; -const PACKS_FALLBACK: Pack_registry = { - marketplace: MARKETPLACE, - packs: [ - { - name: 'ai-sdr-core', - display_name: 'AI SDR Core', - version: '0.1.0', - description: 'Vendor-neutral AI SDR expertise: the operation contract, playbooks and guardrails.', - dependencies: [], - }, - { - name: 'reply-adapter', - display_name: 'Reply.io Adapter', - version: '0.1.0', - description: 'Executes the AI SDR Core contract against Reply.io: CLI, API v3, MCP, auth.', - dependencies: ['ai-sdr-core'], - }, - { - name: 'agentic-runtime', - display_name: 'Agentic Runtime', - version: '0.1.0', - description: 'Durable multi-session work: plans, work items, checkpoints, reports, memory.', - dependencies: ['ai-sdr-core'], - }, - ], +// Packs an earlier version of this CLI installed and this one no longer +// offers, under every name it accepted for them. `list` and `remove` still +// reach what was installed under them; `install` and `update` refuse them. +const RETIRED: Record = { + 'core': 'ai-sdr-core', + 'ai-sdr-core': 'ai-sdr-core', + 'runtime': 'agentic-runtime', + 'agentic-runtime': 'agentic-runtime', }; +const RETIRED_PACKS = ['ai-sdr-core', 'agentic-runtime']; -const packs_url = (ref: string = DEFAULT_REF): string=> - `https://raw.githubusercontent.com/${REPO}/${ref}/packs.json`; +// The plugin marketplace an earlier version registered in Claude Code and +// Codex. Its plugins are named `@`; this CLI only finds +// and removes them, and never registers the marketplace again. +const OLD_MARKETPLACE = 'reply-skills'; -const bad_document = (detail: string): RuntimeError=> - new RuntimeError('The skills pack registry is malformed.', {code: 'skills.packs_malformed', detail}); +const MOVED = 'The SDR expertise and the runtime skills ship with Jason (github.com/reply-team/jason-ai)' + + ' and are not installed by this CLI.'; -const as_string = (value: unknown, field: string): string=>{ - if (typeof value !== 'string' || !value.trim()) - { - throw bad_document(`missing or non-string field: ${field}`); - } - return value; -}; +// The pack's directory in the installed package. This module sits one level +// under the package root in both layouts — src/skills from a checkout, +// dist/skills once built — so the same relative path finds it from either. +const pack_dir = (from: string = __dirname): string=> + path.join(from, '..', '..', 'skills', PACK_NAME); -// Parses reply-skills' packs.json. Rejects the document as a whole rather than -// returning a half-parsed registry — a partially understood dependency graph is -// worse than no graph. -const parse_packs = (raw: unknown): Pack_registry=>{ - const doc = (raw ?? {}) as Record; - const marketplace = (doc.marketplace ?? {}) as Record; - const entries = doc.packs; - if (!Array.isArray(entries) || !entries.length) +const plugin_id = (pack: string): string=>`${pack}@${OLD_MARKETPLACE}`; + +const the_pack = (): Pack=>({name: PACK_NAME, version: cli_version()}); + +// Requested names (aliases allowed) → the packs to act on. With no name, +// `install` and `update` mean the one pack, and `list` and `remove` mean +// everything this CLI ever installed, retired packs included. +const resolve_packs = (requested: string[], operation: Operation): Pack[]=>{ + const reaches_retired = operation === 'list' || operation === 'remove'; + if (!requested.length) { - throw bad_document('packs must be a non-empty array'); + return reaches_retired + ? [the_pack(), ...RETIRED_PACKS.map(name=>({name, version: '', retired: true}))] + : [the_pack()]; } - const packs: Pack[] = entries.map((entry, i)=>{ - const e = (entry ?? {}) as Record; - const name = as_string(e.name, `packs[${i}].name`); - const deps = e.dependencies === undefined ? [] : e.dependencies; - if (!Array.isArray(deps) || deps.some(d=>typeof d !== 'string')) - { - throw bad_document(`packs[${i}].dependencies must be an array of strings`); - } - return { - name, - display_name: typeof e.displayName === 'string' ? e.displayName : name, - version: as_string(e.version, `packs[${i}].version`), - description: typeof e.description === 'string' ? e.description : '', - dependencies: deps as string[], - }; - }); - const known = new Set(packs.map(p=>p.name)); - for (const pack of packs) + const wanted: Pack[] = []; + for (const raw of requested) { - for (const dep of pack.dependencies) + const retired = RETIRED[raw]; + if (retired !== undefined && !reaches_retired) { - if (!known.has(dep)) - { - throw bad_document(`${pack.name} depends on unknown pack '${dep}'`); - } + throw new UsageError(MOVED, {code: 'usage.skills_pack_moved'}); } - } - return {marketplace: as_string(marketplace.name ?? MARKETPLACE, 'marketplace.name'), packs}; -}; - -// Fetches the registry, degrading to the embedded copy on any problem — -// unreachable network, HTTP error, or a document we cannot trust. Installing a -// known-good pack set beats failing because GitHub is having a bad day. -const load_packs = async(opts: {ref?: string; fetch_impl?: typeof fetch} = {}): Promise=>{ - const fetch_impl = opts.fetch_impl ?? fetch; - try { - const response = await fetch_impl(packs_url(opts.ref)); - if (!response.ok) + const name = retired ?? ALIASES[raw] ?? raw; + if (name !== PACK_NAME && retired === undefined) { - return PACKS_FALLBACK; + throw new UsageError(`Unknown skills pack '${raw}'.`, { + code: 'usage.skills_pack', + hint: `The pack is ${PACK_NAME} (alias: ${Object.keys(ALIASES).join(', ')})`, + }); } - return parse_packs(await response.json()); - } catch { - return PACKS_FALLBACK; - } -}; - -// Requested names (aliases allowed, empty means everything) → the packs to act -// on, dependencies always before their dependents. -// -// `dependencies: false` returns exactly the requested packs, still in registry -// order. Removal uses it: `remove reply-adapter` must not drag `ai-sdr-core` -// along, because other installed packs still need it. -const resolve_packs = ( - requested: string[], - registry: Pack_registry, - opts: {dependencies?: boolean} = {}, -): Pack[]=>{ - const by_name = new Map(registry.packs.map(p=>[p.name, p])); - const valid = registry.packs.map(p=>p.name).join(', '); - const wanted = requested.length - ? requested.map(raw=>{ - const name = ALIASES[raw] ?? raw; - if (!by_name.has(name)) - { - throw new UsageError(`Unknown skills pack '${raw}'.`, { - code: 'usage.skills_pack', - hint: `Valid packs: ${valid} (aliases: ${Object.keys(ALIASES).join(', ')})`, - }); - } - return name; - }) - : registry.packs.map(p=>p.name); - - if (opts.dependencies === false) - { - const chosen = new Set(wanted); - return registry.packs.filter(p=>chosen.has(p.name)); - } - - const ordered: Pack[] = []; - const seen = new Set(); - const visit = (name: string): void=>{ - if (seen.has(name)) + if (!wanted.some(p=>p.name === name)) { - return; + wanted.push(retired === undefined ? the_pack() : {name, version: '', retired: true}); } - seen.add(name); - const pack = by_name.get(name) as Pack; - for (const dep of pack.dependencies) - { - visit(dep); - } - ordered.push(pack); - }; - for (const name of wanted) - { - visit(name); } - return ordered; + return wanted; }; export { - REPO, MARKETPLACE, DEFAULT_REF, ALIASES, PACKS_FALLBACK, - packs_url, parse_packs, load_packs, resolve_packs, + PACK_NAME, ALIASES, RETIRED, RETIRED_PACKS, OLD_MARKETPLACE, MOVED, + pack_dir, plugin_id, the_pack, resolve_packs, }; diff --git a/src/skills/plugins.ts b/src/skills/plugins.ts new file mode 100644 index 0000000..e1adb03 --- /dev/null +++ b/src/skills/plugins.ts @@ -0,0 +1,79 @@ +import {execFile} from 'child_process'; +import {OLD_MARKETPLACE} from './packs'; +import type {Detected_host} from './detect'; +import type {Runner, Run_result, Scope} from './types'; + +// The plugins an earlier version of this CLI installed through a host's own +// plugin CLI (Claude Code, Codex). This CLI installs nothing that way any +// more: it only lists those plugins, so `list` and `remove` still reach them, +// and removes one when the copy from the package replaces it. + +const default_runner: Runner = (bin, args)=>new Promise(resolve=>{ + execFile(bin, args, {encoding: 'utf8', windowsHide: true}, (error, stdout, stderr)=>{ + const code = error && typeof (error as {code?: unknown}).code === 'number' + ? (error as unknown as {code: number}).code + : (error ? 1 : 0); + resolve({code, stdout: stdout ?? '', stderr: stderr ?? ''}); + }); +}); + +type Listing_result = {ok: true; versions: Record} | {ok: false; detail: string}; + +// Pack name → version, for the plugins of the old marketplace alone. Both +// hosts print a JSON listing, with different envelopes: Claude Code a direct +// array whose rows carry an `id` of the form "@" (older +// versions wrapped rows with `name` and `marketplace` in {plugins:[…]}), Codex +// {installed:[…]} with `marketplaceName`. A row is taken only when it names +// the old marketplace, so a plugin of the same name from anywhere else is +// never listed, and never removed. A row that names its scope (Claude Code's +// do) is taken only for the scope this run acts on. +const old_plugins = async(host: Detected_host, run: Runner, scope: Scope): Promise=>{ + const cli = host.def.plugin_cli!; + const result = await run(host.bin as string, cli.list_json()); + if (result.code !== 0) + { + return {ok: false, detail: (result.stderr || result.stdout).trim() || `exit code ${result.code}`}; + } + let parsed: unknown; + try { + parsed = JSON.parse(result.stdout); + } catch { + return {ok: false, detail: 'the plugin listing was not JSON'}; + } + const doc = (parsed ?? {}) as Record; + const rows = (Array.isArray(parsed) + ? parsed + : [doc.plugins, doc.installed].find(Array.isArray) ?? []) as Record[]; + const out: Record = {}; + for (const row of rows) + { + const raw = (row?.name ?? row?.id) as unknown; + if (typeof raw !== 'string' || typeof row.version !== 'string') + { + continue; + } + const at = raw.lastIndexOf('@'); + const name = at < 0 ? raw : raw.slice(0, at); + const marketplace = at < 0 ? (row.marketplace ?? row.marketplaceName) : raw.slice(at + 1); + if (marketplace === OLD_MARKETPLACE && (typeof row.scope !== 'string' || row.scope === scope)) + { + out[name] = row.version; + } + } + return {ok: true, versions: out}; +}; + +const remove_plugin = async( + host: Detected_host, + run: Runner, + id: string, + scope: Scope, +): Promise<{ok: true} | {ok: false; detail: string}>=>{ + const result = await run(host.bin as string, host.def.plugin_cli!.remove(id, scope)); + return result.code === 0 + ? {ok: true} + : {ok: false, detail: (result.stderr || result.stdout).trim() || `exit code ${result.code}`}; +}; + +export {default_runner, old_plugins, remove_plugin}; +export type {Listing_result}; diff --git a/src/skills/report.ts b/src/skills/report.ts index 7f0991e..cf670da 100644 --- a/src/skills/report.ts +++ b/src/skills/report.ts @@ -1,6 +1,6 @@ import {HOSTS} from './hosts'; import {pc} from '../utils/output'; -import type {Host_outcome, Operation, Pack_action, Report} from './types'; +import type {Host_outcome, Operation, Pack_outcome, Report} from './types'; // Turns per-host outcomes into what the user reads and what the process // returns. The report names only what was found: an assistant that is not on @@ -12,9 +12,10 @@ import type {Host_outcome, Operation, Pack_action, Report} from './types'; // 'Windsurf (Devin)' both overrun it and ran their text into the separator. const LABEL_WIDTH = Math.max(...HOSTS.map(h=>h.label.length)) + 1; -// "a, b or c" — no trailing comma, and safe at one or zero items. -const or_list = (items: string[]): string=> - items.length < 2 ? items[0] ?? '' : `${items.slice(0, -1).join(', ')} or ${items[items.length - 1]}`; +// "a, b or c" (or "and") — no trailing comma, and safe at one or zero items. +const joined = (items: string[], word: string): string=> + items.length < 2 ? items[0] ?? '' : `${items.slice(0, -1).join(', ')} ${word} ${items[items.length - 1]}`; +const or_list = (items: string[]): string=>joined(items, 'or'); // `list` is a query: a host answering "ok" says nothing about whether any pack // is actually there. For every other operation, "installed" is the outcome @@ -28,24 +29,64 @@ const summarize = (hosts: Host_outcome[], action: Operation): Report['summary']= failed: hosts.filter(h=>h.status === 'failed').length, }); -const dependency_note = (requested: string[], resolved: string[]): string | undefined=>{ - const added = resolved.filter(name=>!requested.includes(name)); - if (!added.length || !requested.length) - { - return undefined; - } - return `${added.join(', ')} added — required by ${requested.join(', ')}`; -}; - const verb = { installed: 'installed', upgraded: 'updated', removed: 'removed', current: 'already current', failed: 'failed', } as const; // `list` never changes anything: an 'upgraded' pack there means a newer -// version is available, not that an update already happened underfoot. -const pack_verb = (report_action: Operation, pack_action: Pack_action): string=> - report_action === 'list' && pack_action === 'upgraded' ? 'update available' : verb[pack_action]; +// version is available, not that an update already happened underfoot, and a +// retired pack is one an earlier version installed and this one no longer +// offers. +const pack_verb = (report_action: Operation, pack: Pack_outcome): string=>{ + if (report_action === 'list' && pack.retired && pack.action === 'current') + { + return 'installed, no longer offered'; + } + return report_action === 'list' && pack.action === 'upgraded' ? 'update available' : verb[pack.action]; +}; + +// The command that removes a plugin by hand, spelled from the host's own +// registry entry. +const remove_command = (host: Host_outcome, id: string): string | undefined=>{ + const def = HOSTS.find(h=>h.id === host.host); + const bin = def?.binaries[0]; + return def?.plugin_cli && bin + ? [bin, ...def.plugin_cli.remove(id, host.scope ?? 'user')].join(' ') + : undefined; +}; + +// What happened to the old reply-adapter plugin the copy replaces. +const old_plugin_lines = (host: Host_outcome): string[]=>{ + const old = host.old_plugin; + if (!old) + { + return []; + } + if (old.action === 'removed') + { + return [pc.dim(` replaced the ${old.id} plugin with this copy`)]; + } + const fix = remove_command(host, old.id); + return [ + pc.yellow(` ⚠ the ${old.id} plugin is still installed and loads beside this copy` + + `${old.detail ? `: ${old.detail}` : ''}`), + ...(fix ? [pc.dim(` fix: ${fix}`)] : []), + ]; +}; + +// One line for the run: the other plugins of the old marketplace stay where +// they are, and this CLI no longer offers them. +const retired_plugins_line = (report: Report): string | undefined=>{ + const hosts = report.hosts.filter(h=>h.retired_plugins?.length); + if (!hosts.length) + { + return undefined; + } + const ids = [...new Set(hosts.flatMap(h=>h.retired_plugins ?? []))]; + return pc.dim(`${ids.join(', ')} stay installed in ${joined(hosts.map(h=>h.label), 'and')};` + + ' this CLI no longer offers them.'); +}; // Groups a host's packs by what happened, so one host is one line. const host_line = (host: Host_outcome, report_action: Operation): string=>{ @@ -61,7 +102,7 @@ const host_line = (host: Host_outcome, report_action: Operation): string=>{ const groups = new Map(); for (const pack of host.packs ?? []) { - const key = pack_verb(report_action, pack.action); + const key = pack_verb(report_action, pack); groups.set(key, [...(groups.get(key) ?? []), pack.name]); } if (!groups.size) @@ -79,7 +120,7 @@ const host_line = (host: Host_outcome, report_action: Operation): string=>{ // Hosts this run put something new in front of. The action labels alone cannot // answer it: an unchanged version reports `current` in every adapter, which is -// right, but a flat host re-copying a newer commit at that same version did +// right, but repairing a copy that never finished at that same version did // rewrite the files. `refreshed` carries exactly that, so both facts are // consulted. const changed_hosts = (report: Report): Host_outcome[]=>report.hosts.filter(h=> @@ -100,11 +141,6 @@ const human_lines = (report: Report): string[]=>{ return lines; } lines.push(pc.green(`✓ detected ${report.hosts.map(h=>h.label).join(', ')}`)); - const note = dependency_note(report.requested, report.resolved); - if (note && report.action === 'install') - { - lines.push(pc.dim(` ${note}`)); - } for (const host of report.hosts) { lines.push(host_line(host, report.action)); @@ -112,6 +148,7 @@ const human_lines = (report: Report): string[]=>{ { lines.push(pc.dim(` fix: ${host.hint}`)); } + lines.push(...old_plugin_lines(host)); // Surface pack-level details for failed packs const failed_packs = (host.packs ?? []).filter(p=>p.action === 'failed' && p.detail); for (const pack of failed_packs) @@ -119,6 +156,11 @@ const human_lines = (report: Report): string[]=>{ lines.push(pc.dim(` ${pack.name}: ${pack.detail}`)); } } + const retired = retired_plugins_line(report); + if (retired) + { + lines.push(retired); + } // Only the hosts that need it — restarting one that re-reads its skills // every turn is work the host does not ask for. Named when a run touched // both kinds. @@ -150,4 +192,4 @@ const exit_code_for = (report: Report): number=>{ return report.summary.installed > 0 ? 0 : 1; }; -export {summarize, dependency_note, host_line, human_lines, exit_code_for}; +export {summarize, host_line, human_lines, exit_code_for}; diff --git a/src/skills/types.ts b/src/skills/types.ts index 95b58d2..b4995ed 100644 --- a/src/skills/types.ts +++ b/src/skills/types.ts @@ -3,32 +3,24 @@ type Pack = { name: string; - display_name: string; + // The CLI's own version for the pack it ships; empty for a retired pack, + // whose version is whatever an earlier version recorded. version: string; - description: string; - dependencies: string[]; -}; - -type Pack_registry = { - marketplace: string; - packs: Pack[]; + // A pack this CLI no longer offers: `list` and `remove` still reach it. + retired?: boolean; }; type Scope = 'user' | 'project'; -type Host_kind = 'native-plugin' | 'flat-skills-dir'; +// Every host receives the pack as files in its skills directory. +type Host_kind = 'flat-skills-dir'; -// Argument vectors for a host's own plugin CLI, minus the resolved binary. -// Kept as data so a new host is a registry entry, not a branch in the adapter. -type Host_cli = { - marketplace_add: (repo: string)=>string[]; +// Argument vectors for a host's own plugin CLI, minus the resolved binary, +// used only to find and remove plugins an earlier version of this CLI +// installed there. Kept as data so the spelling is a registry entry. +type Plugin_cli = { list_json: ()=>string[]; - install: (pack: string, marketplace: string, scope: Scope)=>string[]; - update: (pack: string, marketplace: string)=>string[]; - remove: (pack: string, marketplace: string)=>string[]; - // Scope of the update operation: 'pack' for per-pack updates (Claude Code), - // 'marketplace' for whole-marketplace updates (Codex). - update_scope: 'pack' | 'marketplace'; + remove: (id: string, scope: Scope)=>string[]; }; type Host_def = { @@ -37,16 +29,15 @@ type Host_def = { kind: Host_kind; // Paths relative to the home directory; the first that exists proves presence. config_dirs: string[]; - // Command names to look for on PATH (native hosts). + // Command names to look for on PATH, for a host with a plugin CLI. binaries: string[]; // Absolute-path candidates for hosts that ship off PATH, with {home} expanded. binary_paths: string[]; - cli?: Host_cli; - // Skills directory relative to the home directory (flat hosts). - user_skills_dir?: string; - // Skills directory relative to the project root (flat hosts, and native - // hosts whose plugin mechanism cannot express a project install). - project_skills_dir?: string; + plugin_cli?: Plugin_cli; + // Skills directory relative to the home directory. + user_skills_dir: string; + // Skills directory relative to the project root. + project_skills_dir: string; // Whether the user must start a new session before the assistant sees newly // installed skills. Required, so a new host decides it rather than omits it. needs_new_session: boolean; @@ -56,19 +47,29 @@ type Host_def = { type Pack_action = 'installed' | 'upgraded' | 'current' | 'removed' | 'failed'; type Pack_outcome = { + // The pack's name, or a plugin's `@` id for a plugin + // an earlier version installed through the host's own CLI. name: string; action: Pack_action; version?: string; from?: string; detail?: string; - // Set by the flat adapter on a `current` pack whose files this run - // rewrote anyway: a newer commit on the same ref, or a repair of an - // install that never finished. The version did not move — so the action - // is `current`, never `upgraded` — but the bytes on disk did, and that is - // what decides whether the user has to start a new assistant session. - // Never set by a native host, which cannot see below its own plugin CLI, - // and never by a dry run, which does not clone and so cannot know. + // Set on a `current` pack whose files this run rewrote anyway: the repair + // of an install that never finished. The version did not move — so the + // action is `current`, never `upgraded` — but the bytes on disk did, and + // that is what decides whether the user has to start a new assistant + // session. Never set by a dry run. refreshed?: boolean; + // A pack this CLI no longer offers, found by `list` or `remove`. + retired?: boolean; +}; + +// The reply-adapter plugin an earlier version installed through the host's +// own CLI, which an install or update of the copy takes away. +type Old_plugin = { + id: string; + action: 'removed' | 'failed'; + detail?: string; }; type Host_status = 'ok' | 'partial' | 'failed' | 'skipped'; @@ -83,13 +84,14 @@ type Host_outcome = { reason?: string; detail?: string; hint?: string; - // The commit a flat host actually cloned in this run — set only when this - // run cloned the skills repository (never on a native host, and never - // when nothing was pending, a dry run skipped the clone, or the clone - // itself failed). This is what lets the orchestrator report the source - // commit without ever attributing a stale or foreign one to a run that - // did not produce it. - commit?: string; + // Set by install and update when the host still had the old reply-adapter + // plugin: whether it was removed once the copy landed. A failure leaves + // the status alone — the copy is there — and the report says the plugin + // still loads beside it. + old_plugin?: Old_plugin; + // The other plugins of that marketplace still installed, by id. This CLI + // leaves them, and the report says it no longer offers them. + retired_plugins?: string[]; // Mirrors Host_def.verified: false means this assistant's paths come from // its documentation and have not been confirmed by a verification run of // our own. Stamped by the orchestrator for every host it @@ -117,7 +119,8 @@ type Orphaned_packs = { type Report = { action: Operation; - source: {repo: string; ref: string; commit?: string}; + // What the pack was copied from: this CLI's own package, at its version. + source: {version: string}; requested: string[]; resolved: string[]; hosts: Host_outcome[]; @@ -127,12 +130,12 @@ type Report = { type Run_result = {code: number; stdout: string; stderr: string}; -// Injected process runner: the single seam that lets every adapter test run -// without an assistant installed. +// Injected process runner: the single seam that lets every plugin-CLI test +// run without an assistant installed. type Runner = (bin: string, args: string[])=>Promise; export type { - Pack, Pack_registry, Scope, Host_kind, Host_cli, Host_def, Orphaned_packs, + Pack, Scope, Host_kind, Plugin_cli, Host_def, Orphaned_packs, Old_plugin, Pack_action, Pack_outcome, Host_status, Host_outcome, Operation, Report, Run_result, Runner, }; From 9b3d500bb9bb2281a17f65f3f7d737009727fe3e Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Wed, 4 Nov 2026 07:34:51 -0700 Subject: [PATCH 2/4] docs(skills): describe the one pack the CLI ships and where the rest lives The README stops presenting three packs and the separate skills repository: it names the pack this package carries, how it moves with the CLI, the copied-file paths for Claude Code and Codex, and that the SDR expertise and runtime skills ship with Jason. --- README.md | 74 +++++++++++++++++++++++++++---------------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index d26e9cc..14a85b8 100644 --- a/README.md +++ b/README.md @@ -57,16 +57,19 @@ with `REPLY_NO_UPDATE_CHECK=1` set. ## Where this fits -Reply's agentic toolkit is three pieces. They are complementary, not alternatives: +Reply's agentic toolkit is two pieces, with the skills that teach an agent to use them +carried in this package. They are complementary, not alternatives: | | What it is | When you want it | |---|---|---| -| **reply CLI** (this repo) | `npm i -g reply-cli` — authenticated access to *every* v3 endpoint via `reply api` | Your agent has a shell. This is the complete surface. | +| **reply CLI** (this repo) | `npm i -g reply-cli` — authenticated access to *every* v3 endpoint via `reply api`, and the Reply skills (`reply skills install`) | Your agent has a shell. This is the complete surface. | | **[Reply MCP](https://github.com/reply-team/reply-mcp)** | A curated tool catalog over `mcp.reply.io` | Your client speaks MCP and has no shell — desktop apps, hosted assistants. | -| **[reply-skills](https://github.com/reply-team/reply-skills)** | Outbound expertise as markdown skills: what to do, in what order, with what guardrails | Your agent knows *how* to call things but not *what* to run. | -MCP gives your agent tools. Skills give it judgement. Most setups want both; a shell-capable -agent can do everything through the CLI alone. +The skills teach an agent how to perform an SDR operation against Reply: which endpoint, which +scope, in what order, and what Reply's errors mean. The vendor-neutral SDR expertise — the +operation catalogue, playbooks and guardrails those skills map onto — and the runtime skills ship +with [Jason](https://github.com/reply-team/jason-ai), the catalogue under its `skills/business`. +A shell-capable agent can do everything through the CLI alone. The shortest path that works: install the CLI, `reply auth login`, `reply skills install`, then talk to your agent in plain words. MCP is optional — add it when your client has no shell. @@ -525,9 +528,10 @@ exist. PowerShell, cmd, macOS and Linux are unaffected. ## Skills -Reply's outbound expertise ships as three markdown skill packs in -[reply-skills](https://github.com/reply-team/reply-skills). One command installs -them into every AI assistant on your machine, dependencies resolved: +The Reply skills ship inside this package as one pack, `reply-adapter` (alias +`adapter`), at the CLI's own version: `reply-api`, `reply-auth`, `reply-cli`, +`reply-mcp` and `reply-operations-mapping`. One command copies them into every +AI assistant on your machine, from the installed package, with no download: ```sh reply skills install @@ -535,23 +539,12 @@ reply skills install ``` ✓ detected Claude Code, Codex -✓ Claude Code · ai-sdr-core, reply-adapter, agentic-runtime installed -✓ Codex · ai-sdr-core, reply-adapter, agentic-runtime installed +✓ Claude Code · reply-adapter installed +✓ Codex · reply-adapter installed Start a new session in each assistant so the skills load. ``` -| Pack | Alias | What it gives your agent | -|---|---|---| -| `ai-sdr-core` | `core` | Vendor-neutral SDR operations, playbooks and guardrails | -| `reply-adapter` | `adapter` | Executing those operations against Reply.io | -| `agentic-runtime` | `runtime` | Durable multi-session work: plans, checkpoints, reports | - -Install a subset — dependencies come along automatically, so `adapter` pulls -`core`: - ```sh -reply skills install core -reply skills install adapter runtime reply skills install --agent codex # only this assistant reply skills install --project # into this repository, not your home ``` @@ -559,21 +552,28 @@ reply skills install --project # into this repository, not your home Then manage them: ```sh -reply skills list # what's installed where (notes packs with an update available) -reply skills update # bring installed packs to the latest version -reply skills remove runtime # remove one pack -reply skills remove # remove all of them +reply skills list # what's installed where, and at which version +reply skills update # bring the installed skills to the version of this CLI +reply skills remove # remove everything this CLI installed ``` -On Claude Code and Codex the packs are installed through the assistant's own -plugin mechanism, so they keep updating through it. Other `SKILL.md` hosts -receive the skills as files. Add `--json` for a machine-readable report, and +The skills move with the CLI: after `reply install` brings a newer CLI, +`reply skills update` copies its skills over the old ones. Every assistant +receives the skills as files. Add `--json` for a machine-readable report, and `--dry-run` to see the plan without changing anything. -| Assistant | How it receives the packs | Skills path | Paths verified | To take effect | +An earlier version of this CLI installed three packs, and installed them on +Claude Code and Codex through the assistant's own plugin CLI. `install` and +`update` now replace the old `reply-adapter` plugin with the copied +files, removing that plugin through the assistant's own CLI, and say so; the +two other plugins stay installed, and the report names them. `list` and +`remove` still find what an earlier version installed, under the old pack +names too. + +| Assistant | How it receives the skills | Skills path | Paths verified | To take effect | |---|---|---|---|---| -| Claude Code | its own plugin CLI | managed by the plugin CLI | yes | start a new session | -| Codex | its own plugin CLI (`--project` copies files instead) | managed by the plugin CLI | yes | start a new session | +| Claude Code | copied files | `~/.claude/skills`, or `.claude/skills` with `--project` | yes | start a new session | +| Codex | copied files | `~/.agents/skills`, or `.agents/skills` with `--project` | yes | start a new session | | Cursor | copied files | `~/.cursor/skills`, or `.agents/skills` with `--project` | Cursor 3.14.27, cursor-agent 2026.08.04-aaa8809 | a new session (a new chat) | | Windsurf (ships as Devin) | copied files | `~/.codeium/windsurf/skills`, or `.windsurf/skills` with `--project` | Devin 3.6.27, devin CLI 3000.3.27 | a new session (the next `devin` run) | | Antigravity | copied files | `~/.gemini/config/skills`, or `.agents/skills` with `--project` | Antigravity 2.0.1 | nothing — it re-reads its skills every turn, including in a conversation already open | @@ -585,10 +585,9 @@ Codex, Antigravity and GitHub Copilot. A project-scope install aimed at one of them therefore makes those skills visible in the others, and removing them for one changes what the others see. Use user scope when you want a host's skills to itself. GitHub Copilot reads two further repository directories, `.claude/skills` -and `.github/skills`. This command never writes to either — Claude Code installs -through its own plugin CLI in both scopes — so that crossover appears only when -something else fills them: a skill copied there by hand, or the `npx skills` -channel, which writes `.claude/skills` for a project-scoped Claude Code install. +and `.github/skills`; `--project` for Claude Code writes `.claude/skills`, so a +project-scope install for Claude Code is visible to GitHub Copilot in that +repository too. Every assistant in the table has been verified against the version named. A host added later may arrive with its skills directory taken from the vendor's @@ -600,8 +599,9 @@ Antigravity and GitHub Copilot with the release that adds them. GitHub Copilot is two products over one directory: the `copilot` CLI and the VS Code agent host, which ships `~/.copilot/skills` among the defaults of its `chat.agentSkillsLocations` setting — alongside `~/.claude/skills` and -`~/.agents/skills`, user directories the CLI itself does not read. The CLI is -what the row above was verified against. VS Code scans those directories once per window and does not watch them, +`~/.agents/skills`, user directories the CLI itself does not read and where this +command puts the skills for Claude Code and Codex, so VS Code sees those too. +The CLI is what the row above was verified against. VS Code scans those directories once per window and does not watch them, so an install made while it is open needs `Developer: Reload Window` rather than just a new chat. From d155a9ef68738b5502a65fd98705f371361dbd35 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Wed, 4 Nov 2026 07:38:44 -0700 Subject: [PATCH 3/4] feat(skills): list names the version each pack has on disk reply skills list now prints each pack with the version installed in that assistant, so the human report answers which version is where as the JSON one already did. The line naming the old plugins left in place agrees in number with how many there are. --- src/__tests__/commands/skills.test.ts | 24 +++++++++++------------ src/__tests__/skills/package-pack.test.ts | 2 +- src/__tests__/skills/report.test.ts | 10 ++++++++-- src/skills/report.ts | 14 ++++++++++--- 4 files changed, 32 insertions(+), 18 deletions(-) diff --git a/src/__tests__/commands/skills.test.ts b/src/__tests__/commands/skills.test.ts index ad5b74b..7f8ba32 100644 --- a/src/__tests__/commands/skills.test.ts +++ b/src/__tests__/commands/skills.test.ts @@ -11,12 +11,12 @@ import type {Report} from '../../skills/types'; const report = (over: Partial = {}): Report=>({ action: 'install', - source: {repo: 'reply-team/reply-skills', ref: 'main'}, - requested: ['ai-sdr-core'], - resolved: ['ai-sdr-core'], + source: {version: '0.1.0'}, + requested: ['reply-adapter'], + resolved: ['reply-adapter'], hosts: [{ - host: 'claude-code', label: 'Claude Code', kind: 'native-plugin', scope: 'user', status: 'ok', - packs: [{name: 'ai-sdr-core', action: 'installed', version: '0.1.0'}], + host: 'claude-code', label: 'Claude Code', kind: 'flat-skills-dir', scope: 'user', status: 'ok', + packs: [{name: 'reply-adapter', action: 'installed', version: '0.1.0'}], }], summary: {installed: 1, skipped: 0, failed: 0}, ...over, @@ -39,7 +39,7 @@ const capture = async(fn: ()=>unknown | Promise): Promise<{out: string; let dir: string; beforeEach(()=>{ vi.clearAllMocks(); - dir = fs.mkdtempSync(path.join(os.tmpdir(), 'reply-skills-cmd-')); + dir = fs.mkdtempSync(path.join(os.tmpdir(), 'reply-cli-skills-cmd-')); process.env.REPLY_CONFIG_DIR = dir; }); afterEach(()=>{ @@ -55,7 +55,7 @@ describe('handle_skills', ()=>{ mock_run_skills.mockResolvedValue(report()); const {out, err} = await capture(()=>handle_skills('install', [], {})); expect(err).toContain('detected Claude Code'); - expect(err).toContain('ai-sdr-core installed'); + expect(err).toContain('reply-adapter installed'); expect(out).toBe(''); }); @@ -63,13 +63,13 @@ describe('handle_skills', ()=>{ mock_run_skills.mockResolvedValue(report({ action: 'list', hosts: [{ - host: 'claude-code', label: 'Claude Code', kind: 'native-plugin', scope: 'user', status: 'ok', - packs: [{name: 'ai-sdr-core', action: 'current', version: '0.1.0'}], + host: 'claude-code', label: 'Claude Code', kind: 'flat-skills-dir', scope: 'user', status: 'ok', + packs: [{name: 'reply-adapter', action: 'current', version: '0.1.0'}], }], })); const {out, err} = await capture(()=>handle_skills('list', [], {})); expect(out).toContain('detected Claude Code'); - expect(out).toContain('ai-sdr-core already current'); + expect(out).toContain('reply-adapter 0.1.0 already current'); expect(err).toBe(''); }); @@ -85,7 +85,7 @@ describe('handle_skills', ()=>{ const {out} = await capture(()=>handle_skills('install', [], {json: true})); const parsed = JSON.parse(out); expect(parsed.action).toBe('install'); - expect(parsed.resolved).toEqual(['ai-sdr-core']); + expect(parsed.resolved).toEqual(['reply-adapter']); expect(parsed.hosts[0].host).toBe('claude-code'); }); @@ -137,7 +137,7 @@ describe('handle_skills', ()=>{ it('still prints the report before failing, so the reason is not lost', async()=>{ mock_run_skills.mockResolvedValue(report({ hosts: [{ - host: 'codex', label: 'Codex', kind: 'native-plugin', status: 'failed', + host: 'codex', label: 'Codex', kind: 'flat-skills-dir', status: 'failed', reason: 'marketplace-add-failed', detail: 'no network', }], summary: {installed: 0, skipped: 0, failed: 1}, diff --git a/src/__tests__/skills/package-pack.test.ts b/src/__tests__/skills/package-pack.test.ts index 102be12..9468474 100644 --- a/src/__tests__/skills/package-pack.test.ts +++ b/src/__tests__/skills/package-pack.test.ts @@ -301,7 +301,7 @@ describe('list and remove over what an earlier version installed', ()=>{ {name: 'ai-sdr-core', action: 'current', version: '0.1.0', retired: true}, {name: 'agentic-runtime', action: 'current', version: '0.1.0', retired: true}, ]); - expect(human_lines(report).join('\n')).toContain('ai-sdr-core, agentic-runtime installed, no longer offered'); + expect(human_lines(report).join('\n')).toContain('reply-adapter 0.1.0 update available; ai-sdr-core 0.1.0, agentic-runtime 0.1.0 installed, no longer offered'); }); it('removes a journal entry of the earlier shape under its old name, and everything with no name', async()=>{ diff --git a/src/__tests__/skills/report.test.ts b/src/__tests__/skills/report.test.ts index 5ae6d30..833d670 100644 --- a/src/__tests__/skills/report.test.ts +++ b/src/__tests__/skills/report.test.ts @@ -157,7 +157,7 @@ describe('human_lines', ()=>{ {name: 'reply-adapter', action: 'current', version: '0.1.0'}, {name: 'ai-sdr-core', action: 'current', version: '0.0.9', retired: true}, ]})], {action: 'list'})); - expect(out).toMatch(/Claude Code +· reply-adapter already current; ai-sdr-core installed, no longer offered/); + expect(out).toMatch(/Claude Code +· reply-adapter 0.1.0 already current; ai-sdr-core 0.0.9 installed, no longer offered/); }); it('says the old plugin was replaced by the copy', ()=>{ @@ -174,6 +174,12 @@ describe('human_lines', ()=>{ expect(out).toContain('fix: claude plugin uninstall reply-adapter@reply-skills --scope project'); }); + it('says the one old plugin it leaves stays, in the singular', ()=>{ + const lines = human_lines(report([host({retired_plugins: ['ai-sdr-core@reply-skills']})])) + .map(strip).filter(l=>l.includes('no longer offers')); + expect(lines).toEqual(['ai-sdr-core@reply-skills stays installed in Claude Code; this CLI no longer offers it.']); + }); + it('names the old plugins it leaves in one line for the whole run', ()=>{ const lines = human_lines(report([ host({retired_plugins: ['ai-sdr-core@reply-skills', 'agentic-runtime@reply-skills']}), @@ -247,7 +253,7 @@ describe('human_lines', ()=>{ const out = text(report([host({ packs: [{name: 'ai-sdr-core', action: 'upgraded', version: '0.2.0', from: '0.1.0'}], })], {action: 'list'})); - expect(out).toContain('update available'); + expect(out).toContain('ai-sdr-core 0.1.0 update available'); expect(out).not.toContain('updated'); }); diff --git a/src/skills/report.ts b/src/skills/report.ts index cf670da..8f9e8cb 100644 --- a/src/skills/report.ts +++ b/src/skills/report.ts @@ -46,6 +46,13 @@ const pack_verb = (report_action: Operation, pack: Pack_outcome): string=>{ return report_action === 'list' && pack.action === 'upgraded' ? 'update available' : verb[pack.action]; }; +// `list` answers what is installed, so each pack carries the version on disk: +// the one an available update would replace, not the one it would bring. +const listed_name = (report_action: Operation, pack: Pack_outcome): string=>{ + const installed = pack.from ?? pack.version; + return report_action === 'list' && installed ? `${pack.name} ${installed}` : pack.name; +}; + // The command that removes a plugin by hand, spelled from the host's own // registry entry. const remove_command = (host: Host_outcome, id: string): string | undefined=>{ @@ -84,8 +91,9 @@ const retired_plugins_line = (report: Report): string | undefined=>{ return undefined; } const ids = [...new Set(hosts.flatMap(h=>h.retired_plugins ?? []))]; - return pc.dim(`${ids.join(', ')} stay installed in ${joined(hosts.map(h=>h.label), 'and')};` - + ' this CLI no longer offers them.'); + const one = ids.length === 1; + return pc.dim(`${ids.join(', ')} ${one ? 'stays' : 'stay'} installed in ${joined(hosts.map(h=>h.label), 'and')};` + + ` this CLI no longer offers ${one ? 'it' : 'them'}.`); }; // Groups a host's packs by what happened, so one host is one line. @@ -103,7 +111,7 @@ const host_line = (host: Host_outcome, report_action: Operation): string=>{ for (const pack of host.packs ?? []) { const key = pack_verb(report_action, pack); - groups.set(key, [...(groups.get(key) ?? []), pack.name]); + groups.set(key, [...(groups.get(key) ?? []), listed_name(report_action, pack)]); } if (!groups.size) { From 9210aad56e0b8d5f0e8ccaeba43726e5c3349c6a Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Wed, 4 Nov 2026 07:53:14 -0700 Subject: [PATCH 4/4] fix(skills): name the retired packs left on a host, and read only a name's own entry install and update now name, in the one line about what stays, the retired packs an earlier version copied into a host at the run's scope, beside the old plugins, each host with its own names. A pack name is looked up in the tables' own entries only, so a name such as constructor is an unknown pack rather than a retired one. A test pins update on a host that has neither a copy nor the old plugin. --- README.md | 3 ++- src/__tests__/skills/orchestrate.test.ts | 10 +++++++- src/__tests__/skills/package-pack.test.ts | 26 ++++++++++++++++++++ src/__tests__/skills/packs.test.ts | 17 +++++++++++++ src/__tests__/skills/report.test.ts | 15 +++++++++++- src/skills/adapter-flat.ts | 14 +++++++---- src/skills/packs.ts | 9 +++++-- src/skills/report.ts | 30 +++++++++++++++++------ src/skills/types.ts | 4 +++ 9 files changed, 110 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 14a85b8..06870d8 100644 --- a/README.md +++ b/README.md @@ -566,7 +566,8 @@ An earlier version of this CLI installed three packs, and installed them on Claude Code and Codex through the assistant's own plugin CLI. `install` and `update` now replace the old `reply-adapter` plugin with the copied files, removing that plugin through the assistant's own CLI, and say so; the -two other plugins stay installed, and the report names them. `list` and +two other plugins, and copies of the two other packs, stay installed, and the +report names them. `list` and `remove` still find what an earlier version installed, under the old pack names too. diff --git a/src/__tests__/skills/orchestrate.test.ts b/src/__tests__/skills/orchestrate.test.ts index 225601d..e8f88b9 100644 --- a/src/__tests__/skills/orchestrate.test.ts +++ b/src/__tests__/skills/orchestrate.test.ts @@ -6,7 +6,7 @@ import {cli_version} from '../../config'; import {HOSTS} from '../../skills/hosts'; import {record_pack} from '../../skills/journal'; import {run_skills} from '../../skills/orchestrate'; -import {human_lines} from '../../skills/report'; +import {exit_code_for, human_lines} from '../../skills/report'; import type {Detect_deps} from '../../skills/detect'; import type {Runner} from '../../skills/types'; import {UsageError} from '../../utils/errors'; @@ -197,6 +197,14 @@ describe('run_skills', ()=>{ expect(fs.existsSync(skill_file(home, '.cursor', 'skills'))).toBe(true); }); + it('does nothing on update for a host with neither a copy nor the old plugin, and exits 0', async()=>{ + const report = await run_skills(opts({operation: 'update', agents: ['cursor']})); + expect(report.hosts[0]).toMatchObject({host: 'cursor', status: 'ok', packs: []}); + expect(human_lines(report).join('\n')).toMatch(/Cursor +· nothing to do/); + expect(exit_code_for(report)).toBe(0); + expect(fs.existsSync(path.join(home, '.cursor', 'skills'))).toBe(false); + }); + it('reports current on every host when update finds the copy already at this version', async()=>{ await run_skills(opts()); const report = await run_skills(opts({operation: 'update'})); diff --git a/src/__tests__/skills/package-pack.test.ts b/src/__tests__/skills/package-pack.test.ts index 9468474..1462d99 100644 --- a/src/__tests__/skills/package-pack.test.ts +++ b/src/__tests__/skills/package-pack.test.ts @@ -215,6 +215,32 @@ describe('install from the package', ()=>{ expect(lines[0]).toContain('agentic-runtime@reply-skills'); }); + it('names in that line the retired packs an earlier version copied into a host, on install and on update', async()=>{ + fs.mkdirSync(path.join(home, '.cursor'), {recursive: true}); + for (const [pack, skill] of [['ai-sdr-core', 'sdr-operations'], ['agentic-runtime', 'durable-work']]) + { + const file = path.join(home, '.cursor', 'skills', skill, 'SKILL.md'); + fs.mkdirSync(path.dirname(file), {recursive: true}); + fs.writeFileSync(file, `${skill}\n`); + record_pack('cursor', 'user', pack, { + version: '0.1.0', ref: 'main', commit: 'cafe123', scope: 'user', + files: [file], complete: true, installed_at: '2026-10-01T00:00:00.000Z', + }, env); + } + for (const operation of ['install', 'update'] as const) + { + const report = await run_skills(opts({operation, agents: ['cursor']})); + expect(report.hosts[0].retired_packs, operation).toEqual(['ai-sdr-core', 'agentic-runtime']); + const lines = human_lines(report).filter(l=>l.includes('no longer offers')); + expect(lines, operation).toHaveLength(1); + expect(lines[0], operation).toContain( + 'ai-sdr-core, agentic-runtime stay installed in Cursor; this CLI no longer offers them.'); + } + // Only what this run's scope recorded: the user-scope copies are not a project's. + const project = await run_skills(opts({agents: ['cursor'], project: true})); + expect(project.hosts[0].retired_packs).toBeUndefined(); + }); + it('proceeds when the old plugin cannot be removed, and says it is still there beside the copy', async()=>{ const {run} = plugin_runner({listed: ['reply-adapter@reply-skills'], uninstall_fails: true}); const report = await run_skills(opts({}, run)); diff --git a/src/__tests__/skills/packs.test.ts b/src/__tests__/skills/packs.test.ts index 46a7475..db12096 100644 --- a/src/__tests__/skills/packs.test.ts +++ b/src/__tests__/skills/packs.test.ts @@ -58,6 +58,23 @@ describe('resolve_packs', ()=>{ expect((caught as UsageError).hint).toContain('reply-adapter'); expect((caught as UsageError).hint).toContain('adapter'); }); + + it('takes nothing from the object prototype for a pack name', ()=>{ + for (const raw of ['constructor', 'toString', '__proto__']) + { + for (const operation of ['install', 'list'] as const) + { + let caught: unknown; + try { + resolve_packs([raw], operation); + } catch (error) { + caught = error; + } + expect(caught, `${raw} on ${operation}`).toBeInstanceOf(UsageError); + expect((caught as UsageError).code, `${raw} on ${operation}`).toBe('usage.skills_pack'); + } + } + }); }); describe('plugin_id', ()=>{ diff --git a/src/__tests__/skills/report.test.ts b/src/__tests__/skills/report.test.ts index 833d670..d755605 100644 --- a/src/__tests__/skills/report.test.ts +++ b/src/__tests__/skills/report.test.ts @@ -186,7 +186,20 @@ describe('human_lines', ()=>{ host({host: 'codex', label: 'Codex', retired_plugins: ['ai-sdr-core@reply-skills']}), ])).map(strip).filter(l=>l.includes('no longer offers')); expect(lines).toEqual([ - 'ai-sdr-core@reply-skills, agentic-runtime@reply-skills stay installed in Claude Code and Codex;' + 'ai-sdr-core@reply-skills, agentic-runtime@reply-skills stay installed in Claude Code;' + + ' ai-sdr-core@reply-skills stays installed in Codex; this CLI no longer offers them.', + ]); + }); + + it('names retired packs a host copied beside its plugins, hosts with the same names together', ()=>{ + const lines = human_lines(report([ + host({retired_plugins: ['ai-sdr-core@reply-skills'], retired_packs: ['agentic-runtime']}), + host({host: 'cursor', label: 'Cursor', retired_packs: ['ai-sdr-core', 'agentic-runtime']}), + host({host: 'github-copilot', label: 'GitHub Copilot', retired_packs: ['ai-sdr-core', 'agentic-runtime']}), + ])).map(strip).filter(l=>l.includes('no longer offers')); + expect(lines).toEqual([ + 'ai-sdr-core@reply-skills, agentic-runtime stay installed in Claude Code;' + + ' ai-sdr-core, agentic-runtime stay installed in Cursor and GitHub Copilot;' + ' this CLI no longer offers them.', ]); }); diff --git a/src/skills/adapter-flat.ts b/src/skills/adapter-flat.ts index 8b077b4..c4c501f 100644 --- a/src/skills/adapter-flat.ts +++ b/src/skills/adapter-flat.ts @@ -2,7 +2,7 @@ import fs from 'fs'; import os from 'os'; import path from 'path'; import {forget_pack, journal_entry, read_journal, record_pack} from './journal'; -import {pack_dir} from './packs'; +import {RETIRED_PACKS, pack_dir} from './packs'; import type {Env} from '../config'; import type {Detected_host} from './detect'; import type {Journal_entry} from './journal'; @@ -398,6 +398,10 @@ const run_flat = async(opts: Flat_opts): Promise=>{ // install and update both copy. update only touches packs the host // already has: a journal entry, or the old plugin this copy replaces. + // The retired packs an earlier version copied here at this scope stay, + // and the outcome names them so the report can say so. + const left = RETIRED_PACKS.filter(name=>entry_for(name) !== undefined); + const copy_base: Host_outcome = left.length ? {...base, retired_packs: left} : base; const targets = operation === 'update' ? packs.filter(p=>entry_for(p.name) || adopt[p.name] !== undefined) : packs; @@ -423,7 +427,7 @@ const run_flat = async(opts: Flat_opts): Promise=>{ }; if (!pending.length) { - return {...base, packs: outcomes}; + return {...copy_base, packs: outcomes}; } if (dry_run) { @@ -431,7 +435,7 @@ const run_flat = async(opts: Flat_opts): Promise=>{ { outcomes.push(copied_outcome(pack.name, pack.version, from_for(pack.name).from)); } - return {...base, packs: outcomes}; + return {...copy_base, packs: outcomes}; } // A per-host filesystem failure here (a read-only destination, a package @@ -501,7 +505,7 @@ const run_flat = async(opts: Flat_opts): Promise=>{ // far could itself be a collision failure, so check the actions. const landed = outcomes.some(p=>p.action !== 'failed'); return { - ...base, + ...copy_base, status: landed ? 'partial' : 'failed', packs: outcomes, reason: 'copy-failed', @@ -509,7 +513,7 @@ const run_flat = async(opts: Flat_opts): Promise=>{ hint: 'check filesystem permissions for the skills directory, then re-run', }; } - return {...base, packs: outcomes, status: status_of(outcomes)}; + return {...copy_base, packs: outcomes, status: status_of(outcomes)}; }; export {canonical, copy_dir, skills_target, status_of, run_flat}; diff --git a/src/skills/packs.ts b/src/skills/packs.ts index 8188906..3e63ae6 100644 --- a/src/skills/packs.ts +++ b/src/skills/packs.ts @@ -23,6 +23,11 @@ const RETIRED: Record = { }; const RETIRED_PACKS = ['ai-sdr-core', 'agentic-runtime']; +// A name's own entry only: a plain object also answers `constructor`, +// `toString` and `__proto__` from its prototype. +const own = (table: Record, key: string): string | undefined=> + Object.hasOwn(table, key) ? table[key] : undefined; + // The plugin marketplace an earlier version registered in Claude Code and // Codex. Its plugins are named `@`; this CLI only finds // and removes them, and never registers the marketplace again. @@ -55,12 +60,12 @@ const resolve_packs = (requested: string[], operation: Operation): Pack[]=>{ const wanted: Pack[] = []; for (const raw of requested) { - const retired = RETIRED[raw]; + const retired = own(RETIRED, raw); if (retired !== undefined && !reaches_retired) { throw new UsageError(MOVED, {code: 'usage.skills_pack_moved'}); } - const name = retired ?? ALIASES[raw] ?? raw; + const name = retired ?? own(ALIASES, raw) ?? raw; if (name !== PACK_NAME && retired === undefined) { throw new UsageError(`Unknown skills pack '${raw}'.`, { diff --git a/src/skills/report.ts b/src/skills/report.ts index 8f9e8cb..d368e58 100644 --- a/src/skills/report.ts +++ b/src/skills/report.ts @@ -82,18 +82,32 @@ const old_plugin_lines = (host: Host_outcome): string[]=>{ ]; }; -// One line for the run: the other plugins of the old marketplace stay where -// they are, and this CLI no longer offers them. +// One line for the run: what an earlier version installed and this CLI no +// longer offers stays where it is — the other plugins of the old marketplace, +// and copies of the retired packs. Hosts that keep the same names share a +// clause, so each host is named with its own. const retired_plugins_line = (report: Report): string | undefined=>{ - const hosts = report.hosts.filter(h=>h.retired_plugins?.length); - if (!hosts.length) + const groups = new Map(); + for (const host of report.hosts) + { + const names = [...host.retired_plugins ?? [], ...host.retired_packs ?? []]; + if (!names.length) + { + continue; + } + const key = names.join(', '); + const group = groups.get(key) ?? {names, labels: []}; + group.labels.push(host.label); + groups.set(key, group); + } + if (!groups.size) { return undefined; } - const ids = [...new Set(hosts.flatMap(h=>h.retired_plugins ?? []))]; - const one = ids.length === 1; - return pc.dim(`${ids.join(', ')} ${one ? 'stays' : 'stay'} installed in ${joined(hosts.map(h=>h.label), 'and')};` - + ` this CLI no longer offers ${one ? 'it' : 'them'}.`); + const clauses = [...groups.values()].map(({names, labels})=> + `${names.join(', ')} ${names.length === 1 ? 'stays' : 'stay'} installed in ${joined(labels, 'and')}`); + const all = new Set([...groups.values()].flatMap(g=>g.names)); + return pc.dim(`${clauses.join('; ')}; this CLI no longer offers ${all.size === 1 ? 'it' : 'them'}.`); }; // Groups a host's packs by what happened, so one host is one line. diff --git a/src/skills/types.ts b/src/skills/types.ts index b4995ed..f0f6c06 100644 --- a/src/skills/types.ts +++ b/src/skills/types.ts @@ -92,6 +92,10 @@ type Host_outcome = { // The other plugins of that marketplace still installed, by id. This CLI // leaves them, and the report says it no longer offers them. retired_plugins?: string[]; + // The retired packs an earlier version copied into this host at the + // run's scope, by pack name. Left in place like the plugins, and named + // beside them. + retired_packs?: string[]; // Mirrors Host_def.verified: false means this assistant's paths come from // its documentation and have not been confirmed by a verification run of // our own. Stamped by the orchestrator for every host it