zyndo 0.2.1 → 0.3.0

package/dist/commands/referee.d.ts

@@ -0,0 +1,8 @@
+import { type SellerConfig } from '../config.js';
+export type RefereeCommandDeps = Readonly<{
+    loadConfig: () => SellerConfig;
+    httpFetch: typeof fetch;
+    stderr: (msg: string) => void;
+    stdout: (msg: string) => void;
+}>;
+export declare function handleRefereeCommand(args: ReadonlyArray<string>, deps?: RefereeCommandDeps): Promise<void>;

package/dist/commands/referee.js

@@ -0,0 +1,86 @@
+// ---------------------------------------------------------------------------
+// zyndo referee — Slice 3b
+//
+// Opt a skill into (or out of) Kimi K2.5 referee sampling. The command
+// connects as the configured seller to obtain a short-lived session token,
+// then POSTs to /agent/skills/:skillId/referee.
+//
+// Both the config loader and HTTP client are injectable so the unit test can
+// drive the command without hitting the network.
+// ---------------------------------------------------------------------------
+import { loadSellerConfig } from '../config.js';
+const DEFAULT_DEPS = {
+    loadConfig: () => loadSellerConfig(),
+    httpFetch: fetch,
+    stderr: (msg) => process.stderr.write(msg),
+    stdout: (msg) => process.stdout.write(msg)
+};
+export async function handleRefereeCommand(args, deps = DEFAULT_DEPS) {
+    const [subcommand, skillId] = args;
+    if (subcommand !== 'enable' && subcommand !== 'disable') {
+        deps.stderr('Usage: zyndo referee <enable|disable> <skillId>\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (skillId === undefined || skillId.length === 0) {
+        deps.stderr('Missing skillId. Usage: zyndo referee <enable|disable> <skillId>\n');
+        process.exitCode = 1;
+        return;
+    }
+    const enabled = subcommand === 'enable';
+    let config;
+    try {
+        config = deps.loadConfig();
+    }
+    catch (err) {
+        deps.stderr(`Failed to load seller config: ${err.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // Step 1 — fresh connect to obtain a session bearer token. We re-use the
+    // existing seller config (skills, categories, name). The broker will
+    // register a new ephemeral session; this is fine for a one-shot CLI call.
+    const connectRes = await deps.httpFetch(`${config.bridgeUrl}/agent/connect`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'x-zyndo-api-key': config.apiKey
+        },
+        body: JSON.stringify({
+            role: 'seller',
+            name: config.name,
+            description: config.description,
+            skills: config.skills.map((s) => ({
+                id: s.id,
+                name: s.name,
+                description: s.description,
+                priceCents: s.priceCents
+            })),
+            categories: config.categories,
+            maxConcurrentTasks: config.maxConcurrentTasks
+        })
+    });
+    if (!connectRes.ok) {
+        const body = await connectRes.text().catch(() => '');
+        deps.stderr(`Connect failed (${connectRes.status}): ${body}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const session = (await connectRes.json());
+    // Step 2 — POST the opt-in state.
+    const refereeRes = await deps.httpFetch(`${config.bridgeUrl}/agent/skills/${encodeURIComponent(skillId)}/referee`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${session.token}`
+        },
+        body: JSON.stringify({ enabled })
+    });
+    if (!refereeRes.ok) {
+        const body = await refereeRes.text().catch(() => '');
+        deps.stderr(`Referee ${subcommand} failed (${refereeRes.status}): ${body}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    deps.stdout(`Referee ${enabled ? 'enabled' : 'disabled'} for skill ${skillId}.\n`);
+}

package/dist/config.d.ts

@@ -2,15 +2,42 @@ export type ProviderName = 'anthropic' | 'openai' | 'ollama' | 'claude-code';
 export type HarnessName = 'claude' | 'codex' | 'generic';
 export declare const MIN_SKILL_PRICE_CENTS = 10;
 export declare const MAX_SKILL_PRICE_CENTS = 1000000;
+export type DeliverableItemConfig = Readonly<{
+    name: string;
+    quantity: number;
+    unit: string;
+    format: string;
+    specHints?: string;
+}>;
+export type RevisionPolicyConfig = Readonly<{
+    maxRevisions: number;
+    revisionScope: 'same-deliverable' | 'minor-tweaks-only';
+}>;
+export type SkillDeliverablesConfig = Readonly<{
+    summary: string;
+    items: ReadonlyArray<DeliverableItemConfig>;
+    inScope: ReadonlyArray<string>;
+    outOfScope: ReadonlyArray<string>;
+    revisionPolicy: RevisionPolicyConfig;
+    turnaroundHours: number;
+}>;
 export type SellerSkillConfig = Readonly<{
     id: string;
     name: string;
     description: string;
     priceCents: number;
+    deliverables?: SkillDeliverablesConfig;
 }>;
+export declare const MAX_DELIVERABLE_QUANTITY = 1000;
+export declare const MAX_DELIVERABLE_ITEMS = 10;
+export declare const MIN_SCOPE_BULLETS = 3;
+export declare const MAX_SCOPE_BULLETS = 10;
+export declare const MAX_TURNAROUND_HOURS = 168;
+export declare const MAX_REVISIONS = 5;
 export type SellerConfig = Readonly<{
     apiKey: string;
     bridgeUrl: string;
+    id?: string;
     name: string;
     description: string;
     skills: ReadonlyArray<SellerSkillConfig>;
@@ -26,6 +53,7 @@ export type SellerConfig = Readonly<{
     claudeCodeBinary?: string;
     claudeCodeTimeoutMs?: number;
     claudeCodeMaxBudgetUsd?: number;
+    identityKeyPath?: string;
 }>;
 export type BuyerConfig = Readonly<{
     apiKey: string;

package/dist/config.js

@@ -6,6 +6,13 @@ import { parse as parseYaml } from 'yaml';
 // in sync if the contract floor or cap ever changes.
 export const MIN_SKILL_PRICE_CENTS = 10;
 export const MAX_SKILL_PRICE_CENTS = 10_000_00;
+// Keep in sync with @zyndo/contracts SkillDeliverables caps.
+export const MAX_DELIVERABLE_QUANTITY = 1_000;
+export const MAX_DELIVERABLE_ITEMS = 10;
+export const MIN_SCOPE_BULLETS = 3;
+export const MAX_SCOPE_BULLETS = 10;
+export const MAX_TURNAROUND_HOURS = 168;
+export const MAX_REVISIONS = 5;
 // ---------------------------------------------------------------------------
 // Loader
 // ---------------------------------------------------------------------------
@@ -30,6 +37,10 @@ export function loadSellerConfig(configPath) {
     const data = parseYaml(raw);
     const apiKey = optionalString(data, 'api_key') ?? '';
     const bridgeUrl = optionalString(data, 'bridge_url') ?? DEFAULT_BRIDGE_URL;
+    const id = optionalString(data, 'id');
+    if (id !== undefined && !/^[a-z0-9][a-z0-9-]*[a-z0-9]$/i.test(id)) {
+        throw new Error(`Config: "id" must be a slug (letters, digits, hyphens; must start and end alphanumeric). Got: "${id}"`);
+    }
     const name = requireString(data, 'name');
     const description = requireString(data, 'description');
     const provider = requireEnum(data, 'provider', ['anthropic', 'openai', 'ollama', 'claude-code']);
@@ -77,6 +88,7 @@ export function loadSellerConfig(configPath) {
     }
     const claudeCodeTimeoutMs = typeof data.claude_code_timeout_ms === 'number' ? data.claude_code_timeout_ms : undefined;
     const claudeCodeMaxBudgetUsd = typeof data.claude_code_max_budget_usd === 'number' ? data.claude_code_max_budget_usd : undefined;
+    const identityKeyPath = optionalString(data, 'identity_key_path');
     const skills = requireArray(data, 'skills').map((s) => {
         const skill = s;
         const id = requireString(skill, 'id');
@@ -96,7 +108,8 @@ export function loadSellerConfig(configPath) {
             id,
             name: requireString(skill, 'name'),
             description: requireString(skill, 'description'),
-            priceCents: rawPrice
+            priceCents: rawPrice,
+            deliverables: parseDeliverables(skill, id)
         };
     });
     const categories = Array.isArray(data.categories)
@@ -108,6 +121,7 @@ export function loadSellerConfig(configPath) {
     return {
         apiKey,
         bridgeUrl,
+        id,
         name,
         description,
         skills,
@@ -122,7 +136,8 @@ export function loadSellerConfig(configPath) {
         harness,
         claudeCodeBinary,
         claudeCodeTimeoutMs,
-        claudeCodeMaxBudgetUsd
+        claudeCodeMaxBudgetUsd,
+        identityKeyPath
     };
 }
 // ---------------------------------------------------------------------------
@@ -146,6 +161,95 @@ function requireEnum(data, key, allowed) {
     }
     return value;
 }
+function parseDeliverables(skill, skillId) {
+    const raw = skill.deliverables;
+    if (raw === undefined || raw === null) {
+        process.stderr.write(`[zyndo] Warning: skill "${skillId}" has no "deliverables" block. The broker will hide this skill from the marketplace until you publish a scope contract. Run \`zyndo init\` and follow the deliverables prompts, or edit seller.yaml directly. See skills.md "Scope Discipline".\n`);
+        return undefined;
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`Skill "${skillId}": "deliverables" must be an object.`);
+    }
+    const d = raw;
+    const summary = requireString(d, 'summary');
+    if (summary.length > 240) {
+        throw new Error(`Skill "${skillId}": deliverables.summary must be <= 240 characters.`);
+    }
+    const rawItems = d.items;
+    if (!Array.isArray(rawItems) || rawItems.length === 0) {
+        throw new Error(`Skill "${skillId}": deliverables.items must be a non-empty array.`);
+    }
+    if (rawItems.length > MAX_DELIVERABLE_ITEMS) {
+        throw new Error(`Skill "${skillId}": deliverables.items must have at most ${MAX_DELIVERABLE_ITEMS} entries.`);
+    }
+    const items = rawItems.map((it, idx) => {
+        if (typeof it !== 'object' || it === null || Array.isArray(it)) {
+            throw new Error(`Skill "${skillId}": deliverables.items[${idx}] must be an object.`);
+        }
+        const item = it;
+        const name = requireString(item, 'name');
+        const quantity = item.quantity;
+        if (typeof quantity !== 'number' || !Number.isInteger(quantity) || quantity < 1 || quantity > MAX_DELIVERABLE_QUANTITY) {
+            throw new Error(`Skill "${skillId}": deliverables.items[${idx}].quantity must be an integer between 1 and ${MAX_DELIVERABLE_QUANTITY}.`);
+        }
+        const unit = requireString(item, 'unit');
+        const format = requireString(item, 'format');
+        const specHints = optionalString(item, 'spec_hints') ?? optionalString(item, 'specHints');
+        return specHints !== undefined
+            ? { name, quantity, unit, format, specHints }
+            : { name, quantity, unit, format };
+    });
+    const inScope = parseScopeBullets(d, 'in_scope', skillId) ?? parseScopeBullets(d, 'inScope', skillId);
+    const outOfScope = parseScopeBullets(d, 'out_of_scope', skillId) ?? parseScopeBullets(d, 'outOfScope', skillId);
+    if (inScope === undefined) {
+        throw new Error(`Skill "${skillId}": deliverables.in_scope must be an array of ${MIN_SCOPE_BULLETS}-${MAX_SCOPE_BULLETS} strings.`);
+    }
+    if (outOfScope === undefined) {
+        throw new Error(`Skill "${skillId}": deliverables.out_of_scope must be an array of ${MIN_SCOPE_BULLETS}-${MAX_SCOPE_BULLETS} strings.`);
+    }
+    const rawRevision = d.revision_policy ?? d.revisionPolicy;
+    if (typeof rawRevision !== 'object' || rawRevision === null || Array.isArray(rawRevision)) {
+        throw new Error(`Skill "${skillId}": deliverables.revision_policy must be an object with max_revisions and revision_scope.`);
+    }
+    const rp = rawRevision;
+    const maxRevisions = rp.max_revisions ?? rp.maxRevisions;
+    if (typeof maxRevisions !== 'number' || !Number.isInteger(maxRevisions) || maxRevisions < 0 || maxRevisions > MAX_REVISIONS) {
+        throw new Error(`Skill "${skillId}": deliverables.revision_policy.max_revisions must be an integer between 0 and ${MAX_REVISIONS}.`);
+    }
+    const revisionScope = rp.revision_scope ?? rp.revisionScope;
+    if (revisionScope !== 'same-deliverable' && revisionScope !== 'minor-tweaks-only') {
+        throw new Error(`Skill "${skillId}": deliverables.revision_policy.revision_scope must be "same-deliverable" or "minor-tweaks-only".`);
+    }
+    const turnaroundRaw = d.turnaround_hours ?? d.turnaroundHours;
+    if (typeof turnaroundRaw !== 'number' || !Number.isInteger(turnaroundRaw) || turnaroundRaw < 1 || turnaroundRaw > MAX_TURNAROUND_HOURS) {
+        throw new Error(`Skill "${skillId}": deliverables.turnaround_hours must be an integer between 1 and ${MAX_TURNAROUND_HOURS}.`);
+    }
+    return {
+        summary,
+        items,
+        inScope,
+        outOfScope,
+        revisionPolicy: { maxRevisions, revisionScope },
+        turnaroundHours: turnaroundRaw
+    };
+}
+function parseScopeBullets(d, key, skillId) {
+    const raw = d[key];
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw)) {
+        throw new Error(`Skill "${skillId}": deliverables.${key} must be an array.`);
+    }
+    if (raw.length < MIN_SCOPE_BULLETS || raw.length > MAX_SCOPE_BULLETS) {
+        throw new Error(`Skill "${skillId}": deliverables.${key} must have between ${MIN_SCOPE_BULLETS} and ${MAX_SCOPE_BULLETS} bullets.`);
+    }
+    return raw.map((b, idx) => {
+        if (typeof b !== 'string' || b.length === 0 || b.length > 200) {
+            throw new Error(`Skill "${skillId}": deliverables.${key}[${idx}] must be a non-empty string <= 200 chars.`);
+        }
+        return b;
+    });
+}
 function requireArray(data, key) {
     const value = data[key];
     if (!Array.isArray(value) || value.length === 0) {

package/dist/connection.d.ts

@@ -11,6 +11,24 @@ export type AgentEvent = Readonly<{
     payload: Record<string, unknown>;
     createdAt: string;
 }>;
+export type DeliverableItemDetail = Readonly<{
+    name: string;
+    quantity: number;
+    unit: string;
+    format: string;
+    specHints?: string;
+}>;
+export type SkillDeliverablesSnapshot = Readonly<{
+    summary: string;
+    items: ReadonlyArray<DeliverableItemDetail>;
+    inScope: ReadonlyArray<string>;
+    outOfScope: ReadonlyArray<string>;
+    revisionPolicy: Readonly<{
+        maxRevisions: number;
+        revisionScope: 'same-deliverable' | 'minor-tweaks-only';
+    }>;
+    turnaroundHours: number;
+}>;
 export type TaskDetail = Readonly<{
     taskId: string;
     buyerAgentId: string;
@@ -24,6 +42,7 @@ export type TaskDetail = Readonly<{
         content: string;
     }>;
     createdAt: string;
+    deliverablesSnapshot?: SkillDeliverablesSnapshot;
 }>;
 export type TaskMessage = Readonly<{
     messageId: string;
@@ -45,6 +64,7 @@ export declare function connect(bridgeUrl: string, apiKey: string, opts: {
     }>;
     categories?: ReadonlyArray<string>;
     maxConcurrentTasks?: number;
+    sellerSlug?: string;
 }): Promise<AgentSession>;
 export declare function reconnect(session: AgentSession, apiKey: string, opts?: {
     role?: 'buyer' | 'seller';
@@ -54,7 +74,13 @@ export declare function reconnect(session: AgentSession, apiKey: string, opts?:
 export declare function heartbeat(session: AgentSession): Promise<void>;
 export declare function pollEvents(session: AgentSession, ack?: number): Promise<ReadonlyArray<AgentEvent>>;
 export declare function acceptTask(session: AgentSession, taskId: string): Promise<void>;
-export declare function deliverTask(session: AgentSession, taskId: string, content: string): Promise<void>;
+/**
+ * Slice 3b — register the seller's Ed25519 public key with the broker so
+ * subsequent signed deliveries can be verified. Safe to call on every daemon
+ * start; the broker upserts and tracks rotations.
+ */
+export declare function registerIdentity(session: AgentSession, publicKeyB64: string): Promise<void>;
+export declare function deliverTask(session: AgentSession, taskId: string, content: string, signatureB64?: string): Promise<void>;
 export declare function sendTaskMessage(session: AgentSession, taskId: string, type: 'question' | 'answer' | 'info', content: string): Promise<void>;
 export declare function getTaskMessages(session: AgentSession, taskId: string): Promise<ReadonlyArray<TaskMessage>>;
 export declare function getTaskDetail(session: AgentSession, taskId: string): Promise<TaskDetail | undefined>;

package/dist/connection.js

@@ -29,17 +29,20 @@ export async function connect(bridgeUrl, apiKey, opts) {
         'content-type': 'application/json',
         'x-zyndo-api-key': apiKey
     };
+    const body = {
+        role: opts.role,
+        name: opts.name,
+        description: opts.description,
+        skills: opts.skills ?? [],
+        categories: opts.categories ?? [],
+        maxConcurrentTasks: opts.maxConcurrentTasks ?? 3
+    };
+    if (opts.sellerSlug !== undefined)
+        body.sellerSlug = opts.sellerSlug;
     const res = await fetch(`${bridgeUrl}/agent/connect`, {
         method: 'POST',
         headers,
-        body: JSON.stringify({
-            role: opts.role,
-            name: opts.name,
-            description: opts.description,
-            skills: opts.skills ?? [],
-            categories: opts.categories ?? [],
-            maxConcurrentTasks: opts.maxConcurrentTasks ?? 3
-        })
+        body: JSON.stringify(body)
     });
     if (!res.ok) {
         const body = await res.text();
@@ -104,8 +107,23 @@ export async function acceptTask(session, taskId) {
         throw new Error(`Accept failed (${res.status}): ${await res.text()}`);
     }
 }
-export async function deliverTask(session, taskId, content) {
-    const res = await jsonPost(`${session.bridgeUrl}/agent/tasks/${taskId}/deliver`, { output: { type: 'text', content } }, session.token);
+/**
+ * Slice 3b — register the seller's Ed25519 public key with the broker so
+ * subsequent signed deliveries can be verified. Safe to call on every daemon
+ * start; the broker upserts and tracks rotations.
+ */
+export async function registerIdentity(session, publicKeyB64) {
+    const res = await jsonPost(`${session.bridgeUrl}/agent/identity/register`, { publicKeyB64 }, session.token);
+    if (!res.ok) {
+        throw new Error(`Identity register failed (${res.status}): ${await res.text()}`);
+    }
+}
+export async function deliverTask(session, taskId, content, signatureB64) {
+    const body = { output: { type: 'text', content } };
+    if (signatureB64 !== undefined) {
+        body.signature = signatureB64;
+    }
+    const res = await jsonPost(`${session.bridgeUrl}/agent/tasks/${taskId}/deliver`, body, session.token);
     if (!res.ok) {
         throw new Error(`Deliver failed (${res.status}): ${await res.text()}`);
     }

package/dist/identity.d.ts

@@ -0,0 +1,23 @@
+import { type KeyObject } from 'node:crypto';
+export type IdentityKeypair = Readonly<{
+    publicKeyB64: string;
+    privateKey: KeyObject;
+}>;
+/**
+ * Load an existing Ed25519 keypair from `keyPath`, or generate and persist a
+ * new one if the file does not yet exist. The private key is written as a
+ * PKCS#8 PEM with 0600 permissions. The public key is returned as SPKI DER
+ * base64 — the exact shape the broker's `seller_identities` projection
+ * stores.
+ */
+export declare function ensureIdentityKeypair(keyPath: string): IdentityKeypair;
+/**
+ * Sign a delivery payload for the broker. The signature covers
+ * `sha256(${taskId}|${content})` so the broker can reproduce the digest
+ * from the parsed request body.
+ */
+export declare function signDelivery(input: {
+    taskId: string;
+    content: string;
+    privateKey: KeyObject;
+}): string;

package/dist/identity.js

@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------------
+// Ed25519 identity helpers for the zyndo CLI.
+//
+// Sellers generate a keypair once at `init` time and reuse it to sign every
+// delivery body. The broker verifies the signature against a registered
+// SPKI DER public key so it can prove the delivery actually came from the
+// seller that owns the agent id, not a compromised API key.
+//
+// Zero external deps: everything is `node:crypto` + `node:fs`.
+// ---------------------------------------------------------------------------
+import { generateKeyPairSync, createHash, createPrivateKey, createPublicKey, sign as cryptoSign } from 'node:crypto';
+import { writeFileSync, readFileSync, mkdirSync, chmodSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Load an existing Ed25519 keypair from `keyPath`, or generate and persist a
+ * new one if the file does not yet exist. The private key is written as a
+ * PKCS#8 PEM with 0600 permissions. The public key is returned as SPKI DER
+ * base64 — the exact shape the broker's `seller_identities` projection
+ * stores.
+ */
+export function ensureIdentityKeypair(keyPath) {
+    if (!existsSync(keyPath)) {
+        mkdirSync(dirname(keyPath), { recursive: true, mode: 0o700 });
+        const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+        const pem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+        writeFileSync(keyPath, pem, { mode: 0o600 });
+        try {
+            chmodSync(keyPath, 0o600);
+        }
+        catch {
+            // Windows chmod is a no-op for non-owner bits; ignore failures.
+        }
+        const publicKeyB64 = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+        return { publicKeyB64, privateKey };
+    }
+    const pem = readFileSync(keyPath, 'utf8');
+    const privateKey = createPrivateKey(pem);
+    const publicKey = createPublicKey(privateKey);
+    const publicKeyB64 = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+    return { publicKeyB64, privateKey };
+}
+/**
+ * Sign a delivery payload for the broker. The signature covers
+ * `sha256(${taskId}|${content})` so the broker can reproduce the digest
+ * from the parsed request body.
+ */
+export function signDelivery(input) {
+    const digest = createHash('sha256').update(`${input.taskId}|${input.content}`).digest();
+    const signature = cryptoSign(null, digest, input.privateKey);
+    return signature.toString('base64');
+}

package/dist/index.js

@@ -10,6 +10,7 @@ import { startSellerDaemon } from './sellerDaemon.js';
 import { startMcpServer } from './mcp/mcpServer.js';
 import { printBanner } from './banner.js';
 import { handleWalletCommand, handleCashoutCommand, handleConnectCommand } from './commands/wallet.js';
+import { handleRefereeCommand } from './commands/referee.js';
 // Read version from package.json so it never drifts from the published
 // npm version. dist/index.js lives at <pkg>/dist/index.js, so the package
 // manifest is one level up. Fall back to "unknown" if the file is missing
@@ -65,6 +66,10 @@ async function main() {
             handleConnectCommand(args.slice(1));
             break;
         }
+        case 'referee': {
+            await handleRefereeCommand(args.slice(1));
+            break;
+        }
         case 'version':
             process.stdout.write(`zyndo ${getPackageVersion()}\n`);
             break;
@@ -90,6 +95,7 @@ Usage:
   zyndo wallet [balance|topup|ledger]  Manage wallet (opens dashboard)
   zyndo cashout                   View earnings and cashout (opens dashboard)
   zyndo connect [onboard|status]  Stripe Connect setup (opens dashboard)
+  zyndo referee <enable|disable> <skillId>  Toggle Kimi K2.5 referee sampling on a skill
   zyndo version                   Show version
   zyndo help                      Show this help