> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pandaprobe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reflect runtime

> Run the agent, evaluate evidence, continue reflection, and inspect outcomes

Reflect coordinates **Detect → Notify → Reflect → Validate** around an explicit agent invocation. Your agent receives failure evidence and proposes filesystem changes; independent validation determines whether they become accepted rules.

`run` returns the original task result after evaluation and any triggered reflection. It does not replace the task answer with the reflection answer. Task exceptions propagate. Validation settles separately so replay can acquire resources released by the task.

Native agent construction attaches the supplied `reflect_bash` tool and memory instructions. A generic asynchronous callback receives an `Invocation` and must pass its instructions/tool to the model and enforce phase permissions itself. See the [quickstart](https://docs.pandaprobe.com/reflect/quickstart.md), [native integrations](https://docs.pandaprobe.com/reflect/integrations/overview.md), and [custom loop guide](https://docs.pandaprobe.com/reflect/custom-loops.md).

Use unique execution IDs and related-work session IDs. Importing Reflect alone starts no work; constructing it opens its configured persistent workspace. Close Reflect and then the tracing client. An externally supplied platform client remains caller-owned.

Import `Reflect` from `pandaprobe/reflect`; alias it to `ReflectRuntime` when also using JavaScript’s built-in Reflect. Await `agent(...)`, `tool(...)`, `run(...)`, and `close()`. Supported native framework identifiers and agent options are listed below.

## On this page

[Agent](#agent), [AgentOptions](#agentoptions), [Framework](#framework), [NativeAgent](#nativeagent), [Reflect](#reflect), [ReflectInit](#reflectinit), [SubmissionOptions](#submissionoptions).

## Example

This function accepts your native agent builder. It must include the tracing integration and use `reflect.agent(...)` to attach Reflect tooling; see the [framework guides](https://docs.pandaprobe.com/reflect/integrations/overview.md).

```ts theme={null}
import { Client } from "pandaprobe";
import { Reflect as ReflectRuntime, type NativeAgent } from "pandaprobe/reflect";

async function runSupport(
  buildAgent: (reflect: ReflectRuntime, client: Client) => Promise<NativeAgent>,
) {
  const client = new Client();
  const reflect = new ReflectRuntime(client, { config: { workspace: "./agent-memory" } });
  try {
    const agent = await buildAgent(reflect, client);
    const result = await reflect.run(agent, "Help with my return.", { sessionId: "customer-42" });
    for (const proposal of reflect.proposals()) console.log(proposal.id, proposal.status);
    return result;
  } finally {
    await reflect.close();
    await client.shutdown();
  }
}
```

## `Agent`

```ts theme={null}
import type { Agent } from "pandaprobe/reflect";
```

Type parameters: `I = any`, `R = any`.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/typescript/src/reflect/integrations.ts#L11)

```text theme={null}
Agent<I = any, R = any> = ((request: Invocation<I>) => Promise<R>) | NativeAgent<I, R>
```

## `AgentOptions`

```ts theme={null}
import type { AgentOptions } from "pandaprobe/reflect";
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/typescript/src/reflect/integrations.ts#L12)

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `framework` | `"langchain" \| "langgraph" \| "deepagents" \| "openai-agents" \| "claude-agent-sdk" \| "vercel-ai"` | Required |
| `options` | `Record<string, any> \| undefined` | Optional |
| `invokeOptions` | `Record<string, any> \| undefined` | Optional |

## `Framework`

```ts theme={null}
import type { Framework } from "pandaprobe/reflect";
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/typescript/src/reflect/integrations.ts#L3)

```text theme={null}
Framework = | "generic"
  | "langchain"
  | "langgraph"
  | "deepagents"
  | "openai-agents"
  | "claude-agent-sdk"
  | "vercel-ai"
```

## `NativeAgent`

```ts theme={null}
import type { NativeAgent } from "pandaprobe/reflect";
```

Type parameters: `I = any`, `R = any`.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/typescript/src/reflect/integrations.ts#L17)

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `native` | `any` | Optional; read-only |
| `framework` | `Framework` | Required; read-only |

### Methods

> [accordion] invokeReflect
>
> ```text theme={null}
> invokeReflect(request: Invocation<I>, options?: Record<string, any>): Promise<R>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `request` | `Invocation<I>` | Required |
> | `options` | `Record<string, any>` | Optional |

## `Reflect`

```ts theme={null}
import { Reflect } from "pandaprobe/reflect";
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/typescript/src/reflect/runtime.ts#L58)

### Constructor

```text theme={null}
new Reflect(client?: Client, options?: ReflectInit): Reflect
```

| Parameter | Type | Default / passing |
| - | - | - |
| `client` | `Client` | Optional |
| `options` | `ReflectInit` | `{}` |

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `client` | `Client` | Instance value; read-only |
| `config` | `ReflectConfig` | Instance value; read-only |
| `workspace` | `Workspace` | Instance value; read-only |
| `api` | `PlatformClient` | `new PlatformClient(this.client)`; read-only |
| `validator` | `Validator` | Instance value; read-only |
| `signal` | `AbortSignal` | Instance value; read-only |

### Methods

> [accordion] withCurrent
>
> Advanced adapter lifecycle hook. Ordinary applications use run/execution and the settlement methods so attribution, scheduling, and cleanup stay paired. Do not expose this hook to the agent.
>
> ```text theme={null}
> withCurrent<T>(execution: Execution, callback: () => T): T
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `execution` | `Execution` | Required |
> | `callback` | `() => T` | Required |

> [accordion] assertOpen
>
> Advanced adapter lifecycle hook. Ordinary applications use run/execution and the settlement methods so attribution, scheduling, and cleanup stay paired. Do not expose this hook to the agent.
>
> ```text theme={null}
> assertOpen(): void
> ```

> [accordion] trackExecution
>
> Advanced adapter lifecycle hook. Ordinary applications use run/execution and the settlement methods so attribution, scheduling, and cleanup stay paired. Do not expose this hook to the agent.
>
> ```text theme={null}
> trackExecution(execution: Execution): void
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `execution` | `Execution` | Required |

> [accordion] untrackExecution
>
> Advanced adapter lifecycle hook. Ordinary applications use run/execution and the settlement methods so attribution, scheduling, and cleanup stay paired. Do not expose this hook to the agent.
>
> ```text theme={null}
> untrackExecution(execution: Execution): void
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `execution` | `Execution` | Required |

> [accordion] execution
>
> The callback must encompass actual work, including consuming streams.
>
> ```text theme={null}
> execution<T>(options: ExecutionOptions, callback: (execution: Execution) => Promise<T>): Promise<T>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `options` | `ExecutionOptions` | Required |
> | `callback` | `(execution: Execution) => Promise<T>` | Required |

> [accordion] bash
>
> ```text theme={null}
> bash(command: string): Promise<string>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `command` | `string` | Required |

> [accordion] tool
>
> Returns the supplied tool in a generic or native framework format. The generic tool accepts a command string and must run inside an active Reflect boundary.
>
> ```text theme={null}
> tool(framework?: Framework): Promise<any>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `framework` | `Framework` | `"generic"` |

> [accordion] agent
>
> Builds a supported native agent with Reflect tools and memory integration. Pass the framework’s factory/constructor and its native options; do not also add reflect\_bash manually.
>
> ```text theme={null}
> agent(factory: any, options: AgentOptions): Promise<NativeAgent>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `factory` | `any` | Required |
> | `options` | `AgentOptions` | Required |

> [accordion] submitTraces
>
> Schedules evaluation for completed trace references; identities must belong to the same project. Reusing a trace under a different execution ID is rejected.
>
> ```text theme={null}
> submitTraces(traceIds: string[], options: SubmissionOptions): Promise<EvaluationOutcome>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `traceIds` | `string[]` | Required |
> | `options` | `SubmissionOptions` | Required |

> [accordion] waitExport
>
> ```text theme={null}
> waitExport(options?: { timeout?: number; }): Promise<void>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `options` | `{ timeout?: number }` | `{}` |

> [accordion] settleEvaluation
>
> Waits for evaluation evidence for this execution. A caller wait deadline can leave the underlying run pending.
>
> ```text theme={null}
> settleEvaluation(
>   executionId: string,
>   options?: { timeout?: number; signal?: AbortSignal; },
> ): Promise<EvaluationOutcome>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `executionId` | `string` | Required |
> | `options` | `{ timeout?: number; signal?: AbortSignal }` | `{}` |

> [accordion] resumeEvaluations
>
> Resumes persisted pending evaluation work after restart; known evaluation IDs are polled instead of recreated.
>
> ```text theme={null}
> resumeEvaluations(): Promise<EvaluationOutcome>[]
> ```

> [accordion] continueReflection
>
> Uses the supplied host continuation when evaluation has produced a failure notice. Delayed feedback does not automatically restart an agent.
>
> ```text theme={null}
> continueReflection(
>   executionId: string,
>   continuation: Agent,
>   options?: { input?: unknown; previousResult?: unknown; signal?: AbortSignal; },
> ): Promise<ProposalOutcome>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `executionId` | `string` | Required |
> | `continuation` | `Agent` | Required |
> | `options` | `{ input?: unknown; previousResult?: unknown; signal?: AbortSignal }` | `{}` |

> [accordion] settleReflection
>
> Waits for an already scheduled reflection checkpoint. A caller wait timeout is distinct from the checkpoint’s execution deadline.
>
> ```text theme={null}
> settleReflection(
>   executionId: string,
>   options?: { timeout?: number; signal?: AbortSignal; },
> ): Promise<ProposalOutcome>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `executionId` | `string` | Required |
> | `options` | `{ timeout?: number; signal?: AbortSignal }` | `{}` |

> [accordion] run
>
> ```text theme={null}
> run<I, R>(
>   agent: Agent<I, R>,
>   input: I,
>   options: ExecutionOptions & { invokeOptions?: Record<string, unknown>; },
> ): Promise<R>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `agent` | `Agent<I, R>` | Required |
> | `input` | `I` | Required |
> | `options` | `ExecutionOptions & { invokeOptions?: Record<string, unknown> }` | Required |

> [accordion] report
>
> Returns the execution’s task, evaluation, reflection, and proposal outcomes. Does not infer business success from task completion.
>
> ```text theme={null}
> report(executionId: string): ExecutionReport
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `executionId` | `string` | Required |

> [accordion] proposals
>
> Returns persisted proposals, including their lifecycle state and decision evidence.
>
> ```text theme={null}
> proposals(): RuleProposal[]
> ```

> [accordion] scheduleValidation
>
> Advanced adapter lifecycle hook. Ordinary applications use run/execution and the settlement methods so attribution, scheduling, and cleanup stay paired. Do not expose this hook to the agent.
>
> ```text theme={null}
> scheduleValidation(outcome: ProposalOutcome): void
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `outcome` | `ProposalOutcome` | Required |

> [accordion] validate
>
> ```text theme={null}
> validate(
>   proposalId: string,
>   options: { cases: ReplayCase[]; replay: Replay; signal?: AbortSignal; },
> ): Promise<ValidationVerdict>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `proposalId` | `string` | Required |
> | `options` | `{ cases: ReplayCase[]; replay: Replay; signal?: AbortSignal }` | Required |

> [accordion] settleValidation
>
> ```text theme={null}
> settleValidation(options?: { timeout?: number; signal?: AbortSignal; }): Promise<boolean>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `options` | `{ timeout?: number; signal?: AbortSignal }` | `{}` |

> [accordion] trialExecution
>
> ```text theme={null}
> trialExecution<T>(
>   proposalId: string,
>   options: { arm: "control" | "candidate"; sessionId?: string; signal?: AbortSignal; },
>   callback: (execution: Execution) => Promise<T>,
> ): Promise<T>
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `proposalId` | `string` | Required |
> | `options` | `{ arm: "control" \| "candidate"; sessionId?: string; signal?: AbortSignal }` | Required |
> | `callback` | `(execution: Execution) => Promise<T>` | Required |

> [accordion] close
>
> Cancels owned work, bounds the shutdown wait, and closes an owned platform client. It does not close a caller-supplied platform client or the tracing client.
>
> ```text theme={null}
> close(): Promise<void>
> ```

## `ReflectInit`

```ts theme={null}
import type { ReflectInit } from "pandaprobe/reflect";
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/typescript/src/reflect/runtime.ts#L52)

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `config` | `Partial<{ workspace: string; traceVisibilityTimeout: number; evaluationTimeout: number; pollInterval: number; evaluationMaxRuns: number \| null; evaluationMaxTraces: number; evaluationSampleRate: number; maxConcurrency: number; cooldownSeconds: number; reflectionTimeout: number; shutdownTimeout: number; reflectionMaxCommands: number; shellTimeout: number; shellMaxCommands: number; shellMaxLoopIterations: number; shellMemoryBytes: number; commandMaxBytes: number; outputMaxBytes: number; executionOutputMaxBytes: number; contextMaxBytes: number; ruleMaxBytes: number; rulesMaxBytes: number; rulesMaxCount: number; evidenceMaxBytes: number; thresholds: Record<string, number>; diagnosticMetrics: readonly string[]; stallWindow: number; minimumProgress: number; regressionDrop: number; validationMinCases: number; validationMinImprovement: number; validationRegressionTolerance: number; validationTimeout: number; }> \| ReflectConfig \| undefined` | Optional |
| `api` | `PlatformClient \| undefined` | Optional |
| `replay` | `Replay \| undefined` | Optional |
| `cases` | `ReplayCase<unknown>[] \| undefined` | Optional |

## `SubmissionOptions`

Supporting contract used by the API below; it is not a separate package export.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/typescript/src/reflect/evaluation.ts#L20)

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `executionId` | `string` | Required |
| `sessionId` | `string` | Required |
| `completed` | `boolean \| undefined` | Optional |

***

Signatures and fields are generated from the [SDK source](https://github.com/chirpz-ai/pandaprobe-sdk/tree/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/typescript). See the [import index](https://docs.pandaprobe.com/reference/typescript/overview.md#public-import-index) for available entry points.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.