@clawnify/agents

Server-side client for Clawnify's agent API. The app owns its business data and run results; the selected agent owns execution and its native scheduler.

import { createAgents } from "@clawnify/agents";

const agents = createAgents(env);
const { servers, page } = await agents.list({ limit: 25 });
// Populate a dropdown from servers; follow page.has_more for further pages.

await agents.dispatch({
  server_id: selectedServerId,
  instruction: "Read the saved search from the app, find matching prospects, and save evidence. Do not send outreach.",
  payload: { search_id: savedSearch.id },
  idempotency_key: savedRun.id,
});

// Call only after the user enables recurring work. Persist the creation key
// BEFORE sending, and persist the returned server/schedule IDs in the app.
const { schedule } = await agents.schedules.create(selectedServerId, {
  name: "Daily prospect signals",
  trigger: { kind: "cron", expr: "0 9 * * 1-5", tz: "Europe/Amsterdam" },
  text: "Read the saved search from the app, collect evidence, and save results. Do not send outreach.",
}, { idempotencyKey: savedSearch.scheduleCreationKey });

await agents.schedules.pause(selectedServerId, schedule.id);
await agents.schedules.resume(selectedServerId, schedule.id);
await agents.schedules.update(selectedServerId, schedule.id, { name: "Renamed scan" });
await agents.schedules.run(selectedServerId, schedule.id, { idempotencyKey: savedRun.id });
const { runs } = await agents.schedules.runs(selectedServerId, schedule.id);
await agents.schedules.delete(selectedServerId, schedule.id);

Configuration and authority

CLAWNIFY_TOKEN is required. Clawnify injects it into deployed apps. Never expose it in browser code. An OAuth bearer also works, with optional CLAWNIFY_ORG_ID to select the active organization. CLAWNIFY_API_URL overrides the HTTPS origin, not a route; localhost HTTP is supported for development.

The existing service token is organization-scoped and shared by its apps. This package does not provide app-to-app credential isolation. Schedule operations only expose schedules created through this API, not manually created native schedules. The existing agent Schedule page remains available for native administration.

Agent selection means a server's main agent; sub-agent selection is not supported. Agent secrets, browser sessions, and native WebSocket details stay behind the platform API.

Schedules and retries

• Triggers: five-field cron, intervals in whole minutes (every_ms), or a future ISO timestamp with timezone (at). Hermes only supports its server's configured timezone; unsupported combinations return an error.
• App-created schedules use isolated sessions and silent notification delivery. Silent is not a tool restriction: the app's instruction/skill must define allowed actions, access rules, evidence handling, and work limits.
• Native schedules need an updated hook advertising schedules.receipts. Older hooks return agent_schedule_upgrade_required before dispatch. This package does not upgrade an agent or install app skills automatically.
• Create and run require a persisted idempotencyKey, scoped to organization, server, and operation. Reusing a key with different input returns a conflict. Completed calls replay their original response, not current schedule state. Use schedules.get() to refresh current state.
• No automatic retries. Catch ClawnifyAgentsError and inspect code, status, outcomeUnknown, and optional retryAfterSeconds.
• If outcomeUnknown is true, reuse the same key to check for a recorded completion. Never generate a replacement key automatically: native create is not idempotent, and the agent may already have accepted the work. If the outcome stays unknown, inspect the native Schedule page before recovery. Pending receipts do not expire or redispatch themselves.
• One-off dispatch() uses the existing 24-hour dedupe window, not the stronger schedule receipt mechanism. Concurrent identical dispatches may both run.

List methods return { page: { limit, offset, has_more } }, defaulting to 25 items, with a maximum of 100. Schedule listing reflects native state; the receipt store records identity and request outcomes, not another clock.

Apps must provide their own consent, saved-search instructions, result storage, and lifecycle handling (including disabling/removing schedules before switching agents or uninstalling). Manifest-declared schedules and skill synchronization are not implemented by this client.