swarmlord 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Grimaldi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# swarmlord
+
+TypeScript SDK for [Swarmlord](https://swarmlord.ai) — spawn AI coding agents natively on Cloudflare.
+
+## Install
+
+```bash
+npm install swarmlord
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from "swarmlord";
+
+const client = createClient({
+    apiKey: "your-api-key",
+    baseUrl: "https://your-worker.your-account.workers.dev",
+});
+```
+
+## Core Concepts
+
+Everything flows from **Agents**. An agent is a configured template — model, tools, instructions, permissions. From an agent you create **Sessions** (interactive), **Tasks** (one-shot), or **Schedules** (recurring).
+
+```
+Agent
+ ├── Session   (interactive, multi-turn, streaming)
+ ├── Task      (fire-and-forget, await result)
+ └── Schedule  (cron-triggered, manageable)
+```
+
+## Agents
+
+```typescript
+// Use a built-in agent type
+const build = client.agent("build");
+
+// Or configure a custom agent
+const reviewer = client.agent({
+    name: "build",
+    model: "anthropic/claude-sonnet-4-20250514",
+    instructions: ["Focus on security and correctness"],
+    config: { permission: "allow" },
+});
+```
+
+## Sessions — Interactive Conversations
+
+Sessions are stateful, multi-turn conversations with an agent. They support streaming, tool calls, and permission gates.
+
+```typescript
+const session = await build.createSession({ title: "Build Todo App" });
+
+// Stream a message with callbacks
+const result = await session.send("Create a REST API with Hono", {
+    onText: delta => process.stdout.write(delta),
+    onToolStart: part => console.log(`[tool] ${part["tool"]}`),
+    onToolComplete: part => console.log(`[done] ${part["tool"]}`),
+    onPermission: async req => "once",
+    onError: err => console.error(err),
+});
+
+console.log(result.text); // full response text
+console.log(result.parts); // all tool call parts
+
+// Continue the conversation
+await session.send("Now add authentication");
+
+// Or use the async iterator for full control
+for await (const event of session.stream("Add tests")) {
+    switch (event.type) {
+        case "text-delta":
+            process.stdout.write(event.delta);
+            break;
+        case "tool-start":
+            console.log(`Running: ${event.part["tool"]}`);
+            break;
+    }
+}
+
+// Session management
+await session.summarize(); // trigger context compaction
+await session.revert(messageId); // undo to a specific message
+await session.abort(); // cancel current turn
+await session.delete(); // clean up
+
+// Direct sandbox access
+const shellResult = await session.shell("npm test");
+console.log(shellResult.stdout, shellResult.exitCode);
+```
+
+### Resume an existing session
+
+```typescript
+const session = build.session("existing-session-id");
+await session.send("Continue where we left off");
+```
+
+### Fork a session
+
+```typescript
+const fork = await build.forkSession("session-to-fork");
+await fork.send("Try a different approach");
+```
+
+## Tasks — One-Shot Jobs
+
+Tasks are fire-and-forget agent runs. Create a session, send a prompt, get back a handle. The agent runs in the background.
+
+```typescript
+// Launch a task
+const task = await build.run("Refactor the auth module to use JWT");
+
+// Check on it
+const status = await task.poll(); // "accepted" | "busy" | "idle" | "error"
+
+// Block until done
+const result = await task.result({ timeoutMs: 300_000 });
+console.log(result.text); // the agent's final output
+console.log(result.status); // "completed" | "error"
+
+// Cancel if needed
+await task.cancel();
+```
+
+### Tasks with webhooks
+
+```typescript
+const task = await build.run("Update all dependencies", {
+    webhook: "https://my-app.com/hooks/agent-done",
+});
+// Webhook receives: { sessionId, status, result, tokens, timestamp }
+```
+
+### Resume a task from another process
+
+```typescript
+// Save the task ID
+const taskId = task.id;
+
+// Later, in another process
+const resumed = client.task(taskId);
+const result = await resumed.result();
+```
+
+## Schedules — Recurring Jobs
+
+Schedules trigger agent runs on a cron. Each trigger creates a Task you can inspect.
+
+```typescript
+const schedule = await reviewer.schedule({
+    cron: "0 9 * * 1-5", // weekdays at 9am
+    prompt: "Review recent commits for security issues",
+});
+
+// Manual trigger — returns a Task handle
+const task = await schedule.trigger();
+const result = await task.result();
+
+// Management
+await schedule.pause();
+await schedule.resume();
+await schedule.update({ cron: "0 9 * * *" }); // change to daily
+await schedule.delete();
+
+// List all schedules
+const schedules = await client.listSchedules();
+```
+
+## Client-Level Operations
+
+```typescript
+// List sessions
+const sessions = await client.listSessions({ limit: 20, archived: false });
+
+// Resume any handle by ID
+const session = client.session("session-id");
+const task = client.task("task-session-id");
+const schedule = client.schedule("schedule-id");
+```
+
+## Types
+
+All types are exported for use in your own code:
+
+```typescript
+import type {
+    AgentHandle,
+    SessionHandle,
+    TaskHandle,
+    ScheduleHandle,
+    AgentEvent,
+    SendResult,
+    TaskResult,
+    StreamCallbacks,
+} from "swarmlord";
+```