# Examples

These programs exercise `flows` against one existing Letta agent. They create new conversations on that agent; they never create a replacement identity.

## Prerequisites

- Install the repository dependencies with Bun 1.4.2 using `bun install --frozen-lockfile`. Bun 1.3.8 cannot parse the checked-in lockfile.
- Authenticate the Letta Agent SDK.
- Set `LETTA_AGENT_ID` or `AGENT_ID` to the agent the flow should use.

Run examples from the repository root.

## Compare independent perspectives

[`advisory-panel.ts`](./advisory-panel.ts) opens three fresh conversations for an optimist, a skeptic, and an operator. A fourth conversation receives their successful outputs and synthesizes a recommendation without hiding disagreement.

```bash
bun examples/advisory-panel.ts "Should we ship this workflow?"
```

The example prints the synthesis to standard output and conversation IDs to standard error. It writes no files.

## Audit source files for security defects

[`security-sweep.ts`](./security-sweep.ts) assigns source files to fresh, tool-free hunter conversations, validates their structured findings, and gives the collected reports to a security-monitor conversation. Use the shell wrapper from an interactive terminal so a workspace-scoped `LETTA_API_KEY` cannot shadow device authentication:

```bash
./examples/security-sweep.sh src --max 8 --concurrency 3
```

Add `--model <handle>` to set a conversation-scoped model, `--print` to print the complete report, or `--out <file>` to choose the report path. The sweep writes a private Markdown report and JSON record under `security-sweeps/` by default. Treat model findings as review candidates, not confirmed vulnerabilities.

## Draft and review a publication batch

[`public-knowledge-batch.ts`](./public-knowledge-batch.ts) runs a finite editorial workflow:

1. A fresh tool-free conversation drafts each article from a frozen public-source packet.
2. Another stateless conversation reviews the draft against the same packet.
3. A new conversation revises drafts with blocking findings.
4. A final conversation reviews each revision once.

Start from the version 2 [`public-knowledge-batch.example.json`](./public-knowledge-batch.example.json). Each packet file must declare which public source IDs it represents. The loader checks that every declared source is mapped, but the person assembling the packet remains responsible for its provenance. Copy the manifest beside the source files it names, then validate paths and hashes without calling a model:

```bash
bun examples/public-knowledge-batch.ts path/to/manifest.json --dry-run
```

Run the batch after inspecting the dry-run artifacts:

```bash
bun examples/public-knowledge-batch.ts path/to/manifest.json --concurrency 3
```

The CLI confines output to `publication-runs/`. Each run contains candidate Markdown, reviews, a complete result, and a content-dark receipt with conversation IDs, run IDs, source and artifact hashes, timing, cost, failures, and integration-readiness state.

The workflow has no Git, deployment, protocol-write, or publication capability. Because it uses an existing agent ID, the model still receives that agent's server-compiled system context even when the local session is stateless. The source packet is the declared evidence basis, not the only text visible to the model. `readyForIntegration` means the model and deterministic checks found no remaining block. A separately authorized integration process must still inspect the prose for private-context leakage, verify semantic source coverage, run the target repository's checks, and publish the artifact.

## Read the runtime contract

The root [`README`](../README.md) explains flow scopes, fresh conversations, session cleanup, structured results, and the current limits of the DSL. [`PLAN.md`](../PLAN.md) records the experiments that remain intentionally deferred.