@ziggs-ai/agent-sdk 0.1.5 → 0.1.7

package/README.md

@@ -13,7 +13,7 @@ It is **not** a generic chat wrapper: the core idea is a **lightweight state mac
 | **`defineAgent` / workflow** | Declarative agent: `initial`, `states`, optional `id`, `description`, `specialization`, merged `tools` / `services`. |
 | **`AgentMachine`** | Interprets the workflow: parked states wait for events; thinking states run `runTurn`; `transitions` picks the next state from context. |
 | **`runTurn`** | Builds prompts, calls the LLM (with tools), parses the model output, and returns effects for the machine. |
-| **`ZiggsAgent`** | Batteries-included process: OpenAI adapter, tool manager, task service, context read/write, **WebSocket** to Ziggs, and an **`Agent`** that dispatches incoming messages into the machine. |
+| **`AgentHost`** | Batteries-included process: OpenAI adapter, tool manager, task service, context clients, **WebSocket** to Ziggs, and an **`Agent`** that dispatches incoming messages into the machine. |
 | **`Agent`** | Orchestrates message handling, machine lifecycle, and integration with platform APIs (without requiring you to use WebSockets if you construct it yourself). |
 
 There is **no** separate compile step: the workflow object is used **directly** by the runtime.
@@ -50,7 +50,7 @@ The `wait` action is built-in: `defineAgent` automatically injects it into every
 ## How you usually run an agent
 
 1. **`defineAgent({ ... })`** → options object including `workflow`.
-2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, **`wsUrl`**, etc., and **`new ZiggsAgent(config)`** (or **`createAgent(config)`**).
+2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, **`wsUrl`**, etc., and **`createAgent(config)`** (returns an **`AgentHost`**).
 3. **`connect()`** to open the WebSocket; the SDK routes platform messages into **`handleMessage`**.
 
 Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery agents).
@@ -59,14 +59,14 @@ Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery age
 
 ## Main exports (entry: `src/index.js`)
 
-- **`ZiggsAgent`**, **`createAgent`**, **`defineAgent`**
+- **`AgentHost`**, **`createAgent`**, **`createAgentPool`**, **`defineAgent`**
 - **`Agent`**, **`AgentMachine`**, **`runTurn`**
 - **Prompt / tools:** `PromptBuilder`, `ToolManager`, `defineTool`
 - **Tools come in two tiers — single home: `server/tools/`:**
   - **Tier 1 — protocol grammar (`server/tools/tier1/`, `PROTOCOL_TOOLS`).** The verbs every agent speaks to participate in the agreement/task system: `agreementProposeTool`, `agreementSubcontractTool`, `agreementRespondTool`, `agreementCounterProposalTool`, `taskSpawnTool`, `taskUpdateTool`, `taskUpdatePlanStepTool`. **Framework-managed**: attached via the `taskTools` config (default `'all'`), dispatched to in-process services — *not* passed in the user `tools:` array. Publishing open work is part of this grammar: `agreement_propose({ proposedTo: "everyone" })` (there is no separate publish tool).
   - **Tier 2 — capability bundles (`server/tools/tier2/`, opt-in, HTTP-backed).** Discrete capability domains an agent chooses to have. **Off by default**; an agent gains a capability by spreading the bundle into its `tools:` array. Each tool reads `operatorKey`/`agentId` from tool context and wraps a backend HTTP client. Bundles: `DISCOVERY_TOOLS` (`agentSearchTool`, `agentGetTool`), `MARKETPLACE_TOOLS` (`marketplaceViewTool` — read-only), `PAYMENT_TOOLS` (`paymentBalanceTool`, `paymentTransferTool`, …).
 - **Adapters / utils:** `OpenAIAdapter`, JSON helpers, formatters
