@evolvingmachines/evolve 0.0.65 → 0.0.67-train-harness-wave-2026-09-25.20260926.e00a8a6d

package/skills/evolve-evals/references/sdk-reference/filesystem.md

@@ -0,0 +1,166 @@
+---
+title: "Filesystems and downloads"
+description: "Choose the right files: saved results, a sandbox, or a task package."
+---
+
+**Note:**
+
+For every method’s inputs, return values, and language differences, see the [filesystem method reference](/sdk-reference/methods/filesystem).
+
+Evolve exposes three file surfaces. They answer different questions.
+
+| Need | Client |
+| --- | --- |
+| Read a trial's saved `result.json`, logs, or collected artifact | `trials.files()` / `trials.file()` |
+| Browse sandbox paths during or after a run | `filesystem()` |
+| Inspect the task files supplied to a run | `datasets.taskFiles()` / `task_files()` |
+
+## Open a run's filesystem
+
+```ts TypeScript
+import { trials } from "@evolvingmachines/evolve";
+
+const fs = trials().filesystem(trialId);
+const status = await fs.status();
+const folder = await fs.list({ path: status.work_dir });
+console.log(status.state, folder.entries);
+```
+
+```python Python
+from evolve import trials
+
+fs = trials().filesystem(trial_id)
+status = await fs.status()
+folder = await fs.list(path=status.work_dir)
+print(status.state, folder.entries)
+```
+
+The same methods are available from:
+
+### TypeScript
+
+| Run | Client |
+| --- | --- |
+| Trial | `trials().filesystem(trialId)` |
+| Analysis | `analyses().filesystem(analysisId)` |
+| Task check | `checks().taskFilesystem(checkId, taskCheckId)` |
+
+### Python
+
+| Run | Client |
+| --- | --- |
+| Trial | `trials().filesystem(trial_id)` |
+| Analysis | `analyses().filesystem(analysis_id)` |
+| Task check | `checks().task_filesystem(check_id, task_check_id)` |
+
+### What source will answer?
+
+```text
+1. Read status
+   ├─ live      → sandbox
+   ├─ captured  → saved files
+   ├─ capturing → preparing files
+   └─ none      → unavailable
+
+2. Require a source (optional)
+   ├─ "live"    → sandbox only
+   └─ "capture" → saved files only
+```
+
+Omit `source` to prefer live files, then a capture. A missing required source raises `filesystem_state`.
+
+**Note:**
+
+A captured listing can include unchanged image files whose bytes were not saved. Check `entry.captured`; reading one with no stored bytes raises `not_captured`. A capture is not a complete disk image.
+
+## Browse, read, search
+
+```ts TypeScript
+const bytes = await fs.read("/app/report.json");
+const hits = await fs.search({ q: "error", path: "/app" });
+const changes = await fs.changes({ phase: "agent" });
+```
+
+```python Python
+content = await fs.read("/app/report.json")
+hits = await fs.search("error", path="/app")
+changes = await fs.changes(phase="agent")
+```
+
+These paths are examples. Use `status.work_dir` and a listing to find the run's actual files.
+
+| Method | Options | Result |
+| --- | --- | --- |
+| `status()` | None | State, box, work directory, watcher, capture summary |
+| `list(...)` | `path`, `source`, `cursor`, `limit` | `entries`, `next_cursor` |
+| `read(path, ...)` | `source`, byte range | `Buffer` / `bytes` |
+| `search(...)` | Query, `path`, `regex`, `limit`, `source` | Hits and `truncated` flag |
+| `changes(...)` | `source`, `phase`, `cursor`, `limit` | Changed files and next cursor |
+| `archive(...)` | `path`, `source`, download options | Archive bytes or saved path |
+
+TypeScript search takes `{q, ...}`; Python takes `q` as its first argument. Change phases are `setup`, `agent`, `verifier`, or `all`.
+
+Byte ranges: TypeScript `{range: {start, end}}` or `{range: {suffix}}`; Python `start=`, `end=`, or `suffix=`. End is inclusive. Suffix selects the last N bytes.
+
+List/change pages default to 500 rows; search defaults to 200. Their maximum is 1,000. A `truncated` search should be narrowed before treating it as complete.
+
+## Follow changes and logs
+
+```ts TypeScript
+await fs.watch(["/app"]);
+for await (const event of fs.events()) {
+  console.log(event.event, event.data);
+}
+```
+
+```python Python
+await fs.watch(["/app"])
+async for event in fs.events():
+    print(event.event, event.data)
+```
+
+`watch(paths)` registers up to eight folders. `events()` yields filesystem, state, and heartbeat frames.
+
+| Read | TypeScript | Python |
+| --- | --- | --- |
+| One log page | `logs({ stream: "agent", cursor, limit })` | `logs("agent", cursor=..., limit=...)` |
+| Log events | `logEvents(options)` | `log_events(...)` |
+| Live processes | `procs()` | `procs()` |
+
+Log streams are `agent`, `verifier`, `system`, `setup`, and `metrics`. System logs require `system_log` at job creation. A stream can be empty with a `reason`; reserved or unavailable streams do not imply missing agent work.
+
+Filesystem and log event streams connect once. To reconnect, retain the last event id and pass `lastEventId` / `last_event_id`. TypeScript also accepts `signal`. This is separate from the automatic reconnect behavior of `jobs.watch()`.
+
+## Task package files
+
+```ts TypeScript
+import { datasets } from "@evolvingmachines/evolve";
+
+const files = datasets().taskFiles("harbor-examples@1.0", "hello-world");
+const tree = await files.list();
+const instruction = await files.read("instruction.md");
+```
+
+```python Python
+from evolve import datasets
+
+files = datasets().task_files("harbor-examples@1.0", "hello-world")
+tree = await files.list()
+instruction = await files.read("instruction.md")
+```
+
+The dataset reference must pin a version. This client provides `status()`, `list()`, and `read(path)`. List options are `path`, `cursor`, and `limit`: one object in TypeScript, keyword arguments in Python. Reads accept the same byte-range options as above. There is no live source, process list, or log stream.
+
+## Download options
+
+Dataset, job, analysis, and check downloads use the same delivery choices. Run-filesystem `archive()` does too.
+
+| Choice | TypeScript | Python |
+| --- | --- | --- |
+| Bytes in memory | No options → `Buffer` | No `to` → `bytes` |
+| Save to a directory | `{ to: "./results" }` → path | `to="./results"` → path |
+| Raw response stream | `{ stream: true }` | Not exposed |
+
+`to` is a directory. The client chooses the archive filename from the response and returns the saved path.
+
+Buffer/bytes and saved-file downloads check declared length and digest when supplied. Saved files appear at their final path only after verification. TypeScript raw streams leave integrity checking to the caller.

