# Agent OS Import Contract

ECF Core exports Agent OS preview artifacts. These are local/self-hosted handoff files, not a live Agent OS deployment.

## Generated Files

When you run:

```bash
ecf-core compile . --agent-os
```

ECF Core writes:

```text
.ecf-core/
  context-packet.json
  source-map.json
  source-manifest.json
  policy-summary.json
  evidence-units.json
  context-evidence-units.json
  context-compaction-report.json
  page-index.json
  tree-index.json
  retrieval-plan.json
  code-index.json
  context-router.json
  deployment-preview.json
  agent-os-harness.json
  agent-os-handoff.json
  agent-os-import.json
  grounding-eval.json       # when eval --grounding is run
```

## Import Boundary

`agent-os-import.json` is stable as `ecf-core.agent-os-import.v1`.

It declares:

- `import_mode: "preview_only"`
- `live_deploy_allowed: false`
- required local artifact files
- acceptance checks for preview import
- compile-stage readiness summary for owner-facing Agent OS preview cards
- context index readiness from `page-index.json`, `tree-index.json`, and `retrieval-plan.json`
- source-manifest, code-index, and context-router evidence for deterministic first-run retrieval
- explicit boundary flags proving the export does not include hosted runtime, settlement, marketplace routing, or Full ECF private internals

## Consumer Rule

Any Agent OS importer should treat ECF Core artifacts as preview evidence only. A separate Agent OS deployment flow must perform its own owner review, policy checks, runtime provisioning, billing/spend authorization, and launch gates.

Agent OS can use `evidence-units.json`, `source-manifest.json`, `code-index.json`, `context-router.json`, `page-index.json`, `tree-index.json`, `retrieval-plan.json`, and `grounding-eval.json` as preview evidence when deciding whether a deployment has enough allowed context to launch safely. A passing grounding eval is not deployment approval; it is evidence for the owner-facing readiness report.

## Rust Framework Runtime Metadata

An importer may pair `agent-os-harness.json` with a local Agoragentic Rust framework runtime when the runtime is exposed over HTTP/JSON. Treat that runtime metadata as preview evidence until a separate Agent OS launch flow approves runtime provisioning, owner policy, and billing/spend controls.

The local Rust runtime compatibility surface is:

- `GET /health`
- `GET /.well-known/agent-card.json`
- `GET /tools`
- `POST /invoke`
- `POST /a2a/invoke`
- `GET /schema/agoragentic-rust-framework.json`
- `GET /openapi.json`

Consumers should verify the runtime health response, Agent Card, tool manifest, JSON Schema, and OpenAPI profile before showing runtime readiness. They should use the stable HTTP/JSON, JSON Schema, TypeScript declaration, and Python model boundaries rather than requiring PyO3, N-API, WASM, local model downloads, wallet access, or hosted provider calls.

See [`../examples/importers/rust-framework-agent-os-harness-import.example.json`](../examples/importers/rust-framework-agent-os-harness-import.example.json) for a preview-only importer fixture. The fixture does not deploy a Rust agent, expose a public API, publish a marketplace listing, enable x402, mutate trust, change hosted Router routes, or grant Full ECF access.

## Local Preview Check

Before handing artifacts to Agent OS, run:

```bash
ecf-core agent-os-preview .ecf-core
```

The check verifies:

- `agent-os-import.json` uses the stable preview-only schema
- every required artifact file exists
- deployment-preview checks satisfy import acceptance checks
- context index artifacts are readable and preview-only
- optional grounding evidence is readable when present
- the boundary flags still prove there is no hosted runtime, wallet/settlement authority, marketplace routing, or Full ECF private internals

Machine-readable output is available with:

```bash
ecf-core agent-os-preview .ecf-core --json
```

## Hosted Agent OS Preview

If you have an Agoragentic API key, the Agent OS CLI can ingest the preview packet directly:

```bash
AGORAGENTIC_API_KEY=amk_your_api_key npx -y agoragentic-os preview .ecf-core/agent-os-import.json
```

This command calls the hosted Agent OS preview endpoint only. It does not create a deployment, fund wallets, expose APIs, publish marketplace listings, enable x402, or grant Full ECF access.

## Third-Party Importer Examples

See [`../examples/importers/`](../examples/importers/) for a minimal consumer-side contract.

Third-party importers must treat ECF Core artifacts as preview evidence only. They should validate files, checks, grounding evidence, and boundary flags, then show an owner-facing readiness report. They must not auto-deploy, fund wallets, publish marketplace listings, expose public APIs, enable x402, or infer Full ECF access.