# submit

Queue a turn in the session log.

`runtime.submit(scope, input)` writes a queued turn and its `queued` event in one transaction through the SDK's `SessionLog`. It works before `open`, so a host can accept prompts before the session loads. Submission is idempotent by request ID: the same prompt again returns the stored turn.

```ts title="host.ts"
import type { AgentRuntime } from 'nanocode-wasm'

declare const runtime: AgentRuntime

// 1. Queue the prompt under a request ID that the client chose
const submitted = await runtime.submit('owner', {
  metadata: { user: 'u1' },
  prompt: 'Summarize the log.',
  request_id: 'turn-1',
})

// 2. Drive only a new turn
if (submitted.submitted === 'accepted') await runtime.drive('turn-1')
```

## Signature

```ts
// Resolves with the submission outcome
submit(
  scope: string,
  input: {
    request_id: string
    prompt: string
    hand?: string
    metadata: unknown
  },
): Promise<Submitted>
```

## Parameters

### scope

* **Type:** `string`

The session log scope, the same value as `config.scope`.

```ts
// One log per scope
await runtime.submit('owner', {
  metadata: {},
  prompt: 'Hello.',
  request_id: 'turn-1',
})
```

### input.hand

* **Type:** `string`

The name of the hand that Code Mode uses for this turn. Without it, the turn uses the default executor, or the only attached hand if no default exists.

```ts
// Runs this turn's Code Mode work on the laptop hand
await runtime.submit('owner', {
  hand: 'laptop',
  metadata: {},
  prompt: 'List the files.',
  request_id: 'turn-2',
})
```

### input.metadata

* **Type:** `unknown`

JSON that the turn stores. `TurnView.metadata` returns it unchanged.

```ts
// Stores the caller's identity with the turn
await runtime.submit('owner', {
  metadata: { user: 'u1' },
  prompt: 'Hello.',
  request_id: 'turn-3',
})
```

### input.prompt

* **Type:** `string`

The user prompt of the turn.

```ts
// A plain text prompt
await runtime.submit('owner', {
  metadata: {},
  prompt: 'Explain the last error.',
  request_id: 'turn-4',
})
```

### input.request_id

* **Type:** `string`

The turn's ID within the scope. Clients retry a submission with the same ID. [`admit`](/docs/api/wasm/AgentRuntime#admit) rejects IDs that the SDK reserves.

```ts
// A random ID per prompt
await runtime.submit('owner', {
  metadata: {},
  prompt: 'Hello.',
  request_id: crypto.randomUUID(),
})
```

## Returns

* **Type:** `Promise<Submitted>`

```ts
type Submitted =
  // A turn exists for the request ID
  | { submitted: 'accepted' | 'existing' | 'conflict'; turn: TurnView }
  // The turn or its input.accepted event does not fit value_limit
  | { submitted: 'too_large'; bytes: number; limit: number }
```

### submitted

* **Type:** `'accepted' | 'existing' | 'conflict' | 'too_large'`

| Value       | Meaning                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------- |
| `accepted`  | The turn is new and queued. `published` receives its `queued` event.                     |
| `existing`  | A turn with this ID and the same prompt and hand exists.                                 |
| `conflict`  | A turn with this ID exists with a different prompt or hand.                              |
| `too_large` | `value_limit` is set and the turn row or its `input.accepted` event would not fit in it. |

```ts
import type { Submitted } from 'nanocode-wasm'

declare const submitted: Submitted

// Maps a conflict to an HTTP status
const status = submitted.submitted === 'conflict' ? 409 : 202
```

### turn

* **Type:** `TurnView`

The stored turn. [turn and pending](/docs/api/wasm/turn#returns) documents `TurnView`.

```ts
import type { Submitted } from 'nanocode-wasm'

declare const submitted: Submitted

// The report of the stored turn
if ('turn' in submitted) console.log(submitted.turn.report.status)
```

### bytes and limit

* **Type:** `number`

For `too_large`, the encoded size of the turn and the SQL host's `value_limit`, in bytes.

```ts
import type { Submitted } from 'nanocode-wasm'

declare const submitted: Submitted

// Reports the size to the client
if (submitted.submitted === 'too_large')
  console.log(`${submitted.bytes} > ${submitted.limit}`)
```

## Errors

The promise rejects if the SQL host throws or the runtime is closed.

```ts
import type { AgentRuntime } from 'nanocode-wasm'

declare const runtime: AgentRuntime

// Rejects with the transaction error
await runtime
  .submit('owner', {
    metadata: {},
    prompt: 'Hello.',
    request_id: 'turn-1',
  })
  .catch(console.error)
```