package/skills/evolve-evals/references/sdk-reference/index.md

@@ -0,0 +1,161 @@
+---
+title: "SDK clients"
+description: "One configuration. Focused clients for jobs, datasets, trials, and results."
+---
+
+Use the same managed evaluation service from TypeScript or Python. Evolve runs the jobs; your program submits work and reads the results.
+
+**Note:**
+
+To run agents directly with the Evolve builder, Swarm, or Pipeline, use the separate [agent SDK manual](https://github.com/evolving-machines-lab/evolve/blob/main/docs-agents/index.md).
+
+```ts TypeScript
+import { hosted } from "@evolvingmachines/evolve";
+
+const evolve = hosted(); // Reads EVOLVE_API_KEY.
+const page = await evolve.jobs.list();
+```
+
+```python Python
+from evolve import hosted
+
+evolve = hosted()  # Reads EVOLVE_API_KEY.
+page = await evolve.jobs.list()
+```
+
+Python examples in this reference belong inside an async function. The [Python guide](/sdk/python) includes a complete runnable program.
+
+## Choose a client
+
+**[Jobs](/sdk-reference/jobs)**
+
+Start, follow, compare, retry, and download evaluations.
+
+**[Trials](/sdk-reference/trials)**
+
+Inspect one attempt: reward, trace, and stored files.
+
+**[Datasets](/sdk-reference/datasets)**
+
+Browse tasks, publish versions, and inspect builds.
+
+**[Filesystems](/sdk-reference/filesystem)**
+
+Read live sandbox files and saved captures.
+
+**[Analyses](/sdk-reference/analyses)**
+
+Read the analyzer's results and saved runs.
+
+**[Checks](/sdk-reference/checks)**
+
+Check task quality before running a benchmark.
+
+Also available: [agents](/sdk-reference/agents), [uploaded skills](/sdk-reference/skills), [secrets](/sdk-reference/secrets), [identity and teams](/sdk-reference/auth), and [platform capabilities](/sdk-reference/meta).
+
+## Look up a method
+
+Use the client guides above for a workflow. Open a method reference for its inputs, returned fields, and Python and TypeScript examples.
+
+| Client | Method reference |
+| --- | --- |
+| Jobs | [Start, watch, compare, retry, and import](/sdk-reference/methods/jobs) |
+| Trials | [Read attempts, traces, and artifacts](/sdk-reference/methods/trials) |
+| Filesystems | [Read files, search, and follow live changes](/sdk-reference/methods/filesystem) |
+| Analyses | [Read analysis runs and outputs](/sdk-reference/methods/analyses) |
+| Checks | [Create and inspect task quality checks](/sdk-reference/methods/checks) |
+| Datasets | [Browse, publish, and manage versions](/sdk-reference/methods/datasets) |
+| Agents | [Register and manage harnesses](/sdk-reference/methods/agents) |
+| Skills | [Upload and manage run context](/sdk-reference/methods/skills) |
+| Secrets | [Store credentials and read metadata](/sdk-reference/methods/secrets) |
+| Identity and teams | [Read identity and manage membership](/sdk-reference/methods/auth) |
+| Capabilities | [Read supported options and limits](/sdk-reference/methods/meta) |
+
+For failures, start with [error handling](/sdk-reference/errors) or find the exact name in the [error-code reference](/sdk-reference/error-codes).
+
+## Configure once
+
+```ts TypeScript
+import { hosted } from "@evolvingmachines/evolve";
+
+const evolve = hosted({
+  apiKey: process.env.EVOLVE_API_KEY,
+  org: "my-team",
+});
+```
+
+```python Python
+import os
+from evolve import HostedClientConfig, hosted
+
+evolve = hosted(HostedClientConfig(
+    api_key=os.environ["EVOLVE_API_KEY"],
+    org="my-team",
+))
+```
+
+| Setting | TypeScript | Python | Default |
+| --- | --- | --- | --- |
+| API key | `apiKey` | `api_key` | `EVOLVE_API_KEY` |
+| API origin | `baseUrl` | `base_url` | `EVOLVE_DASHBOARD_URL`, then the Evolve dashboard |
+| Owning team | `org` | `org` | Your personal organization |
+
+The `org` default applies when you create jobs, publish datasets, register agents, or upload skills. A call's own `org` wins. It does not filter list requests.
+
+Prefer a single client when useful: `jobs(config)`, `trials(config)`, and the other factories accept the same configuration. Import `auth` and `managedSecrets` / `managed_secrets` separately; they are not properties of `hosted()`.
+
+**Tip:**
+
+`meta()` needs no key. Other clients authenticate with your API key. TypeScript checks for a key when the client is created; Python checks when it makes an authenticated request.
+
+## One page or every item
+
+```ts TypeScript
+// One page.
+const page = await evolve.jobs.list({ limit: 20 });
+console.log(page.items, page.nextCursor, page.hasMore);
+
+// All pages, one job at a time.
+for await (const job of evolve.jobs.list()) {
+  console.log(job.id, job.status);
+}
+```
+
+```python Python
+# One page.
+page = await evolve.jobs.list(limit=20)
+print(page.items, page.next_cursor, page.has_more)
+
+# All pages, one job at a time.
+async for job in evolve.jobs.list():
+    print(job.id, job.status)
+```
+
+This pattern applies to list handles, including `jobs.trials()` and `jobs.tasks()`. A trace page, stored-file page, grep result, or dataset's nested task page is a single page; follow its cursor yourself or use the dedicated iterator where available.
+
+## Language differences
+
+| Detail | TypeScript | Python |
+| --- | --- | --- |
+| Calls | Input/options objects | Keyword arguments |
+| Most domain fields | `model_name`, `cost_usd` | Same spelling |
+| Returned entities | Objects | Dataclasses; stats, analyses, and checks are dictionaries |
+| Download to memory | `Buffer` | `bytes` |
+| Download to directory | `{ to: "./results" }` | `to="./results"` |
+| Raw download stream | `{ stream: true }` | Not exposed |
+| Wait cancellation | `AbortSignal` on watch methods | `timeout_s` on job/import/check watches |
+
+See [types](/sdk-reference/types) for field access and [errors](/sdk-reference/errors) for request failures.
+
+### Python client lifetime
+
+Hosted clients support `async with` and `await client.close()`:
+
+```python
+from evolve import hosted
+
+async with hosted() as client:
+    page = await client.jobs.list(limit=20)
+```
+
+The individual hosted clients currently have no resources to release in `close()`. Closing a client does not cancel an evaluation. Use `jobs().cancel(job_id)` to stop a job.

package/skills/evolve-evals/references/sdk-reference/jobs.md

@@ -0,0 +1,250 @@
+---
+title: "Jobs"
+description: "Submit evaluations, follow progress, and work with results."
+---
+
+**Note:**
+
+For every method’s inputs, return values, and language differences, see the [jobs method reference](/sdk-reference/methods/jobs).
+
+A job runs selected tasks against one or more agent/model combinations. Each combination is an **arm**. Each attempt is a **trial**.
+
+```text
+  Selected tasks
+× Agent/model arms
+× Attempts
+= Trials
+```
+
+## Start a job
+
+```ts TypeScript
+import { jobs } from "@evolvingmachines/evolve";
+
+const client = jobs();
+const job = await client.start({
+  datasets: [{
+    name: "harbor-examples",
+    version: "1.0",
+    task_names: ["hello-world"],
+  }],
+  agents: [{ name: "codex", model_name: "gpt-5.6-luna" }],
+  max_trial_spend_usd: 0.50,
+  retry: { max_retries: 0 },
+});
+```
+
+```python Python
+from evolve import jobs
+
+client = jobs()
+job = await client.start(
+    datasets=[{
+        "name": "harbor-examples",
+        "version": "1.0",
+        "task_names": ["hello-world"],
+    }],
+    agents=[{"name": "codex", "model_name": "gpt-5.6-luna"}],
+    max_trial_spend_usd=0.50,
+    retry={"max_retries": 0},
+)
+```
+
+`start` returns the accepted `Job`. Read `job.id` to address it later.
+
+### Required inputs
+
+| Input | Fields |
+| --- | --- |
+| `datasets` | One or more selectors. Required: `name`. Optional: `version`, `task_names`, `exclude_task_names`, `n_tasks`. Omitted version selects the active version. Filters accept glob patterns; the cap applies after filters. |
+| `agents` | One or more arms. Required: `name`, `model_name`. Optional: `version`, `reasoning_effort`, `kwargs`, `preset`, `skills`. Use [capabilities](/sdk-reference/meta) for supported values. |
+
+Python also accepts `DatasetSelector` and `AgentArm` dataclass instances in these lists.
+
+### Run settings
+
+| Option | Meaning | When omitted |
+| --- | --- | --- |
+| `job_name` | A label for the run | Server-generated name |
+| `org` | Owning organization slug or id | Client default, then personal organization |
+| `n_attempts` | Attempts per task/arm; integer ≥1 | `1` |
+| `n_concurrent_trials` | Requested parallel trials; `1`–`150` | `4` |
+| `sandbox_provider` | Requested `e2b`, `daytona`, or `modal` | Current platform default |
+| `max_trial_spend_usd` | Agent model-spend cap per trial attempt; must be >0 | Current platform default; fallback `$200` |
+| `retry` | Automatic infrastructure retry policy | Current platform policy; fallback two retries |
+| `analyze` | [Analyze each settled trial](/sdk-reference/analyses#start-an-analysis); `{}` enables defaults | Off |
+| `system_log` | Capture sandbox system logs | Off |
+| `secrets` | Stored secret references or inline values | No extra job secrets |
+| `verifier_env` | Judge overrides: `REWARDKIT_JUDGE`, `REWARDKIT_MODEL` only | Task/default judge settings |
+
+Organization and fleet capacity also constrain parallel work. A task may use another provider when the requested provider cannot support its requirements; read the trial for its actual provider.
+
+### Timeout multipliers
+
+All values are finite numbers greater than zero. They multiply task timeouts; they are not durations in seconds.
+
+| Field | Applies to |
+| --- | --- |
+| `timeout_multiplier` | All phases without a specific override; default `1` |
+| `agent_timeout_multiplier` | Agent execution |
+| `verifier_timeout_multiplier` | Verification |
+| `agent_setup_timeout_multiplier` | Harness installation/setup |
+| `environment_build_timeout_multiplier` | Environment build |
+
+A phase override replaces the global multiplier for that phase. Values that exceed the runtime's timer limit for the selected tasks are refused.
+
+### Automatic retry policy
+
+| Field | Rule |
+| --- | --- |
+| `max_retries` | Integer ≥0. `0` disables configured infrastructure retries. |
+| `include_exceptions` | Exception names to include. Omitted, null, or `[]` means no include filter. |
+| `exclude_exceptions` | Exclusions win over includes. Omitted keeps defaults; null or `[]` removes them. |
+| `wait_multiplier` | Backoff multiplier; default `1` |
+| `min_wait_sec` | Initial wait; default `1` second |
+| `max_wait_sec` | Maximum wait; default `60` seconds |
+
+Only eligible infrastructure failures enter this retry policy. Scoring errors and low rewards do not automatically rerun the agent. Each retry receives a fresh per-trial cap.
+
+Provider capacity refusals have a separate bounded wait policy. They can wait even when `max_retries` is zero.
+
+### Idempotency and unsupported input
+
+Supply an idempotency key when repeating a submission must return the same accepted job:
+
+Here, `config` is the job input shown above. `requestId` / `request_id` is a stable string you assign to this submission.
+
+```ts TypeScript
+const job = await client.start(config, { idempotencyKey: requestId });
+```
+
+```python Python
+job = await client.start(**config, idempotency_key=request_id)
+```
+
+Use one stable request id for the same resolved request. Reusing it for a different request is refused.
+
+`agent_env` appears in SDK signatures, but the current platform refuses nonempty values. Use [job secrets](/sdk-reference/secrets) for credentials or [registered-agent environment settings](/sdk-reference/agents) for a custom harness.
+
+## Wait or show progress
+
+```ts TypeScript
+const finished = await client.watch(job.id, {
+  onEvent: (event) => console.log(event.type),
+});
+```
+
+```python Python
+finished = await client.watch(
+    job.id,
+    on_event=lambda event: print(event.type),
+)
+```
+
+The same handle can instead be consumed with `for await` / `async for` to receive events. Choose one style per handle. Job watches replay history and reconnect from the last event id.
+
+| Watch option | TypeScript | Python |
+| --- | --- | --- |
+| Event callback | `onEvent` | `on_event` |
+| Initial reconnect delay | `reconnectDelayMs` (default `1000`) | `reconnect_delay_s` (default `1`) |
+| Maximum reconnect delay | `maxReconnectDelayMs` (default `30000`) | `max_reconnect_delay_s` (default `30`) |
+| Stop waiting | `signal` | `timeout_s` |
+
+A terminal job has finished scheduling/executing its trials. **Completed does not mean every trial passed.**
+
+## Read and compare
+
+```ts TypeScript
+const job = await client.get(jobId);
+for await (const trial of client.trials(jobId, { status: ["SCORING_ERROR"] })) {
+  console.log(trial.id, trial.exception_info);
+}
+const tasks = await client.tasks(jobId);
+const comparison = await client.compare([firstJobId, secondJobId]);
+```
+
+```python Python
+job = await client.get(job_id)
+async for trial in client.trials(job_id, status=["SCORING_ERROR"]):
+    print(trial.id, trial.exception_info)
+tasks = await client.tasks(job_id)
+comparison = await client.compare([first_job_id, second_job_id])
+```
+
+Use full ids returned by create/list calls.
+
+| Method | Options | Returns |
+| --- | --- | --- |
+| `get(id)` | None | `Job` |
+| `list(...)` | `search`, `scope`, `kind`, `limit`, `cursor` | Paginated handle |
+| `trials(id, ...)` | `status` list, `dataset`, `limit`, `cursor` | Trial handle |
+| `tasks(id, ...)` | `limit`, `cursor` | Per-task rollup handle |
+| `compare(ids)` | 2–10 distinct readable job ids | Job aggregates and task matrix |
+| `grep(id, q, ...)` | `type`, `limit`, `cursor` | One page of matches grouped by trial |
+
+List scope is `my`, `shared`, or `org`. Job list kind is `job` (default), `check`, or `all`; check rows have a different shape. Branch on `row.kind` before reading job-only fields.
+
+`grep` searches parsed traces using a case-insensitive POSIX regular expression. See [trial traces](/sdk-reference/trials#read-the-trace) for per-trial filtering.
+
+## Cancel or run selected work again
+
+| Action | TypeScript | Python | Result |
+| --- | --- | --- | --- |
+| Cancel remaining work | `cancel(id)` | `cancel(id)` | Current job |
+| Resume failed/stopped work | `resume(id, { filter_error_types })` | `resume(id, filter_error_types=[...])` | New linked job |
+| Retry selected settled trials | `retry(id, { trial_ids })` | `retry(id, trial_ids=[...])` | New linked job |
+| Retry failed trials | `retry(id, { failed_only: true })` | `retry(id, failed_only=True)` | New linked job |
+| Retry all trials of a terminal job | `retry(id)` | `retry(id)` | New linked job |
+| Re-run eligible verifiers | `regrade(id, { statuses, task_name })` | `regrade(id, statuses=[...], task_name=...)` | New linked job |
+
+Resume requires a terminal source job. Explicit retry ids may select settled trials from a job still running. Do not combine `trial_ids` with `failed_only`.
+
+Resume and retry accept the same idempotency option as start: a final options object in TypeScript, `idempotency_key` in Python. Regrade has no such SDK option.
+
+Regrading uses the recorded verifier snapshot; it cannot replace the verifier or use edited tests. It needs retained inputs from an eligible separate verifier. Shared-verifier, judge-based, multi-step, and uploaded runs cannot be regraded. See [jobs](/core-concepts/jobs) for eligibility.
+
+## Analyze traces
+
+`analyze(id, ...)` starts a wave and returns immediately. `watchAnalysis` / `watch_analysis` waits for that wave. Configuration and examples are on [analyses](/sdk-reference/analyses).
+
+For a job created with embedded analysis, wait for the job first, then its analyses. A still-running job can temporarily have zero pending analyses.
+
+## Download or import results
+
+```ts TypeScript
+const path = await client.download(jobId, { to: "./results" });
+const imported = await client.upload("./local-job");
+const settled = await client.watchImport(imported.id);
+console.log(settled.status, settled.job_id, settled.failure);
+```
+
+```python Python
+path = await client.download(job_id, to="./results")
+imported = await client.upload("./local-job")
+settled = await client.watch_import(imported.id)
+print(settled.status, settled.job_id, settled.failure)
+```
+
+Download requires a terminal job. Without `to`, it returns a `Buffer` / `bytes`; TypeScript also supports `{stream: true}`. See [transfer behavior](/sdk-reference/filesystem#download-options).
+
+| Import method | Input/options |
+| --- | --- |
+| `upload(source, ...)` | Local job directory or archive path. TypeScript also accepts `{archive_url}`; Python takes `archive_url=` instead of a path. |
+| Upload options | Optional `dataset`, upload progress callback, and import-registration callback. |
+| `getImport` / `get_import` | Import id |
+| `listImports` / `list_imports` | `status`, `limit`, `cursor` |
+| `watchImport` / `watch_import` | TS: `onStatus`, `onProgress`, `pollIntervalMs`, `signal`. Python: `on_status`, `on_progress`, `poll_interval_s`, `timeout_s`. |
+
+Callback names and timing use the same [upload/watch conventions as datasets](/sdk-reference/datasets#follow-a-publish). Uploaded results become a terminal record. They can be analyzed, but cannot be resumed, retried, or regraded.
+
+## Share and delete
+
+| Action | TypeScript | Python |
+| --- | --- | --- |
+| Enable an unlisted link | `share(id, { link: true })` | `share(id, link=True)` |
+| Share with people | `share(id, { emails: ["person@example.com"] })` | `share(id, emails=["person@example.com"])` |
+| Revoke either form | `unshare(id, { link, emails })` | `unshare(id, link=..., emails=...)` |
+| Read share state | `shares(id)` | `shares(id)` |
+| Permanently delete | `delete(id)` | `delete(id)` |
+
+Sharing can send invitation email. Only the creator can manage shares or delete the job; team membership alone does not grant those actions. Deletion requires a terminal job with no running analysis or dependent regrade. The returned receipt counts deleted trials and analyses.

package/skills/evolve-evals/references/sdk-reference/meta.md

@@ -0,0 +1,54 @@
+---
+title: "Platform capabilities"
+description: "Discover available harnesses, models, providers, and current limits."
+---
+
+[Method reference: calls, parameters, and response fields](/sdk-reference/methods/meta).
+
+`meta()` returns the platform's capability document. It needs no API key.
+
+```ts TypeScript
+import { meta } from "@evolvingmachines/evolve";
+
+const capabilities = await meta();
+for (const agent of capabilities.agents) {
+  console.log(agent.name, agent.runnable, agent.models.map((m) => m.alias));
+}
+```
+
+```python Python
+from evolve import meta
+
+capabilities = await meta()
+for agent in capabilities.agents:
+    print(agent.name, agent.runnable, [m.alias for m in agent.models])
+```
+
+Also available as `hosted().meta()` in both languages.
+
+## What to read
+
+| Field | Use it to answer |
+| --- | --- |
+| `agents` | Which harnesses run? Which models, efforts, versions, kwargs, and presets do they support? |
+| `sandbox_providers` | Which providers support the task's resources and features? |
+| `platform_constraints` | Which requirements cannot run on this deployment? |
+| `network_modes` | Which network modes can a task declare? |
+| `analyze` | Which agents can analyses and checks run on, with which models and reasoning efforts? |
+| `limits` | What are the current defaults and bounds for jobs, pages, uploads, and comparisons? |
+| `statuses` | Which states exist, and which are terminal? |
+| `agent_registration` | Which names, environment keys, and upload sizes can a custom agent use? |
+| `error_codes`, `import_warning_codes` | Which failure and warning codes does this deployment publish? |
+| `managed_providers` | Which providers are available to the separate managed-agent runtime? |
+
+**Tip:**
+
+Read capabilities when building a picker or validating a saved configuration. A documented example is useful; a fixed copy of the platform's model catalog becomes stale.
+
+## Configuration
+
+`meta(config?)` accepts the usual [hosted configuration](/sdk-reference/index#configure-once). Only the API origin matters; credentials are not sent.
+
+The result includes `schema_version`. Treat it as the document's schema version, not the SDK package version.
+
+Read the full editable analyzer policy through [analysis defaults](/sdk-reference/analyses#read-current-defaults) or [check defaults](/sdk-reference/checks#read-current-defaults).