# As an SDK, without a folder

The folder is the default and not the only way in. The same app can be a value you
import:

```ts
import { createApp, agent, fn, guard } from "@praecise/harness";

const app = await createApp({
  name: "acme",
  config: { models: { /* ... */ } },
  agents: {
    support: agent({ role: "Help.", description: "Answers questions.", tools: ["lookup"] }),
  },
  functions: {
    lookup: fn({
      description: "Look up an order.",
      input: { id: "the order id" },
      effect: "read",
      run: ({ id }) => ({ id, status: "delivered" }),
    }),
  },
  guard: guard((attempt) => (attempt.effect === "write" ? "read-only today" : undefined)),
});

await app.ask("support", "where is order 12?");
```

The record key is the name, which is the rule the folder already uses:
`agents/support.ts` and `{ agents: { support } }` are the same agent by the same name.

Reach for this when the folder cannot be one:

- **You are shipping agents in a package.** A library cannot ship a folder — it can ship
  one to copy, which stops receiving fixes the moment it is copied. It can export an app,
  or a piece of one.
- **There is no filesystem to scan.** An edge worker, a bundled binary, a browser. The
  loader needs `readdir` and dynamic `import` of arbitrary paths; a bundler needs to see
  imports statically. Those requirements are opposed, and this side satisfies the second.
- **The app is assembled, not written.** Generated from a spec, composed per tenant, built
  from parts.

Both doors produce the same project and run the same checks. An agent with no role, memory
pointing at a store that does not exist, a workflow with a cycle — each is refused the same
way in the same words, because two front doors with two standards is a framework where a
bug report cannot be reproduced.

`defineApp` returns the project without starting it, so you can inspect `warnings` and
`faults` first. `createApp` refuses to start a faulted app rather than serving one that is
missing the agent the next request names.

## Changing agents while the app runs

A running app can take a new agent, a new version of one, or lose one:

```ts
await app.add(agent({ name: "billing", role: "Answer billing questions." }));
await app.replace(agent({ name: "support", role: "Customer support for Acme.", tools: ["lookup"] }));
await app.remove("billing");
```

The agent is checked and planned as it would be at load. Requests already under
way finish on the plan they started with; the next request for that name gets the
new one. MCP clients are not sent a list-changed notification.

## Testing without a model

`@praecise/harness/testing` is a model that says what a test tells it to:

```ts
import { createApp } from "@praecise/harness";
import { scriptedModel } from "@praecise/harness/testing";

const model = scriptedModel([
  { tool: { name: "lookup", args: { order: "9" } } },
  "It shipped.",
]);

const app = await createApp({ config: { models: model.models }, agents, functions });
const answer = await app.ask("support", "where is order 9?");

model.requests; // every request the app made, in order
```

Each entry is one reply: text, a tool call, or a function of the request.
`scriptedEndpoint` does the same one level down, as a `fetch` that answers with
the bodies it is given, and `systemText` reads the instructions out of a request.
