# @zephyrcloudio/harness-codemode

Run JavaScript that combines tools and returns selected results. For using CodeMode in the terminal,
see the [CLI guide](/docs/cli.md).

## Usage

```ts
import { CodeMode, Tool, renderResult } from '@zephyrcloudio/harness-codemode';
import { Effect, Schema } from 'effect';

const runtime = CodeMode.make({
  tools: {
    echo: Tool.make({
      description: 'Return the supplied JSON value.',
      input: Schema.Json,
      output: Schema.Json,
      execute: (value) => Effect.succeed(value),
    }),
  },
});

const result = await Effect.runPromise(runtime.execute('return await tools.echo("hello");'));
console.log(renderResult(result)); // hello
```

Use `await` for dependent calls and `Promise.all` or `Promise.allSettled` for independent work.
Await every call you need: returning interrupts unfinished work. Use `return` for the result;
console output, including `console.table`, is also included when execution finishes.

Scripts can access only the supplied tools, with no imports or direct filesystem/network access.
Use synchronous `search({ query })` inside a script to find an unfamiliar tool's path and signature.
Effect schemas validate tool arguments and results; plain JSON Schemas describe them but do not
validate them. Tool authorization remains the host's responsibility.

## Display formatting

```ts
const { formatCodeMode } = await import('@zephyrcloudio/harness-codemode/format');
const displaySource = await formatCodeMode(source);
```

Formatting accepts JavaScript and TypeScript and leaves invalid source unchanged. Execution still
requires JavaScript; use formatted text for display only. For repeated renders, create a reusable
formatter with `makeCodeModeFormatter()` from the same import path.

## Limits

The interpreter currently has these fixed limits:

- String length: 16,777,216 code units.
- Array length: 10,000,000 elements.
- Pending promises: 10,000.
- Plain-data value depth: 32.
- Function call depth: 10,000; resets when an await resumes.
- Console formatting depth: 32.
- Signature schema rendering depth: 8.

Execution limits produce an error; console and signature depth limits abbreviate displayed values.
These limits are not configurable. There is no default execution timeout or total tool-call limit.


## Public TypeScript exports

- `CodeMode`
- `Tool`

---

Generated from [`packages/codemode/README.md`](https://github.com/ZephyrCloudIO/ze-harness/blob/main/packages/codemode/README.md).