Documentation

npm install oncell

import { Agent, tools } from "oncell";

const agent = new Agent("support", {
  instructions: `
    You are a support agent for Acme Corp.
    Search the knowledge base before answering.
  `,
  tools: {
    searchDocs: {
      description: "Search the knowledge base",
      params: z.object({ query: z.string() }),
      run: async ({ query }) => agent.files.search(query),
    },
  },
});

agent.chat(async ({ message }) => {
  return agent.llm(message, { autoContext: true });
});

export default agent;

import { OnCell } from "@oncell/sdk";
const oncell = new OnCell({ apiKey: "oncell_sk_..." });

// Deploy
await oncell.deploy("./agent.ts");

// Call
const reply = await oncell.agent("support").run("chat", {
  message: "How do I reset my password?"
});

// Or stream
for await (const event of oncell.agent("support").stream("chat", {
  message: "How do I reset my password?"
})) {
  console.log(event.type, event.data);
}

// Per-agent memory
await agent.memory.set("config", { theme: "dark" });
const config = await agent.memory.get("config");

// Per-user (inside chat handlers, auto-scoped)
const prefs = await agent.memory.get("prefs");   // this user's prefs

// Per-user (outside chat handlers, explicit)
await agent.memory.forUser("user_123").set("prefs", { lang: "ts" });

// Durable files: upload KB docs, search them in any run
await agent.files.write("kb/faq.md", content);
const docs = await agent.files.search("password reset");

// Workspace: ephemeral, per-run (coding agents clone here)
// agent.shell() runs in workspace by default
await agent.shell("git", ["clone", repoUrl, "."]);
// Two concurrent runs = two workspaces, no collision

// Tagged templates only — injection impossible
await agent.db.sql"color:#5cdb7f">`INSERT INTO tickets(title, priority) VALUES(${title}, ${priority})`;
const rows = await agent.db.sql"color:#5cdb7f">`SELECT * FROM tickets WHERE status = ${"open"}`;

const token = agent.secrets.GITHUB_TOKEN;  // typed, traced-as-redacted
// Never serialized into snapshots. On restore, re-injected by the host.
// Set via dashboard or: oncell secrets set GITHUB_TOKEN=ghp_... --env prod

const answer = await agent.llm("Summarize this ticket");
console.log("color:#5cdb7f">`${answer}`);  // toString() returns .text

const result = await agent.llm("Fix the failing tests", {
  tools: [tools.workspace, tools.shell],
  maxSteps: 50,
  maxCost: 5.00,   // halt if cumulative cost exceeds $5
});

// result.status: "completed" | "max_steps" | "max_cost" | "timeout"
// result.text: final output
// result.steps: number of tool iterations
// result.cost: dollars spent (includes spawned children)
// result.resumeToken: present if halted — continue from here

interface Result<T = unknown> {
  text: string;
  status: "completed" | "max_steps" | "max_cost" | "max_tokens" | "timeout";
  steps: number;
  cost: number;
  usage: { inputTokens: number; outputTokens: number };
  resumeToken?: string;
  data?: T;            // typed when output schema provided
  toString(): string;  // returns .text
}

if (result.status === "max_cost") {
  const ok = await agent.askHuman({
    question: "color:#5cdb7f">`Spent $${result.cost}. Approve $5 more?`,
  });
  if (ok.approved) {
    const continued = await agent.llm.resume(result.resumeToken, { maxCost: 5.00 });
    // resumes from exact checkpoint — no step re-executes or re-bills
  }
}

const result = await agent.llm("Extract invoice details", {
  output: z.object({
    invoiceNumber: z.string(),
    amount: z.number(),
    dueDate: z.string(),
  }),
});
result.data.amount;  // number — typed, validated

const turn = await agent.llm.step(messages, {
  tools: myTools,
  system: "Custom system prompt for this turn",
});
// turn.message, turn.toolCalls — your dispatch, your policies

import { Agent, tools } from "oncell";

const agent = new Agent("coder", {
  instructions: "You are a coding agent.",
  tools: [tools.workspace, tools.shell, tools.git],
});

tools: [
  tools.workspace.pick("read", "search"),  // read-only
  tools.shell,
  { deploy: { description: "...", params: z.object({...}), confirm: true, run: ... } },
]

agent.task("fix", async ({ repo, issue }: { repo: string; issue: string }) => {
  await agent.emit("Cloning repository…");
  await agent.shell("git", ["clone", "color:#5cdb7f">`https://github.com/${repo}.git`, "."]);
  return agent.llm(issue, { tools: [tools.workspace, tools.shell], maxCost: 5.00 });
});

agent.chat(async ({ message, files }) => {
  return agent.llm(message, { autoContext: true });
});

