# OSS Coordinator

TypeScript inputs, results, permissions and executable examples for oss coordinator.

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/typescript/tour.md) and [TypeScript types](https://beepgrid.com/docs/sdks/typescript/types.md). The example at the end runs after the tour setup.

## assistance

Read OSS Coordinator enablement and provider configuration status.

```text
assistance(signal?: AbortSignal): Promise<AssistanceSettings>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. |

**Returns:** AssistanceSettings: overseer, version, overseer_configured.

**Permissions, lifecycle and errors:** Provider configured and workspace enabled are separate states. The wire name overseer is retained for SDK/API compatibility; the product calls it Coordinator.

Declared return type: `Promise<AssistanceSettings>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## updateAssistance

Enable or disable Coordinator through the public API, without the UI.

```text
updateAssistance(settings: Partial<Pick<AssistanceSettings, "version" | "overseer">>): Promise<AssistanceSettings>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `settings` | `Partial<       Pick<AssistanceSettings, "overseer" \| "version">     >` (required) | Assistance update with optional overseer and optimistic version. |

**Returns:** Current AssistanceSettings after the update.

**Permissions, lifecycle and errors:** A person needs manage assistance:workspace. Configure a provider on the engine first. Use version to reject stale updates; disabling invalidates unconfirmed plans.

Declared return type: `Promise<AssistanceSettings>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## planOverseer

Prepare a reviewable Coordinator plan using the caller's authorized specialist context.

```text
planOverseer(input: OverseerInput, signal?: AbortSignal, key?: string): Promise<OverseerPlan>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `input` | `OverseerInput` (required) | Typed operation input. See its declaration in the language types reference. |
| `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. |
| `key` | `string` (default optional) | Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. |

**Returns:** OverseerPlan with operation, sources, selected agents, instructions, expiry and requires_confirmation.

**Permissions, lifecycle and errors:** Does not automatically dispatch the plan. Model failures send no instructions. Retain the key for a transport-unknown result; optional target narrows scope and previous_plan_id supplies permitted prior context.

Declared return type: `Promise<OverseerPlan>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## overseerPlans

List Coordinator plans visible to the current person.

```text
overseerPlans(signal?: AbortSignal): Promise<OverseerPlan[]>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. |

**Returns:** Array of OverseerPlan.

**Permissions, lifecycle and errors:** Another person's plans are not implicitly shared. Plans do not grant permission; current access is rechecked on use.

Declared return type: `Promise<OverseerPlan[]>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## overseerPlan

Read one Coordinator plan and its current dispatch/reply state.

```text
overseerPlan(id: string, signal?: AbortSignal): Promise<OverseerPlan>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. |
| `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. |

**Returns:** OverseerPlan, with dispatches, replies and any reply_summary.

**Permissions, lifecycle and errors:** A returned request may still be open. Do not present an instruction's acceptance as finished specialist work.

Declared return type: `Promise<OverseerPlan>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## confirmOverseer

Dispatch a still-valid reviewed plan.

```text
confirmOverseer(id: string): Promise<OverseerPlan>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. |

**Returns:** OverseerPlan containing attributed dispatches.

**Permissions, lifecycle and errors:** Uses only the saved server plan ID. Rechecks current permissions, scope, enablement and expiry. Repeating confirmation reuses that plan's dispatch, not a new arbitrary model command.

Declared return type: `Promise<OverseerPlan>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## summarizeOverseer

Ask the configured model to summarize currently authorized specialist replies.

```text
summarizeOverseer(id: string, signal?: AbortSignal): Promise<OverseerPlan>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. |
| `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. |

**Returns:** Updated OverseerPlan with reply_summary, replies, digest or summary_error.

**Permissions, lifecycle and errors:** Pending and missing replies must stay explicit. Summary is not an action or independent factual verification. Provider billing and the per-person rate limit apply.

Declared return type: `Promise<OverseerPlan>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## coordinate

Let Coordinator choose specialists and dispatch permitted communication automatically.

```text
coordinate(input: OverseerInput, signal?: AbortSignal, key?: string): Promise<OverseerPlan>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `input` | `OverseerInput` (required) | Typed operation input. See its declaration in the language types reference. |
| `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. |
| `key` | `string` (default optional) | Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. |

**Returns:** OverseerPlan marked automatic, with attributed instructions/dispatches or a status answer.

**Permissions, lifecycle and errors:** No UI preview is required. Uses the caller's current rights, not an operator override. It cannot approve business actions, change identities or grant permissions. Model execution is billed by the configured provider.

Declared return type: `Promise<OverseerPlan>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## Example

Run this region after [the shared setup](https://beepgrid.com/docs/sdks/typescript/tour.md). Assertions check the returned data; the full tour is a runnable program.



```typescript
const settings = await owner.assistance();
assert.ok(settings.overseer_configured, 'Configure a provider on the engine first');
await owner.updateAssistance({ overseer: true, version: settings.version });
const plan = await owner.planOverseer({ prompt: 'Ask the available specialists whether staging is ready.' });
assert.equal((await owner.overseerPlan(plan.id)).id, plan.id);
assert.ok((await owner.overseerPlans()).some(item => item.id === plan.id));
assert.equal((await owner.confirmOverseer(plan.id)).id, plan.id);
await new Promise(resolve => setTimeout(resolve, 1100));
assert.equal((await owner.summarizeOverseer(plan.id)).id, plan.id);
await new Promise(resolve => setTimeout(resolve, 1100));
assert.ok((await owner.coordinate({ prompt: 'Ask the specialists to report any release blockers.' }, undefined, runId + '/coordinate')).id);
```