primcli 1.34.0 → 1.36.0

package/dist/skills/primitive-connect/scripts/check-cli-capabilities.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+
+const receiver = process.argv.length === 4 && process.argv[2] === '--receiver'
+  ? process.argv[3]
+  : null;
+if (receiver !== 'native' && receiver !== 'external') {
+  process.stderr.write('Usage: node scripts/check-cli-capabilities.mjs --receiver native|external\n');
+  process.exitCode = 2;
+} else {
+  const checks = [
+    { args: ['agent', 'connect', '--help'], label: 'agent connect', patterns: [/--session\b/, /--receiver\b/] },
+    { args: ['agent', 'enroll', '--help'], label: 'agent enroll', patterns: [/--session\b/, /--receiver\b/, /--name\b/] },
+    { args: ['listen', '--help'], label: 'listen', patterns: [/external mail events at tool-output authority/i, /never synthetic user messages/i] },
+    { args: ['network', 'peers', '--help'], label: 'network peers', patterns: [/discover listed peers/i, /--owner\b/] },
+  ];
+  if (receiver === 'external') {
+    checks[0].patterns.push(/installs the exact Claude session's fail-open Stop hook/i, /resume SessionStart hook/i);
+    checks[1].patterns.push(/exact Claude session, install a fail-open Stop hook/i, /resume SessionStart hook/i);
+    checks[2].patterns.push(/--wake\b/, /--hook-session\b/);
+  } else {
+    checks[2].patterns.push(/--notify-session\b/, /--background\b/);
+  }
+
+  const missing = [];
+  for (const { args, label, patterns } of checks) {
+    const result = spawnSync('primitive', args, {
+      encoding: 'utf8',
+      timeout: 10_000,
+      maxBuffer: 128 * 1024,
+    });
+    if (result.error || result.status !== 0) {
+      missing.push(`${label} --help is unavailable`);
+      continue;
+    }
+    const help = result.stdout.replace(/\s+/g, ' ');
+    if (patterns.some((pattern) => !pattern.test(help))) {
+      missing.push(`${label} --help lacks required setup, ${receiver} receiving, or peer-discovery support`);
+    }
+  }
+
+  if (missing.length) {
+    process.stderr.write(`Primitive CLI preflight failed: ${missing.join('; ')}. Do not claim the invitation or create an address with this CLI. Install a CLI build with these capabilities and run this check again, or connect with the HTTP API instead.\n`);
+    process.exitCode = 1;
+  } else {
+    process.stdout.write(`Primitive CLI preflight passed for ${receiver} receiving and peer discovery.\n`);
+  }
+}

package/dist/skills/primitive-connect/scripts/connection.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const ORIGIN = 'https://api.primitive.dev';
+const API = `${ORIGIN}/v1`;
+
+export class PrimitiveApiError extends Error {
+  constructor(status, code) {
+    status = Number.isInteger(status) && status >= 100 && status <= 599 ? status : undefined;
+    const safeCode = typeof code === 'string' && /^[a-z_]{1,80}$/.test(code) ? code : undefined;
+    super(`Primitive returned HTTP ${status ?? 'unknown'}${safeCode ? ` (${safeCode})` : ''}.${status === 401 ? ' Stop and ask the owner for a fresh invitation.' : ''}`);
+    this.status = status;
+    this.code = safeCode;
+  }
+}
+
+function fail(message) { throw new Error(message); }
+function json(text) {
+  try { return JSON.parse(text); }
+  catch { fail('Invalid JSON. Inspect private state without printing credentials.'); }
+}
+async function optionalFile(path) {
+  try { return await readFile(path, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+async function writePrivate(path, value) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const file = await open(temporary, 'wx', 0o600);
+  try {
+    await file.writeFile(`${JSON.stringify(value, null, 2)}\n`);
+    await file.sync();
+    await file.close();
+    await rename(temporary, path);
+  } finally {
+    await file.close();
+    await rm(temporary, { force: true });
+  }
+}
+function invitationToken(instruction) {
+  const matches = instruction.match(/https:\/\/api\.primitive\.dev\/v1\/agent-connections\/setup[^\s<>"']*/g);
+  if (matches?.length !== 1) fail('Supply one owner-provided setup URL or copied instruction on stdin.');
+  const url = new URL(matches[0]);
+  const fragment = new URLSearchParams(url.hash.slice(1));
+  const token = fragment.get('token');
+  if (url.origin !== ORIGIN || url.pathname !== '/v1/agent-connections/setup' || url.search ||
+      url.username || url.password || fragment.size !== 1 || !token || /\s/.test(token)) {
+    fail('Invalid setup URL. Get a fresh instruction from the owner app.');
+  }
+  return token;
+}
+function validateState(value) {
+  if (!value || typeof value.api_key !== 'string' || !value.api_key ||
+      value.api_base_url !== API || typeof value.org_id !== 'string' || !value.org_id ||
+      typeof value.owner_address !== 'string' || !value.owner_address.includes('@') ||
+      typeof value.connection?.address !== 'string' || !value.connection.address.includes('@')) {
+    fail('Invalid connection credential response. Get a fresh owner invitation if claiming failed.');
+  }
+  return value;
+}
+function summary(state) {
+  return {
+    address: state.connection.address,
+    owner_address: state.owner_address,
+    org_id: state.org_id,
+    credential_saved: true,
+    verification: 'Confirm with the owner app after replying using this credential.',
+  };
+}
+async function call(fetcher, url, options) {
+  let response;
+  try { response = await fetcher(url, { ...options, redirect: 'error', signal: AbortSignal.timeout(35000) }); }
+  catch { fail('Request outcome is unknown. Do not blindly retry a claim or send; reconcile or obtain a fresh invitation.'); }
+  let envelope;
+  try { envelope = await response.json(); }
+  catch { fail('Unreadable API response. A mutation may have succeeded; do not blindly retry it.'); }
+  if (!response.ok || envelope.success === false) {
+    throw new PrimitiveApiError(response.status, envelope?.error?.code);
+  }
+  return envelope;
+}
+
+export async function run(args, { input = '', directory, fetcher = fetch } = {}) {
+  const stateDir = directory ?? process.env.PRIMITIVE_AGENT_STATE_DIR ?? join(homedir(), '.local', 'state', 'primitive-connect');
+  await mkdir(stateDir, { recursive: true, mode: 0o700 });
+  await chmod(stateDir, 0o700);
+  const statePath = join(stateDir, 'connection.json');
+  const [command, method, path, idempotencyKey] = args;
+  if (command === 'claim') {
+    if (args.length !== 1) fail('Pass the setup instruction on stdin, never as a command argument.');
+    const token = invitationToken(input);
+    const digest = createHash('sha256').update(token).digest('hex');
+    const lockPath = join(stateDir, 'claim.lock');
+    try { await mkdir(lockPath, { mode: 0o700 }); }
+    catch (error) {
+      if (error.code === 'EEXIST') fail('A claim is running or was interrupted. Check that process before removing the private claim.lock directory.');
+      throw error;
+    }
+    try {
+      const previousText = await optionalFile(statePath);
+      const previous = previousText ? validateState(json(previousText)) : null;
+      if (previous?.invitation_sha256 === digest) return summary(previous);
+      const pendingPath = join(stateDir, 'pending-claim.json');
+      const pending = await optionalFile(pendingPath);
+      if (pending && json(pending).invitation_sha256 === digest) {
+        fail('This invitation was already attempted. Its one-time response may be lost; ask the owner for a fresh invitation.');
+      }
+      await writePrivate(pendingPath, { invitation_sha256: digest, attempted_at: new Date().toISOString() });
+      const envelope = await call(fetcher, `${API}/agent-connections/claim`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({ token }),
+      });
+      const state = validateState(envelope.data);
+      if (previous && (previous.org_id !== state.org_id || previous.connection.address !== state.connection.address ||
+          previous.owner_address !== state.owner_address)) {
+        fail('The invitation changes the saved identity or owner. Existing state was preserved. Confirm the intended identity with the owner.');
+      }
+      await writePrivate(statePath, { ...state, invitation_sha256: digest });
+      await rm(pendingPath, { force: true });
+      return summary(state);
+    } finally { await rm(lockPath, { recursive: true, force: true }); }
+  }
+  const saved = await optionalFile(statePath);
+  if (!saved) fail('No saved connection. Claim the owner-provided setup instruction first.');
+  const state = validateState(json(saved));
+  if (command === 'status' && args.length === 1) return summary(state);
+  if (command !== 'request' || !method || !path || args.length > 4) {
+    fail('Usage: connection.mjs claim | status | request METHOD /path [idempotency-key]. JSON bodies come from stdin.');
+  }
+  const url = new URL(`${API}${path}`);
+  if (!url.pathname.startsWith('/v1/')) fail('This helper supports only the documented address-scoped email and notes paths.');
+  const pathname = url.pathname.slice('/v1'.length);
+  let ownNote = false;
+  if (method === 'PUT') {
+    const parts = pathname.split('/');
+    if (parts.length === 4 && parts[1] === 'address-notes') {
+      let address, name;
+      try { address = decodeURIComponent(parts[2]); name = decodeURIComponent(parts[3]); }
+      catch { fail('Invalid address-note path encoding.'); }
+      ownNote = address === state.connection.address && Boolean(name) && !name.includes('/');
+      if (ownNote) url.pathname = `/v1/address-notes/${encodeURIComponent(address)}/${encodeURIComponent(name)}`;
+    }
+  }
+  const uuid = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+  const conversationRead = method === 'GET' && !url.search && (
+    new RegExp(`^/threads/${uuid}$`, 'i').test(pathname) ||
+    new RegExp(`^/emails/${uuid}/conversation$`, 'i').test(pathname)
+  );
+  const allowed = url.pathname.startsWith('/v1/') && url.origin === ORIGIN && !url.hash && !url.username && !url.password && path.startsWith('/') && (
+    (method === 'GET' && (/^\/(emails|sent-emails)(\/[^/]+)?$/.test(pathname) || pathname === '/address-notes')) ||
+    conversationRead ||
+    (method === 'POST' && pathname === '/send-mail') ||
+    (method === 'PUT' && ownNote)
+  );
+  if (!allowed) fail('This helper supports only the documented address-scoped email, thread and notes paths.');
+  const headers = { Authorization: `Bearer ${state.api_key}`, Accept: 'application/json' };
+  let body;
+  if (method !== 'GET') {
+    body = json(input);
+    if (!body || typeof body !== 'object' || Array.isArray(body)) fail('Expected a JSON object on stdin.');
+    if (method === 'POST') {
+      if (!idempotencyKey || /[\r\n]/.test(idempotencyKey)) fail('Provide a stable idempotency key for sending.');
+      if (body.from && body.from !== state.connection.address) fail('The sender must match the saved connection address.');
+      body.from = state.connection.address;
+      headers['Idempotency-Key'] = idempotencyKey;
+    }
+    headers['Content-Type'] = 'application/json';
+  }
+  return call(fetcher, url.href, { method, headers, ...(body ? { body: JSON.stringify(body) } : {}) });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const args = process.argv.slice(2);
+    const needsInput = args[0] === 'claim' || (args[0] === 'request' && args[1] !== 'GET');
+    let input = '';
+    if (needsInput) {
+      for await (const chunk of process.stdin) {
+        input += chunk;
+        if (input.length > 1024 * 1024) fail('Input is too large.');
+      }
+    }
+    console.log(JSON.stringify(await run(args, { input }), null, 2));
+  } catch (error) {
+    // Never print response bodies, request bodies, URLs, or raw runtime exceptions.
+    const known = error instanceof PrimitiveApiError || (error instanceof Error && error.constructor === Error);
+    console.error(known ? error.message : 'Local connection operation failed. Check private storage and permissions.');
+    process.exitCode = 1;
+  }
+}

package/dist/skills/primitive-connect/scripts/mail.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { prepareSignalEmail, sendPreparedSignal } from '@primitivedotdev/sdk/interactions';
+import { PrimitiveApiError, run as connection } from './connection.mjs';
+
+export const commands = Object.freeze({
+  send: 'send OPERATION_ID < message.json    {"to":"...","subject":"...","text":"..."}',
+  reply: 'reply EMAIL_ID OPERATION_ID < reply.txt',
+  signal: 'signal EMAIL_ID OPERATION_ID < signal.json    {"kind":"typing"}, {"kind":"working"}, {"kind":"read"}, or {"kind":"ack","status":"received"}',
+});
+export const help = `Usage: mail.mjs ${Object.values(commands).join('\n       mail.mjs ')}\n\nEMAIL_ID is a received email record ID. Reuse OPERATION_ID for the same operation.\nBodies come from stdin. Signals are ordinary emails. Verify the sender before replying or reporting progress.`;
+class MailError extends Error {}
+function check(value, message) { if (!value) throw new MailError(message); }
+function address(value) {
+  check(typeof value === 'string' && value.length <= 320 && /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/.test(value), 'Expected a bare email address.');
+  return value.toLowerCase();
+}
+function header(value) {
+  check(typeof value === 'string' && value.trim() && Buffer.byteLength(value, 'utf8') <= 998 && !/[\x00-\x1f\x7f]/.test(value), 'Missing or invalid email threading header.');
+  return value;
+}
+function bodyText(value) {
+  check(typeof value === 'string' && value.trim() && value.length <= 100000, 'Supply a nonempty message of up to 100,000 characters.');
+  return value;
+}
+async function read(path) {
+  try { return JSON.parse(await readFile(path, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+async function save(path, value) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const file = await open(temporary, 'wx', 0o600);
+  try {
+    await file.writeFile(JSON.stringify(value));
+    await file.sync();
+    await file.close();
+    await rename(temporary, path);
+    // Windows FlushFileBuffers requires a writable handle; directories use read handles.
+    if (process.platform !== 'win32') {
+      const directory = await open(dirname(path), 'r');
+      try { await directory.sync(); }
+      finally { await directory.close(); }
+    }
+  } finally {
+    await file.close();
+    await rm(temporary, { force: true });
+  }
+}
+function receipt(data) {
+  check(typeof data?.id === 'string' && data.id.length > 0, 'Send outcome is unknown. Reconcile using the same operation ID.');
+  return { id: data.id, status: typeof data.status === 'string' ? data.status : 'accepted' };
+}
+
+/** Optional adapter: inject the runtime's existing credential transport. Never claim again. */
+export function createMailer({ identity, request, directory, now = Date.now, uuid = randomUUID }) {
+  const own = address(identity.address);
+  check(typeof identity.org_id === 'string' && identity.org_id, 'Pin the organization from the connection claim.');
+  check(typeof directory === 'string' && directory, 'Choose private durable outbox storage.');
+  const scope = { address: own, org_id: identity.org_id };
+  async function parent(id, signalOnly = false) {
+    check(typeof id === 'string' && /^[a-zA-Z0-9-]{1,128}$/.test(id), 'Supply a received email record ID.');
+    const message = (await request('GET', `/emails/${encodeURIComponent(id)}`)).data;
+    check(address(message.recipient) === own && address(message.from_email) !== own, 'The parent must be incoming mail addressed to this agent.');
+    if (signalOnly) {
+      const parts = message.parsed?.attachments ?? message.attachments;
+      check(Array.isArray(parts), 'Inspect the parent attachment inventory before reporting progress.');
+      check(!parts.some(part => part.filename?.toLowerCase() === 'interaction.json'), 'Do not automatically report progress on interaction emails.');
+    }
+    const references = message.references ?? message.parsed?.references ?? [];
+    check(Array.isArray(references), 'Invalid parent references.');
+    return {
+      accountScope: identity.org_id, from: address(message.from_email), to: own,
+      messageId: header(message.message_id), subject: header(message.subject || 'Conversation'),
+      references: references.map(header),
+    };
+  }
+  async function operation(id, intent, prepare) {
+    check(typeof id === 'string' && /^[a-zA-Z0-9:_-]{1,128}$/.test(id), 'Use a stable operation ID of up to 128 letters, digits, colons, underscores, or hyphens.');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    const hash = createHash('sha256').update(JSON.stringify([scope, id])).digest('hex');
+    const path = join(directory, `${hash}.json`), lock = join(directory, `${hash}.lock`);
+    try { await mkdir(lock, { mode: 0o700 }); }
+    catch (error) {
+      if (error.code === 'EEXIST') throw new MailError('This operation is running or was interrupted. Inspect its process before removing the private lock directory.');
+      throw error;
+    }
+    try {
+      let record = await read(path);
+      if (record) {
+        check(JSON.stringify(record.scope) === JSON.stringify(scope) && JSON.stringify(record.intent) === JSON.stringify(intent), 'This operation ID already belongs to a different message.');
+      } else {
+        record = { scope, intent, prepared: await prepare(), attempted: false, receipt: null };
+        await save(path, record);
+      }
+      if (record.receipt) return record.receipt;
+      const prepared = record.prepared;
+      if (record.attempted) {
+        const found = (await request('GET', `/sent-emails?idempotency_key=${encodeURIComponent(prepared.idempotencyKey)}`)).data;
+        const body = JSON.parse(prepared.requestJson);
+        check(Array.isArray(found), 'Unable to reconcile this send. Keep its operation ID.');
+        const matches = found.filter(row => row.from_address?.toLowerCase() === own && row.to_address?.toLowerCase() === body.to.toLowerCase());
+        check(matches.length === 1, 'Send outcome is still unknown. Keep the same operation ID and check again; do not send a duplicate.');
+        record.receipt = receipt(matches[0]);
+        await save(path, record);
+        return record.receipt;
+      }
+      if (prepared.expiresAtMs !== null && now() >= prepared.expiresAtMs)
+        return { status: 'expired' };
+      record.attempted = true;
+      await save(path, record);
+      const send = async (body, key) => {
+        try { return (await request('POST', '/send-mail', body, key)).data; }
+        catch (error) {
+          // Only a typed send refusal proves deletion. Missing reads remain unknown.
+          if (!(error instanceof PrimitiveApiError) || error.status !== 410 || error.code !== 'sent_email_deleted') throw error;
+          record.receipt = { status: 'deleted' };
+          await save(path, record);
+          return null;
+        }
+      };
+      const result = intent.kind === 'signal'
+        ? await sendPreparedSignal(send, prepared, { accountScope: identity.org_id, now })
+        : { status: 'response', result: await send(JSON.parse(prepared.requestJson), prepared.idempotencyKey) };
+      if (record.receipt) return record.receipt;
+      if (result.status === 'expired') {
+        record.attempted = false;
+        await save(path, record);
+        return { status: 'expired' };
+      }
+      record.receipt = receipt(result.result);
+      await save(path, record);
+      return record.receipt;
+    } finally { await rm(lock, { recursive: true, force: true }); }
+  }
+  const preparedMail = body => ({ accountScope: identity.org_id, expiresAtMs: null, idempotencyKey: uuid(), requestJson: JSON.stringify(body) });
+  return {
+    send: (id, { to, subject, text }) => operation(id, { kind: 'send', to, subject, text }, async () =>
+      preparedMail({ from: own, to: address(to), subject: header(subject), body_text: bodyText(text) })),
+    reply: (id, emailId, text) => operation(id, { kind: 'reply', emailId, text }, async () => {
+      const p = await parent(emailId);
+      return preparedMail({ from: own, to: p.from, subject: p.subject,
+        body_text: bodyText(text), in_reply_to: p.messageId, references: [...new Set([...p.references, p.messageId])] });
+    }),
+    signal: (id, emailId, input) => operation(id, { kind: 'signal', emailId, input }, async () => {
+      check(input && ['ack', 'read', 'working', 'typing'].includes(input.kind), 'Choose ack, read, working, or typing.');
+      const p = await parent(emailId, true);
+      const result = prepareSignalEmail({ ...input, parent: p,
+        ...(['working', 'typing'].includes(input.kind) ? { expiresAtMs: now() + (input.kind === 'typing' ? 30000 : 60000) } : {}) }, { now, uuid });
+      check(result.status === 'prepared', 'Wait for the parent email Message-ID before reporting progress.');
+      return result.prepared;
+    }),
+  };
+}
+
+export async function run(args, { input = '', directory, fetcher } = {}) {
+  if (!args.length || (args.length === 1 && ['help', '--help'].includes(args[0]))) return help;
+  const [command, first, second] = args;
+  check(Object.hasOwn(commands, command) && args.length === (command === 'send' ? 2 : 3), help);
+  const root = directory ?? process.env.PRIMITIVE_AGENT_STATE_DIR ?? join(homedir(), '.local', 'state', 'primitive-connect');
+  const options = { directory: root, fetcher };
+  const identity = await connection(['status'], options);
+  const mail = createMailer({ identity, directory: join(root, 'outbox'), request: (method, path, body, key) =>
+    connection(['request', method, path, ...(key ? [key] : [])], { ...options, input: body ? JSON.stringify(body) : '' }) });
+  if (command === 'reply') return mail.reply(second, first, input);
+  let value;
+  try { value = JSON.parse(input); } catch { throw new MailError('Supply valid JSON on stdin.'); }
+  return command === 'send' ? mail.send(first, value) : mail.signal(second, first, value);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const args = process.argv.slice(2);
+    let input = '';
+    const needsInput = Object.hasOwn(commands, args[0]) && args.length === (args[0] === 'send' ? 2 : 3);
+    if (needsInput) for await (const chunk of process.stdin) {
+      input += chunk;
+      check(input.length <= 1024 * 1024, 'Input is too large.');
+    }
+    const result = await run(args, { input });
+    console.log(typeof result === 'string' ? result : JSON.stringify(result));
+  } catch (error) {
+    console.error(error instanceof MailError ? error.message : 'Mail operation failed. Inspect private connection state and reconcile using the same operation ID.');
+    process.exitCode = 1;
+  }
+}

package/dist/skills/primitive-connect.json

@@ -0,0 +1,21 @@
+{
+  "name": "primitive-connect",
+  "version": "743a3ee630e9d621",
+  "source": {
+    "repository": "https://github.com/primitivedotdev/skills",
+    "path": "skills/primitive-connect",
+    "commit": "1660f99f967bd0dfbec0547916fa25b1d7e85494"
+  },
+  "files": {
+    "SKILL.md": "b1e03a6fa6c6df81320368924c39f28b311f45154aede9e73085b930eb589a28",
+    "package-lock.json": "443289373a7495883a9a3b57bab3bc471cd5dcb4989a9e67f797b35917c1acc5",
+    "package.json": "8cc45b2c28ba415960c9b85f6c1449f15f9c10bac0b96922e7907b40d50e3dbf",
+    "references/communication.md": "c931aada9553a8592088c28de5b272d5e0a15234aa9c9318ea7d1d5f69b39a79",
+    "references/contact-requests.md": "7923bc855a56f11b088c73c73b7d9c5b04fef3f45eb758f28040d44e46a0d9c6",
+    "references/native-session.md": "d6d529d87edc68a450be4c8b162488efa666c59fc23c35576fe6887235ff3d33",
+    "references/private-api-fallback.md": "19831f63dade9228e82c01a7573c23ae5474d97a79df75958b3e390b5bc4c531",
+    "scripts/check-cli-capabilities.mjs": "e6d4c045601f7d3b5cec103bdb3648723b8e66ebd22d87aca606fb78aed844fd",
+    "scripts/connection.mjs": "fd7bc74e413d2fb864589dc1b164d907fdb9bf37b46692ee0f89bc583dae9212",
+    "scripts/mail.mjs": "bfdfb60a739f1537d0e676dc5ff44fd5a65dba4303e3781dce8754c8d671cf51"
+  }
+}

package/man/primitive.1

@@ -20,6 +20,29 @@ Most commands print human-readable output by default. Commands that expose JSON
 .B --json
 flag or use generated operation output that can be piped into tools such as
 .BR jq (1).
+.PP
+With
+.BR --json ,
+stdout is exactly one JSON document, on success and on failure, and stderr
+stays empty, so output merged with 2>&1 still parses. Notices the command
+would print on stderr go in the document's
+.B warnings
+array; a failure adds
+.B error
+and
+.BR exit_code .
+Generated API commands keep their usual stdout shape with
+.BR --json :
+the data payload only. They do not print the
+.B next cursor:
+line then; add
+.B --envelope
+to get the full response envelope, with the pagination cursor in
+.B meta.cursor
+and empty-result hints in
+.BR summary .
+.B primitive listen
+streams JSONL and is not covered by this rule.
 .SH LOCAL WEBHOOK EVENTS
 .PP
 .B primitive listen
@@ -312,6 +335,19 @@ chat sent the message but no reply arrived before the timeout. Wait; do not rese
 .B 4
 .BR uncertain :
 transport error, conflict, server error, or a send record with status unknown. The message may have gone out; check sent history before retrying.
+.PP
+Every
+.B --json
+envelope from these commands carries
+.B sent_email_id
+(null until a send record is known) and
+.BR idempotency_key ,
+including on an uncertain outcome. Reconcile with
+.BR "primitive sent get --idempotency-key KEY" ;
+not_found means no record is visible yet, not that nothing was created, so
+retry only with the same
+.BR --idempotency-key ,
+never a new one.
 .SH ENVIRONMENT
 .TP
 .B PRIMITIVE_API_KEY

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primcli",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,
@@ -145,6 +145,9 @@
       },
       "agent:notes": {
         "description": "Read and maintain organization address notes. Connected profiles default to their own address and can write only their own notes. Use agent notes list|get|set|delete; new notes are private, and updates preserve visibility unless explicitly changed. Commands return JSON by default."
+      },
+      "agent:working": {
+        "description": "Short, expiring work claims stored in the AGENT_WORKING address note. Set a claim when work starts, clear it when work ends, and check a peer's claim with get --address before editing a shared file. Claims are advisory, not locks."
       }
     },
     "topicSeparator": " "