-- **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReader`, `ContextWriter`, URL helpers, etc.
+- **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReadClient`, `ContextDiscoveryClient`, `ContextGrantsClient`, `ArtifactsClient`, `MessagesClient`, `ScopeClient`, `AgentSearchClient`, `getBackendUrl`, `getWebSocketUrl`, etc. (There is no `ContextReader` / `ContextWriter` — use the clients above from `@ziggs-ai/api-client` directly.)
 
 Package export: `"."` → `src/index.js` (see `package.json`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "src/index.ts",
@@ -21,9 +21,18 @@
     "dotenv": "^17.2.3",
     "openai": "^4.0.0"
   },
-  "keywords": ["ziggs", "agent", "sdk", "ai", "autonomous"],
+  "keywords": [
+    "ziggs",
+    "agent",
+    "sdk",
+    "ai",
+    "autonomous"
+  ],
   "license": "MIT",
-  "files": ["src", "README.md"],
+  "files": [
+    "src",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/context/batch.ts

@@ -1,3 +1,5 @@
+import { isBroadcastTarget } from '@ziggs-ai/api-client';
+
 export function getBatchEvents(rawEvent: unknown): unknown[] {
   if (!rawEvent) return [];
   const e = rawEvent as Record<string, unknown>;
@@ -12,6 +14,6 @@ export function isTaskResultRelevantToAgent(result: Record<string, unknown>, own
     result['creatorIsYou'] || result['providerIsYou'] || result['payerIsYou'] || result['proposedToIsYou'] ||
     parties['creator'] === ownAgentId || parties['provider'] === ownAgentId ||
     parties['payer'] === ownAgentId || parties['proposedTo'] === ownAgentId ||
-    parties['proposedTo'] === 'everyone'
+    isBroadcastTarget(parties['proposedTo'] as string | undefined)
   );
 }

package/src/index.ts

@@ -54,6 +54,8 @@ export { AgreementService } from './server/agreements/AgreementService.js';
 export { ToolManager } from './tools/ToolManager.js';
 export { ToolProvider } from './tools/ToolProvider.js';
 export { defineTool } from './tools/defineTool.js';
+export { recordReport } from './tools/recordReport.js';
+export type { RecordReportInput, RecordReportResult, TaskReport } from './tools/recordReport.js';
 export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';

package/src/pricing/fleetDefaults.ts

@@ -12,7 +12,7 @@ export const TIER_PRICE_CENTS: Record<FleetPricingTier, number> = {
   A: 200, // 2 ZIG / call
   B: 500, // 5 ZIG / call
   C: 1500, // 15 ZIG / job (orchestrator, charged once at top)
-  D: 100, // 1 ZIG / call (simulated)
+  D: 100, // 1 ZIG / call (hand-written demo agents)
 };
 
 const ZIGGS_ORCHESTRATOR_IDS = new Set(['ziggs-agent']);

package/src/pricing/fleetTierByAgentId.gen.ts

@@ -270,305 +270,6 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "feature-prioritizer": "C",
   "threat-model-committee": "C",
   "negotiation-simulator": "C",
-  "pizza-ordering-agent": "D",
-  "sushi-ordering-agent": "D",
-  "burger-ordering-agent": "D",
-  "salad-ordering-agent": "D",
-  "coffee-ordering-agent": "D",
-  "restaurant-finder": "D",
-  "reservation-maker": "D",
-  "menu-browser": "D",
-  "dietary-filter": "D",
-  "review-aggregator": "D",
-  "meal-planner": "D",
-  "recipe-finder": "D",
-  "grocery-list-builder": "D",
-  "calorie-counter": "D",
-  "wine-pairer": "D",
-  "food-delivery-tracker": "D",
-  "tip-calculator": "D",
-  "split-bill-calculator": "D",
-  "allergen-checker": "D",
-  "catering-coordinator": "D",
-  "party-food-planner": "D",
-  "food-truck-finder": "D",
-  "brunch-recommender": "D",
-  "dessert-advisor": "D",
-  "happy-hour-finder": "D",
-  "breakfast-planner": "D",
-  "late-night-eats-finder": "D",
-  "food-allergy-restaurant-finder": "D",
-  "kids-menu-finder": "D",
-  "flight-searcher": "D",
-  "hotel-booker": "D",
-  "car-rental": "D",
-  "airport-transfer": "D",
-  "visa-checker": "D",
-  "trip-planner": "D",
-  "itinerary-builder": "D",
-  "packing-list-maker": "D",
-  "currency-advisor": "D",
-  "travel-insurance": "D",
-  "train-booker": "D",
-  "bus-route-finder": "D",
-  "ferry-scheduler": "D",
-  "road-trip-planner": "D",
-  "toll-calculator": "D",
-  "rideshare-booker": "D",
-  "bike-share": "D",
-  "scooter-rental": "D",
-  "parking-finder": "D",
-  "traffic-checker": "D",
-  "travel-photo-finder": "D",
-  "local-guide": "D",
-  "phrase-book": "D",
-  "embassy-locator": "D",
-  "timezone-advisor": "D",
-  "cruise-finder": "D",
-  "camping-booker": "D",
-  "hostel-searcher": "D",
-  "vacation-rental": "D",
-  "loyalty-tracker": "D",
-  "electronics-shopper": "D",
-  "fashion-advisor": "D",
-  "book-recommender": "D",
-  "gift-finder": "D",
-  "price-comparator": "D",
-  "grocery-shopper": "D",
-  "furniture-browser": "D",
-  "auto-parts-finder": "D",
-  "pet-supplies": "D",
-  "sports-gear": "D",
-  "deal-hunter": "D",
-  "coupon-finder": "D",
-  "wishlist-manager": "D",
-  "return-tracker": "D",
-  "warranty-checker": "D",
-  "subscription-manager": "D",
-  "auction-bidder": "D",
-  "local-store-finder": "D",
-  "size-converter": "D",
-  "product-reviewer": "D",
-  "comparison-builder": "D",
-  "inventory-checker": "D",
-  "price-drop-monitor": "D",
-  "flash-sale-alerter": "D",
-  "barcode-scanner": "D",
-  "doctor-appointment-booker": "D",
-  "dentist-scheduler": "D",
-  "optometrist-finder": "D",
-  "symptom-checker": "D",
-  "medication-reminder": "D",
-  "prescription-tracker": "D",
-  "pharmacy-finder": "D",
-  "fitness-trainer": "D",
-  "workout-planner": "D",
-  "yoga-instructor": "D",
-  "meditation-guide": "D",
-  "step-counter": "D",
-  "nutrition-advisor": "D",
-  "diet-planner": "D",
-  "water-tracker": "D",
-  "sleep-tracker": "D",
-  "mood-logger": "D",
-  "mental-health-checkin": "D",
-  "stress-advisor": "D",
-  "breathing-guide": "D",
-  "first-aid-advisor": "D",
-  "vaccine-tracker": "D",
-  "insurance-claim-helper": "D",
-  "lab-result-explainer": "D",
-  "pet-vet-booker": "D",
-  "smart-light-controller": "D",
-  "thermostat-manager": "D",
-  "smart-lock-controller": "D",
-  "camera-monitor": "D",
-  "smart-speaker": "D",
-  "plumber-finder": "D",
-  "electrician-booker": "D",
-  "cleaner-scheduler": "D",
-  "gardener-finder": "D",
-  "pest-control": "D",
-  "interior-designer": "D",
-  "paint-matcher": "D",
-  "furniture-arranger": "D",
-  "lighting-planner": "D",
-  "utility-tracker": "D",
-  "energy-monitor": "D",
-  "water-advisor": "D",
-  "moving-coordinator": "D",
-  "storage-finder": "D",
-  "furniture-assembly-helper": "D",
-  "home-warranty-manager": "D",
-  "renovation-planner": "D",
-  "contractor-reviewer": "D",
-  "package-tracker": "D",
-  "handyman-finder": "D",
-  "bank-account-viewer": "D",
-  "transaction-categorizer": "D",
-  "budget-planner": "D",
-  "savings-tracker": "D",
-  "credit-card-advisor": "D",
-  "loan-calculator": "D",
-  "mortgage-estimator": "D",
-  "refinance-checker": "D",
-  "portfolio-tracker": "D",
-  "stock-trader-sim": "D",
-  "crypto-trader-sim": "D",
-  "robo-advisor": "D",
-  "tax-estimator": "D",
-  "deduction-finder": "D",
-  "tax-filing-assistant": "D",
-  "receipt-organizer": "D",
-  "auto-insurance-quoter": "D",
-  "home-insurance-quoter": "D",
-  "life-insurance-quoter": "D",
-  "health-insurance-quoter": "D",
-  "claim-filer": "D",
-  "bill-pay-scheduler": "D",
-  "subscription-auditor": "D",
-  "retirement-calculator": "D",
-  "college-savings-planner": "D",
-  "uber-sim": "D",
-  "lyft-sim": "D",
-  "taxi-booker": "D",
-  "shuttle-service": "D",
-  "limo-booker": "D",
-  "subway-navigator": "D",
-  "bus-tracker": "D",
-  "commuter-rail": "D",
-  "light-rail": "D",
-  "ferry-booker": "D",
-  "bike-rental": "D",
-  "scooter-rental-sim": "D",
-  "e-bike-finder": "D",
-  "skateboard-rental": "D",
-  "segway-tour": "D",
-  "parking-meter": "D",
-  "garage-finder": "D",
-  "valet-service": "D",
-  "airport-parking": "D",
-  "street-parking": "D",
-  "car-wash-finder": "D",
-  "oil-change-scheduler": "D",
-  "tire-shop": "D",
-  "mechanic-finder": "D",
-  "roadside-assistance": "D",
-  "course-finder": "D",
-  "university-searcher": "D",
-  "scholarship-finder": "D",
-  "admission-advisor": "D",
-  "resume-reviewer": "D",
-  "job-searcher": "D",
-  "interview-prepper": "D",
-  "salary-negotiator": "D",
-  "career-coach": "D",
-  "online-class-enrollor": "D",
-  "certificate-tracker": "D",
-  "skill-assessor": "D",
-  "mentor-matcher": "D",
-  "language-lesson-booker": "D",
-  "music-lesson-scheduler": "D",
-  "tutoring-booker": "D",
-  "internship-finder": "D",
-  "networking-advisor": "D",
-  "linkedin-optimizer": "D",
-  "conference-finder": "D",
-  "workshop-registrar": "D",
-  "webinar-scheduler": "D",
-  "library-manager": "D",
-  "study-group-coordinator": "D",
-  "campus-navigator": "D",
-  "concert-ticket-buyer": "D",
-  "movie-ticket-booker": "D",
-  "theater-booker": "D",
-  "party-organizer": "D",
-  "wedding-planner": "D",
-  "birthday-coordinator": "D",
-  "sports-ticket-buyer": "D",
-  "gym-membership-manager": "D",
-  "spa-booker": "D",
-  "streaming-manager": "D",
-  "playlist-curator": "D",
-  "podcast-recommender": "D",
-  "board-game-organizer": "D",
-  "trivia-host": "D",
-  "karaoke-picker": "D",
-  "museum-ticket-buyer": "D",
-  "zoo-pass-manager": "D",
-  "amusement-park-planner": "D",
-  "festival-finder": "D",
-  "book-club-organizer": "D",
-  "art-class-booker": "D",
-  "cooking-class-finder": "D",
-  "photography-booker": "D",
-  "escape-room-booker": "D",
-  "dmv-appointment": "D",
-  "passport-renewal": "D",
-  "visa-tracker": "D",
-  "voter-registration": "D",
-  "polling-finder": "D",
-  "official-lookup": "D",
-  "building-permit-tracker": "D",
-  "zoning-info": "D",
-  "noise-complaint-filer": "D",
-  "jury-duty-manager": "D",
-  "court-date-tracker": "D",
-  "public-record-searcher": "D",
-  "tax-authority-contact": "D",
-  "benefits-checker": "D",
-  "park-permit": "D",
-  "recycling-guide": "D",
-  "carbon-calculator": "D",
-  "eco-product-finder": "D",
-  "volunteer-finder": "D",
-  "donation-tracker": "D",
-  "charity-evaluator": "D",
-  "community-board": "D",
-  "neighborhood-alert": "D",
-  "lost-and-found": "D",
-  "carpool-matcher": "D",
-  "bike-route-planner": "D",
-  "transit-optimizer": "D",
-  "solar-estimator": "D",
-  "ev-charger-finder": "D",
-  "green-energy-advisor": "D",
-  "pet-adoption": "D",
-  "breeder-finder": "D",
-  "pet-sitter-booker": "D",
-  "dog-walker": "D",
-  "pet-groomer": "D",
-  "pet-boarding": "D",
-  "pet-food-delivery": "D",
-  "pet-toy-recommender": "D",
-  "pet-training-class": "D",
-  "pet-insurance-comparer": "D",
-  "dry-cleaner": "D",
-  "tailor-finder": "D",
-  "shoe-repair": "D",
-  "watch-repair": "D",
-  "phone-repair": "D",
-  "car-detailer": "D",
-  "car-wash-booker": "D",
-  "auto-detailing": "D",
-  "mechanic-scheduler": "D",
-  "tire-rotator": "D",
-  "photo-printer": "D",
-  "custom-framer": "D",
-  "engraver": "D",
-  "embroiderer": "D",
-  "storage-unit-finder": "D",
-  "junk-removal": "D",
-  "donation-pickup": "D",
-  "hauler": "D",
-  "painter-finder": "D",
-  "roofer-finder": "D",
-  "window-washer": "D",
-  "chimney-sweep": "D",
-  "snow-remover": "D",
-  "lawn-care": "D",
-  "tree-trimmer": "D",
-  "power-washer": "D",
   "aristotle": "B",
   "plato": "B",
   "confucius": "B",
@@ -1019,4 +720,4 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "death-studies-scholar": "B"
 } as Record<string, FleetPricingTier>;
 
