{"_id":"@parcha/agentrun","_rev":"4-4bb0f822db459cae4fe3ef3e29150948","name":"@parcha/agentrun","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"@parcha/agentrun","version":"0.1.0","_id":"@parcha/agentrun@0.1.0","maintainers":[{"name":"aj-parcha","email":"Aj@grep.ai"},{"name":"miguel-parcha","email":"miguel@parcha.ai"}],"homepage":"https://agentrun.ai","dist":{"shasum":"c2800b728229ebae622503b77b1e10af8211d9b3","tarball":"https://registry.npmjs.org/@parcha/agentrun/-/agentrun-0.1.0.tgz","fileCount":4,"integrity":"sha512-s6Byd+06e7xtpMEXkqrt5MnirnLN9NjgEVZ0Wci3MJQ9SWhu3XaOudhcPo+/KOrKh+NNsDtylRBBhKaNtXuuRQ==","signatures":[{"sig":"MEUCIQCxGuZ9GNftNr52wCMLFJevEKjb/g219tilZ/Tc9W3PhQIgNSWGFNxK1uN4gexo3UNU5bZwtnk+NainQ0JGdRutqoo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49829},"type":"module","_from":"file:public/sdk/parcha-agentrun-0.1.0.tgz","engines":{"node":">=20.9.0"},"exports":{".":{"types":"./dist/agent.d.ts","import":"./dist/agent.js"}},"_npmUser":{"name":"aj-parcha","email":"Aj@grep.ai"},"_resolved":"/home/ubuntu/worktrees/pool/octopussy/parcha/agentrun/public/sdk/parcha-agentrun-0.1.0.tgz","_integrity":"sha512-s6Byd+06e7xtpMEXkqrt5MnirnLN9NjgEVZ0Wci3MJQ9SWhu3XaOudhcPo+/KOrKh+NNsDtylRBBhKaNtXuuRQ==","deprecated":"0.1.0 targets a retired API host and cannot reach the service. Upgrade to 0.2.0 or later.","_npmVersion":"10.8.2","description":"Headless agentrun client: define an agent and call agent.run()","directories":{},"_nodeVersion":"20.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agentrun_0.1.0_1789970567174_0.2954619136795398","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@parcha/agentrun","version":"0.2.0","keywords":["agentrun","grep","agents","sdk"],"_id":"@parcha/agentrun@0.2.0","maintainers":[{"name":"aj-parcha","email":"Aj@grep.ai"},{"name":"miguel-parcha","email":"miguel@parcha.ai"}],"homepage":"https://agentrun.ai","bugs":{"url":"https://github.com/Parcha-ai/agentrun-js/issues"},"dist":{"shasum":"75cf5309348b6d29465feee2dc4a38273e502a92","tarball":"https://registry.npmjs.org/@parcha/agentrun/-/agentrun-0.2.0.tgz","fileCount":9,"integrity":"sha512-aJmxqyjIJxRasdA4x/30wdxO/EPSXaPmuLHVqoh9mGKAF7K15CeAnpd5pxVX+aMrKf8VWfnMaguqICR1jY6XfA==","signatures":[{"sig":"MEUCIQDnl9o73GYaRbBn12FLC4Qq1aLw0zFJFbY430FtYXNZcgIgUs2gPWgDOXAvh3EwKxuHJDzKSTQ4xbOyrWC5nw9Rvuw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIFO01Gd1c/u5XZ74ziZUXAc0dBDBlrCKQBGaN92PJIA1AiEAmI3z4S95Qf9hUaENJwHFpSnTzeJEgMyd/8mKSVrEG8o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":385333},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.9.0"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"2422725b8810ec4306f083424380e2165dfca7d8","scripts":{"lint":"tsc -p tsconfig.json --noEmit","test":"tsx --test tests/*.test.ts","build":"tsup","check":"npm run typecheck && npm test && npm run build && npm pack --dry-run","prepack":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"miguel-parcha","email":"miguel@parcha.ai"},"repository":{"url":"git+https://github.com/Parcha-ai/agentrun-js.git","type":"git"},"_npmVersion":"10.9.8","description":"TypeScript SDK for AgentRun: create agents, run them, and collect results","directories":{},"sideEffects":false,"_nodeVersion":"22.23.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ajv":"^8.17.0","tsx":"^4.20.0","tsup":"^8.5.1","typescript":"^5.9.0","@types/node":"^22.0.0","ajv-formats":"^3.0.1"},"_npmOperationalInternal":{"tmp":"tmp/agentrun_0.2.0_1790777632017_0.6700928844389125","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"_id":"@parcha/agentrun@0.2.1","bugs":{"url":"https://github.com/Parcha-ai/agentrun-js/issues"},"dist":{"shasum":"b2bbe027335e01d3234b46d171b7c5599a6aec46","tarball":"https://registry.npmjs.org/@parcha/agentrun/-/agentrun-0.2.1.tgz","fileCount":9,"integrity":"sha512-4k09UQPQSBp0Zw3Dtcqj4+DWK/0j3M/Cu+2fMcqk/JKb7wuyFfCYeA9q/3E8i/+bfspXzCCCJIXn45VekY4OZA==","signatures":[{"sig":"MEQCICjmKsE8RBByT8SwFs+IpRyEnvIzRVyQK5VQYCZKYIVGAiBVSPLY6JQNUnjaLX9Kc/MY0qfSU/ZordJwjfpL/9zOXw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFshVcKLZ6rOeDGod/Rso+gSJZQGSCberLojuCK6VgJQAiEArvgsDUYgFK4uN4w21BY9beB8DlHMxpV8y/tELePxCis="}],"unpackedSize":392247},"main":"./dist/index.cjs","name":"@parcha/agentrun","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.9.0"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"fdf4b8acb37261293de7228d8f13e152cf9f4405","scripts":{"lint":"tsc -p tsconfig.json --noEmit","test":"tsx --test tests/*.test.ts","build":"tsup","check":"npm run typecheck && npm test && npm run build && npm pack --dry-run","prepack":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit"},"version":"0.2.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"32da6cac-116d-4da4-b7cd-430deae7ffaa"}},"homepage":"https://agentrun.ai","keywords":["agentrun","grep","agents","sdk"],"repository":{"url":"git+https://github.com/Parcha-ai/agentrun-js.git","type":"git"},"_npmVersion":"12.1.0","description":"TypeScript SDK for AgentRun: create agents, run them, and collect results","directories":{},"maintainers":[{"name":"aj-parcha","email":"Aj@grep.ai"},{"name":"miguel-parcha","email":"miguel@parcha.ai"}],"sideEffects":false,"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ajv":"^8.17.0","tsx":"^4.20.0","tsup":"^8.5.1","typescript":"^5.9.0","@types/node":"^22.0.0","ajv-formats":"^3.0.1"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentrun_0.2.1_1790781544317_0.9238713141066808"}}},"time":{"created":"2026-09-21T06:02:47.019Z","modified":"2026-09-30T15:19:04.720Z","0.1.0":"2026-09-21T06:02:47.304Z","0.2.0":"2026-09-30T14:13:52.100Z","0.2.1":"2026-09-30T15:19:04.437Z"},"bugs":{"url":"https://github.com/Parcha-ai/agentrun-js/issues"},"homepage":"https://agentrun.ai","keywords":["agentrun","grep","agents","sdk"],"repository":{"url":"git+https://github.com/Parcha-ai/agentrun-js.git","type":"git"},"description":"TypeScript SDK for AgentRun: create agents, run them, and collect results","maintainers":[{"name":"aj-parcha","email":"Aj@grep.ai"},{"name":"miguel-parcha","email":"miguel@parcha.ai"}],"readme":"# AgentRun TypeScript SDK\n\nCreate agents, run them on your inputs, and collect the results. Typed, promise-based, no runtime dependencies. Node 20.9 or newer, or any runtime with `fetch`.\n\n```sh\nnpm install @parcha/agentrun\n```\n\n## Quick start\n\nSet `AGENTRUN_API_KEY` in your environment, then:\n\n```ts\nimport { Agent } from \"@parcha/agentrun\";\n\nconst agent = new Agent({\n  name: \"Company verifier\",\n  instructions: \"Verify the company and cite primary sources.\",\n});\nconst run = await agent.run(\"Verify acme.example\");\nconst result = await agent.wait(run.id);\n\nconsole.log(result.status);           // \"completed\", \"failed\", \"cancelled\", or \"blocked\"\nconsole.log(result.report?.markdown); // the report, or undefined\n```\n\n`Agent` saves itself on the first call that needs it. Save `agent.id` and pass `new Agent({ id })` next time to reuse it. Two things to know about `wait`. It returns for every terminal status, so check `result.status` before using the report. It gives up after 10 minutes by default and throws `PollTimeoutError`, but the run keeps going on the server. Call `agent.getRun(run.id)` later to fetch it.\n\nOutside Node, or to avoid environment variables, pass `apiKey` to the constructor.\n\n## Build an agent from a description\n\n```ts\nconst agent = await Agent.create(\"Research companies and cite sources.\");\n// Save agent.buildId if this process might stop.\nawait agent.waitUntilReady(); // builds can take a few minutes\nconst run = await agent.run(\"Research acme.example\");\n```\n\nResume an unfinished build with `new Agent({ buildId })`. Any run method waits for the build first. A build that fails throws `BuildError`; read `error.build.error` for the reason.\n\n## Structured output\n\nPass a JSON schema, or any object with a `toJSONSchema()` method, as `outputSchema`. The result's `structured_output` is the parsed object.\n\n```ts\nconst run = await agent.run(\"Verify acme.example\", {\n  outputSchema: { type: \"object\", properties: { verified: { type: \"boolean\" } } },\n});\nconst { structured_output } = await agent.wait(run.id);\n```\n\n## Batches\n\nRun up to 100 inputs at once. The SDK checks the limits before sending anything.\n\n```ts\nconst batch = await agent.batch([\"Verify acme.example\", \"Verify beta.example\"], {\n  name: \"Q3 checks\",\n  maxConcurrent: 5,\n  idempotencyKey: \"q3-checks-001\",\n});\nconst done = await agent.waitBatch(batch.id);\nfor (const row of (await agent.getBatchResults(batch.id)).results) {\n  console.log(row.row_number, row.status, row.run_id, row.headline);\n}\n```\n\nResult rows carry each run's outcome: `headline`, `excerpt`, `report_link`, and `structured_output`. The inputs are on the batch itself: `(await agent.getBatch(batch.id)).rows` gives each row's `question` and `row_data`.\n\nA CSV works too. Name the column that holds each input. The other columns come back as `row_data` on `getBatch(id).rows`.\n\n```ts\nconst batch = await agent.batch({ csv: csvText, inputColumn: \"website\" });\nfor (const row of (await agent.getBatch(batch.id)).rows) {\n  console.log(row.question, row.row_data);\n}\n```\n\n`csv` may be a string or a `Blob`, up to 1 MB. `waitBatch` returns when the batch completes, fails, is cancelled, or pauses for attention; check `batch.paused_reason`. `cancelBatch` stops new rows; rows already running finish. `retryBatch` re-runs failed rows and spends credits. `getBatch(id, { includeRows: false })` skips per-row data on large batches.\n\n## Loops\n\nA loop is a batch that repeats on a schedule. The first run starts immediately.\n\n```ts\nconst loop = await agent.loop(\n  \"Check acme.example for new filings\",\n  { frequency: \"weekly\", schedule_config: { hour: 9, minute: 0, day_of_week: 0 }, timezone: \"America/New_York\" },\n  { name: \"Weekly filings\", maxCredits: 20 },\n);\nconst history = await agent.getLoop(loop.id);\nawait agent.pauseLoop(loop.id);\nawait agent.deleteLoop(loop.id, { cancelActive: true });\n```\n\n`frequency` is `daily`, `weekly`, or `monthly`. Weekly uses `day_of_week` with 0 as Monday. Monthly uses `day_of_month` from 1 to 28. `maxCredits` caps each occurrence, not the lifetime total. Inputs are frozen at creation; `updateLoop` changes only the name and cadence.\n\n## Campaigns\n\nA campaign is a multi-stage plan. Save it as a draft, review it, then approve it with the digest of the plan you reviewed.\n\n```ts\nconst draft = await agent.createCampaign(plan);\n// read draft.stages and draft.deliverables\nconst started = await agent.approveCampaign(draft.id, draft.review_digest!);\nconst final = await agent.waitCampaign(started.id);\nconst artifact = await agent.downloadCampaignArtifact(final.id, \"companies\");\nawait writeFile(artifact.filename ?? \"companies.xlsx\", await artifact.bytes());\n```\n\n`downloadCampaignArtifact` returns a `Blob` with an extra `filename`, so `arrayBuffer()`, `bytes()`, `text()`, and `type` all work. An agent configured with `run_mode: \"campaign\"` and a `campaign_plan` can start its template directly with `agent.campaign({ goal: \"...\" })`. That call starts work immediately. Approving with a stale digest throws `ConflictError`.\n\n## Skills and integrations\n\n```ts\nimport { AgentRun } from \"@parcha/agentrun\";\n\nconst client = new AgentRun();\nconst skills = await client.listSkills({ query: \"company\" });\nconst tools = await client.listIntegrations({ query: \"company\" });\n\nconst agent = new Agent({\n  name: \"Company verifier\",\n  instructions: \"Verify the company and cite evidence.\",\n  skills: skills.skills.map((s) => s.name),\n  tools: tools.tools.filter((t) => !t.always_on).map((t) => t.name),\n});\n```\n\nSave your own Markdown as a skill with `client.createSkill({ name, description, content })`. Creating a skill with an existing name updates it; the response has `created: false`.\n\n## Statuses\n\nThe API reports progress in its own vocabulary. The SDK maps it to a short list so your code stays simple. The original value is always in `raw_status`.\n\n| `run.status` | Means | Done |\n| --- | --- | --- |\n| `queued` | Accepted, not started. | no |\n| `moderation` | Content check in progress. | no |\n| `running` | Working. | no |\n| `blocked` | Needs your input, or content was rejected. | yes |\n| `completed` | Report is ready. | yes |\n| `failed` | Ran and failed, or never ran. | yes |\n| `cancelled` | Cancelled, deleted, or superseded. | yes |\n\nBatches use `queued`, `running`, `completed`, `completed_with_errors`, `failed`, and `cancelled`. Batch rows use `queued`, `running`, `completed`, and `failed`. A status the SDK does not recognise passes through unchanged.\n\n## Errors\n\nEvery method returns a promise, and every failure is a rejection with an error that extends `AgentRunError`.\n\n| Error | When |\n| --- | --- |\n| `AuthenticationError` | 401. Bad or missing API key. |\n| `PermissionDeniedError` | 403. The key lacks a scope or does not own the resource. |\n| `NotFoundError` | 404. |\n| `ConflictError` | 409. Stale review digest, or a loop already running. |\n| `UnprocessableEntityError` | 422. `error.body.detail` lists the bad fields. |\n| `RateLimitError` | 429. |\n| `ServiceUnavailableError` | 503. Down, or the feature is not enabled for your account. |\n| `APIConnectionError` | No HTTP response at all. `APITimeoutError` for a slow one. |\n| `InvalidResponseError` | 2xx but not the JSON the SDK expects. Usually a wrong `baseURL`. |\n| `BuildError` | An agent build failed. |\n| `PollTimeoutError` | A `wait*` call hit its local deadline. |\n\n`APIError` subclasses carry `statusCode`, `body`, and `requestId`. Include the request ID when you report a problem. The SDK checks the limits the API enforces before sending anything, such as skill content of at least 50 characters or `maxCostUsd` between 0.5 and 1000, and rejects with a plain `Error`. The SDK never retries a request on its own. Pass the same `idempotencyKey` to `run`, `batch`, `loop`, or `createCampaign` when you retry, so the server does not start the work twice.\n\nEvery method accepts `{ signal }` to cancel a request or a wait from your side. Aborting stops local waiting only; it never cancels remote work. Use `cancelRun`, `cancelBatch`, or `cancelCampaign` for that.\n\n## Configuration\n\n| Setting | Option | Environment variable | Default |\n| --- | --- | --- | --- |\n| API key | `apiKey` | `AGENTRUN_API_KEY` | required |\n| API root | `baseURL` | `AGENTRUN_BASE_URL` | `https://api.grep.ai/api/v2` |\n| Per-request timeout | `timeoutMs` | | 30000 |\n| Fetch implementation | `fetch` | | `globalThis.fetch` |\n\n`baseURL` must use HTTPS. Plain HTTP is allowed only for localhost. Redirects are never followed. Environment variables are read only where `process.env` exists.\n\n## Types\n\nThe package ships ESM and CommonJS builds with declarations. Responses are plain objects typed as interfaces, so `run.status` and `batch.rows` have the types your editor shows. Records keep any field the server adds later, reachable as a property. `id` is always the record's ID, whatever the API calls it. Agent records from `getAgent` and `listAgents` expose `instructions`, `skills`, and `tools`, the names `new Agent()` takes; the API's `system_prompt`, `skill_names`, and `mcp_tool_names` hold the same values.\n\n## Development\n\n```sh\nnpm ci\nnpm run typecheck\nnpm run build\nnpm test\nnpm pack --dry-run\n```\n\nTests run against a fake API behind a `fetch` function. Two tests tie the SDK to the backend:\n\n- `tests/contract.test.ts` validates every request the SDK sends, and every canned response, against `tests/fixtures/public-v2.json`, the backend's generated OpenAPI document. Refresh it with `python scripts/update_contract.py <path-or-url>` when the API changes.\n- `tests/packaged.test.ts` starts a real local HTTP server and runs the same script the backend uses to verify packaged SDKs, against the built `dist/`.\n","readmeFilename":"README.md"}