# Ageniti Agent Bootstrap

Read this file first if you are a local coding agent preparing to work with the Ageniti SDK.

Your job is to do the setup yourself from clone onward. Do not ask the user to manually clone the repository unless you are blocked by permissions or environment limits.

## Scope

- Focus on the Ageniti SDK package.
- If the repository contains an `ageniti/` directory, treat that directory as the package root.
- Ignore `website/` unless the user explicitly asks for website work.

## Start From Clone

1. Clone the repository:

```text
git clone https://github.com/Ageniti/ageniti.git
```

2. Detect the package root:

- If the cloned repository root is the SDK package, use that root.
- If the cloned repository contains `ageniti/package.json`, use `ageniti/` as the package root.
- The package root is the directory that contains the SDK source, docs, tests, and `AGENTS.md`.

3. Read these files in order from the package root:

- `AGENTS.md`
- `docs/getting-started.md`
- `docs/api.md`
- `docs/skill.md`

4. Install dependencies in the package root:

```text
npm install
```

5. Inspect the package scripts and available commands before making changes.

## What Ageniti Is

Ageniti is the action primitive layer for apps that need to expose capabilities to agents, automation systems, and external tools. The main model is:

```text
existing app capability
  -> action contract
  -> shared runtime
  -> multiple external surfaces
```

## Main Surfaces

Expect the SDK to expose app capabilities through:

- CLI (with `--ndjson` live streaming, `--idempotency-key`, `--timeout-ms`)
- HTTP (detailed status codes, Content-Type guard, body size limit)
- MCP (stdio auto-detects Content-Length and newline framing)
- OpenAI-compatible tools
- OpenAI Responses tools
- AI SDK tools
- JSON automation
- typed in-process / HTTP client (`@ageniti/core/client`)
- local dev console
- React invocation (`useAction` state-machine hook in `@ageniti/core/react-hooks`)

## Key Primitives

- Action contract (`defineAction`) — input + output schema, side effects, permissions, run.
- Foreign schema interop — `defineAction({ input: zodSchema })` accepts Zod and Standard Schema v1 directly via duck typing.
- Bulk registration — `defineActions`, `actionFromHandler`, `actionsFromHandlers` to wrap existing handler records.
- Streaming events — `runtime.stream(name, input)` returns an async iterable of `log` / `progress` / `artifact` / `result` events that any consumer can subscribe to.
- Typed client + codegen — `createClient` for proxy-style invocation, `generateClientTypes` to emit a `.d.ts` for IDE autocomplete on the consumer side.
- Test utilities — `createTestRuntime`, `expectOk`, `expectError`, `collectStream`, `stubAction`.
- Runtime controls — idempotency keys (LRU-bounded), per-action concurrency limits, per-attempt cancellation, hooks for telemetry, secret redaction in logs / artifact metadata / error messages.

## Working Rules

- Treat the action contract as the source of truth.
- Keep the package entry used for CLI, MCP, HTTP, and build flows Node-safe.
- Do not call `action.run()` directly from external surfaces.
- Respect visibility, permissions, confirmation, side effects, and supported surfaces.
- Treat generated manifests, schemas, `publicMetadata`, and `GUIDE.md` as public contract.
- Keep internal-only details in `metadata`, not `publicMetadata`.

## First Commands To Try

From the package root:

```text
npm install
npm test
```

Then use package-specific commands such as:

```text
ageniti doctor
ageniti init host-openai
task-app docs
task-app build
task-app mcp --stdio
```

## Done When

You understand:

- what the SDK exposes
- how the package root is structured
- which docs define the public contract
- which commands you should run for the current task

If you need more detail after this file, continue with `AGENTS.md` in the package root.