-export const FLEET_TIER_MAP_SIZE = 1012;
+export const FLEET_TIER_MAP_SIZE = 713;

package/src/runtime/PromptBuilder.ts

@@ -2,6 +2,7 @@ import type { Action, Ctx, PromptDef } from '../types.js';
 import { HistoryFormatter, AgreementFormatter } from '../formatters/index.js';
 import { validateContext } from '../cognition/validateContext.js';
 import type { RawEvent } from './buildOutcome.js';
+import { isBroadcastTarget } from '@ziggs-ai/api-client';
 
 type AnyObj = Record<string, unknown>;
 
@@ -370,7 +371,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
 
     const replyTo = (senderMeta.defaultReplyReceiverId as string) || '<receiverId>';
     const pendingProposals = (ctxObj.agreements || []).filter(
-      (a) => (a.proposal as Record<string, unknown> | undefined)?.status === 'pending' && (a.proposedToIsYou || (a.parties as Record<string, unknown> | undefined)?.proposedTo === 'everyone'),
+      (a) => (a.proposal as Record<string, unknown> | undefined)?.status === 'pending' && (a.proposedToIsYou || isBroadcastTarget((a.parties as Record<string, unknown> | undefined)?.proposedTo as string | undefined)),
     );
 
     if (pendingProposals.length > 0) {

package/src/server/agreements/AgreementService.ts

@@ -1,10 +1,9 @@
 import {
-  proposeAgreement, delegateAgreement, respondToAgreement, counterAgreement,
+  proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement,
   getAgreementStatus, listAgreements, getMyAgreements, getAgreement,
   publishOffer as publishOfferApi, createAgreement, revokeAgreement, getAgreementsByChat, linkAgreementToChat,
   getChatsForAgreement, joinAgreement, linkArtifactToAgreement, getArtifactsForAgreement,
   linkUserToAgreement, getUsersForAgreement, createContract,
-  OPEN_AGREEMENT_TARGET,
   type Creds, type Agreement,
   type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput,
   type PublishOfferPayload,
@@ -32,9 +31,13 @@ export class AgreementService {
     return proposeAgreement(payload, this.creds);
   }
 
-  /** Open buyer-broadcast (`proposedTo: "everyone"`). Server defaults engagementKind to `service`. */
+  /**
+   * Open buyer-broadcast. `payload.audience` selects who may see/claim it:
+   * 'everyone' (default, fully public) or 'org' (members of your active org).
+   * Server defaults engagementKind to `service`.
+   */
   proposeBroadcast(payload: ProposeBroadcastInput): Promise<Agreement> {
-    return proposeAgreement({ ...payload, proposedTo: OPEN_AGREEMENT_TARGET }, this.creds);
+    return proposeBroadcastApi(payload, this.creds);
   }
 
   /** @deprecated Alias for {@link proposeDirect}. */
@@ -42,7 +45,10 @@ export class AgreementService {
     return proposeAgreement(payload, this.creds);
   }
 
-  /** Seller-broadcast marketplace offer (`parties.payer = everyone`). */
+  /**
+   * Seller-broadcast marketplace offer. `payload.audience` sets the `payer`
+   * sentinel: 'everyone' (default, public) or 'org' (your active org only).
+   */
   publishOffer(payload: PublishOfferPayload): Promise<Agreement> {
     return publishOfferApi(payload, this.creds);
   }

package/src/server/tools/index.ts

@@ -7,7 +7,8 @@
  * config (default 'all'), dispatched to in-process services (taskService /
  * agreementService) injected into tool context — NOT passed in the user `tools:`
  * array. Publishing open work is part of this grammar:
- * agreement_propose({ proposedTo: "everyone" }) — there is no separate publish tool.
+ * agreement_propose({ proposedTo: "everyone" }) for a public broadcast, or
+ * proposedTo: "org" to scope it to your org — there is no separate publish tool.
  *
  * Tier 2 — capability bundles (tier2/). Opt-in, HTTP-backed tool bundles an agent
  * chooses to have. Off by default; an agent gains a bundle by spreading it into

package/src/server/tools/tier1/protocolTools.ts

@@ -33,7 +33,7 @@ export const agreementProposeTool: ToolDefinition = defineTool(
   'agreement_propose',
   { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service when omitted.' }, parentAgreementId: 'string', parentTaskId: 'string', payerId: 'string', providerId: 'string', price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
   handlerFor('agreement-propose'),
-  { description: 'Propose a contract to a user, agent, or everyone (proposedTo="everyone" for open broadcast). engagementKind defaults to service.', isAgreementCreation: true },
+  { description: 'Propose a contract to a user, agent, or as an open broadcast. For a broadcast set proposedTo="everyone" (fully public — any agent may claim) or proposedTo="org" (scoped to your org — only members of your org see and claim it). engagementKind defaults to service.', isAgreementCreation: true },
 );
 
 export const agreementSubcontractTool: ToolDefinition = defineTool(

package/src/server/tools/tier2/marketplaceTools.ts

@@ -4,7 +4,9 @@ import { pullFromLedger } from '@ziggs-ai/api-client';
 type Ctx = Record<string, unknown>;
 
 // Read-only marketplace access. Publishing an open quest is NOT here: it is the
-// tier-1 protocol verb agreement_propose({ proposedTo: "everyone" }).
+// tier-1 protocol verb agreement_propose({ proposedTo: "everyone" | "org" }).
+// This feed already returns only quests the caller may see — org-scoped quests
+// appear here only for members of the quest's org (filtered server-side).
 export const marketplaceViewTool: ToolDefinition = defineTool('marketplace_view',
   { limit: 'number', since: 'string' },
   async (args, ctx) => {
@@ -19,7 +21,7 @@ export const marketplaceViewTool: ToolDefinition = defineTool('marketplace_view'
     const quests = await pullFromLedger(options, { operatorKey, agentId });
     return { quests, count: quests.length };
   },
-  { description: 'Browse open quests on the marketplace — work that buyers have broadcast to any willing agent. Use to find available jobs. To claim a quest, use agreement_respond on the returned agreementId. To publish your own quest, use agreement_propose({ proposedTo: "everyone" }).' },
+  { description: 'Browse open quests on the marketplace — work buyers have broadcast to willing agents. Returns public quests plus any org-scoped quests in your org. To claim a quest, use agreement_respond on the returned agreementId. To publish your own, use agreement_propose({ proposedTo: "everyone" }) for a public quest or proposedTo: "org" to keep it inside your org.' },
 );
 
 export const MARKETPLACE_TOOLS: ToolDefinition[] = [marketplaceViewTool];

package/src/tools/index.ts

@@ -1,5 +1,7 @@
 export { ToolManager } from './ToolManager.js';
 export { ToolProvider } from './ToolProvider.js';
 export { defineTool } from './defineTool.js';
+export { recordReport } from './recordReport.js';
+export type { RecordReportInput, RecordReportResult, TaskReport } from './recordReport.js';
 // Pure protocol-tool name registry (no handlers, no services).
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from '../tasks/protocolRegistry.js';

package/src/tools/recordReport.ts

@@ -0,0 +1,82 @@
+import {
+  ArtifactsClient,
+  updateTaskState,
+  type Creds,
+} from '@ziggs-ai/api-client';
+
+/**
+ * The canonical report shape (B1 convention — ZIG-561).
+ * Matches Task.result as set by ziggs_set_task_result.
+ */
+export interface TaskReport {
+  summary: string;
+  status?: string;
+  links?: string[];
+}
+
+export interface RecordReportInput {
+  creds: Creds;
+  taskId: string;
+  report: TaskReport;
+  /**
+   * Primary artifact scope — required when `deliverable` is provided.
+   * Pass exactly one of chatId or agreementId.
+   */
+  chatId?: string;
+  agreementId?: string;
+  /**
+   * Heavy deliverable text (document, diff, data).
+   * When present, writes a `content_type=result` artifact bound to the task
+   * alongside setting Task.result.
+   */
+  deliverable?: string;
+}
+
+export interface RecordReportResult {
+  taskId: string;
+  artifactId?: string;
+}
+
+/**
+ * Record a conformant report for a completed task (B2 — ZIG-562).
+ *
+ * Always sets Task.result via updateTaskState (the canonical done payload).
+ * When `deliverable` is provided, also writes a task-bound result artifact
+ * via ArtifactsClient so it is retrievable as `via=task:<taskId>`.
+ *
+ * Implements the B1 convention (Agents/REPORTING.md).
+ */
+export async function recordReport(
+  input: RecordReportInput,
+): Promise<RecordReportResult> {
+  const { creds, taskId, report, chatId, agreementId, deliverable } = input;
+
+  if (deliverable && !chatId && !agreementId) {
+    throw new Error(
+      'recordReport: chatId or agreementId is required when deliverable is provided',
+    );
+  }
+
+  await updateTaskState(
+    taskId,
+    'completed',
+    { result: { summary: report.summary, status: report.status ?? 'ok', links: report.links ?? [] } },
+    creds,
+  );
+
+  if (!deliverable) {
+    return { taskId };
+  }
+
+  const artifactsClient = new ArtifactsClient(creds.operatorKey, creds.agentId);
+  await artifactsClient.write({
+    text: deliverable,
+    content_type: 'result',
+    taskId,
+    chatId,
+    agreementId,
+    visibility: 'chat',
+  });
+
+  return { taskId };
+}