agent.schedule("followup", "every monday 9am", async () => {
  const open = await agent.db.sql"color:#5cdb7f">`SELECT * FROM tickets WHERE status = ${"open"} LIMIT ${20}`;
  for (const ticket of open) {
    const update = await agent.llm("color:#5cdb7f">`Status update for "${ticket.title}"`, { maxSteps: 3 });
    await agent.db.sql"color:#5cdb7f">`UPDATE tickets SET last_update = ${update.text} WHERE id = ${ticket.id}`;
  }
}, { maxCost: 20.00 });  // always budget schedules

agent.onWebhook("/github", async ({ payload }) => {
  if (payload.action === "opened") {
    return agent.llm("color:#5cdb7f">`Review this PR: ${payload.pull_request.url}`, {
      tools: [tools.web],
    });
  }
});

agent.chat(async ({ message }) => {
  const prefs = await agent.memory.get("prefs");            // this user
  const config = await agent.global.memory.get("config");   // cross-user, explicit
  return agent.llm(message, { autoContext: true });
});

agent.task("admin", async ({ userId }) => {
  // task = API endpoint, nothing auto-scoped
  const prefs = await agent.memory.forUser(userId).get("prefs");
});

agent.task("process-refund", async ({ orderId, amount }) => {
  const order = await agent.db.sql"color:#5cdb7f">`SELECT * FROM orders WHERE id = ${orderId}`;

  // Agent parks here — can wait days. Process can crash, redeploy, move.
  const ok = await agent.askHuman({
    question: "color:#5cdb7f">`Refund $${amount} for order ${orderId}?`,
  });

  if (ok.approved) {
    await agent.llm("Process the refund and notify the customer");
  }

  // Sleep 30 days, then follow up
  await agent.sleep({ days: 30 });
  await agent.llm("Check if the customer is satisfied");
});

createTicket: {
  description: "Create a support ticket",
  params: z.object({ title: z.string(), priority: z.enum(["low", "high"]) }),
  confirm: { channel: "dashboard" },  // staff approves, not the customer
  run: async ({ title, priority }) => {
    await agent.db.sql"color:#5cdb7f">`INSERT INTO tickets(title, priority) VALUES(${title}, ${priority})`;
    return "created";
  },
}
// On rejection: LLM receives { denied: true, reason } — adapts, doesn't crash

import { Agent, tools } from "oncell";

const agent = new Agent("coder", {
  instructions: "You are a coding agent. Read code, make changes, run tests, iterate.",
  skills: {
    debugging: { when: "Tests fail", guide: "Read error. Find file. Root cause. Fix. Re-test." },
  },
  tools: [tools.workspace, tools.shell, tools.git],
});

agent.task("fix", async ({ repo, issue }: { repo: string; issue: string }) => {
  await agent.emit("Cloning…");
  await agent.shell("git", ["clone", "color:#5cdb7f">`https://github.com/${repo}.git`, "."]);
  return agent.llm(issue, { maxSteps: 50, maxCost: 5.00 });
});

export default agent;

// researcher.ts
import { Agent, tools } from "oncell";

export const researcher = new Agent("researcher", {
  instructions: "Research a topic thoroughly using web search.",
  tools: [tools.web],
});

researcher.task("research", async ({ topic }: { topic: string }) => {
  return researcher.llm(topic, { maxSteps: 30, maxCost: 2.00 });
});

// planner.ts
import { Agent } from "oncell";
import { z } from "zod";
import { researcher } from "./researcher";

const planner = new Agent("planner", {
  instructions: "Break questions into sub-questions. Delegate. Synthesize.",
  tools: {
    delegate: {
      description: "Send a sub-question to a researcher",
      params: z.object({ topic: z.string() }),
      run: async ({ topic }) => planner.spawn(researcher, "research", { topic }),
    },
  },
});

planner.task("deep-research", async ({ question }: { question: string }) => {
  return planner.llm(question, { maxCost: 10.00 });
  // Parallel delegate calls run concurrently. Child spend cascades against $10.
});

export default planner;
// oncell deploy ./planner.ts deploys both (entry-graph rule)

import { OnCell } from "@oncell/sdk";
const oncell = new OnCell({ apiKey: process.env.ONCELL_API_KEY });

const coder = oncell.agent("coder");

// Run a task
const result = await coder.run("fix", { repo: "acme/api", issue: "Tests failing" });

// Stream a task
for await (const event of coder.stream("fix", { repo, issue })) {
  // event.type: "emit" | "text" | "tool_call" | "tool_result" | "parked" | "done"
}

// Chat (conversation object owns continuity)
const convo = oncell.agent("support").chat({ user: "user_123" });
const reply = await convo.send("My invoice is wrong");
const reply2 = await convo.send("Yes, the March one", { files: [screenshot] });

// Chat streaming
for await (const event of convo.stream("Check my March invoice?")) {
  // same event types as task streaming
}

// Resume a halted run
await coder.resume(result.resumeToken, { maxCost: 5.00 });

// Push files to agent's durable knowledge base
await oncell.agent("support").files.push("./kb/");

// Manage
await oncell.agents.list();