<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->

# ctx.goals

`GoalService` — provided by `@deepseek-ai/dsh-goal`.

Goal service (`ctx.goals`) backed exclusively by the owning session log.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/goal/goal/src/index.ts#L135)

### ctx.goals.get(agent)

```ts website-api
/**
 * Read the current goal for one exact live agent.
 * @param agent - owning live agent.
 * @returns a fresh view or `undefined` when no goal is current.
 * @throws {@link GoalError} when the agent is not the registry's live instance.
 */
get(agent: Agent): GoalView | undefined
```

Read the current goal for one exact live agent.

- `agent` — owning live agent.

**Returns** a fresh view or `undefined` when no goal is current.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/goal/goal/src/index.ts#L161)

### ctx.goals.create(agent, request)

```ts website-api
/**
 * Create and arm a goal. A completed goal may be replaced; every other
 * current phase must be cleared or resumed instead.
 * @param agent - owning live agent.
 * @param request - objective and optional round cap.
 * @returns the created live view.
 */
create(agent: Agent, request: CreateGoalRequest): GoalView
```

Create and arm a goal. A completed goal may be replaced; every other current phase must be cleared or resumed instead.

- `agent` — owning live agent.
- `request` — objective and optional round cap.

**Returns** the created live view.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/goal/goal/src/index.ts#L175)

### ctx.goals.edit(agent, ref, request)

```ts website-api
/**
 * Edit objective and/or round cap without changing phase.
 * @param agent - owning live agent.
 * @param ref - expected current revision.
 * @param request - at least one replacement field.
 * @returns the edited view.
 */
edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
```

Edit objective and/or round cap without changing phase.

- `agent` — owning live agent.
- `ref` — expected current revision.
- `request` — at least one replacement field.

**Returns** the edited view.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/goal/goal/src/index.ts#L200)

### ctx.goals.pause(agent, ref)

```ts website-api
/**
 * Pause an active goal and disarm automatic continuation.
 * @param agent - owning live agent.
 * @param ref - expected current revision.
 * @returns the paused view.
 */
pause(agent: Agent, ref: GoalRef): GoalView
```

Pause an active goal and disarm automatic continuation.

- `agent` — owning live agent.
- `ref` — expected current revision.

**Returns** the paused view.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/goal/goal/src/index.ts#L221)

### ctx.goals.resume(agent, ref)

```ts website-api
/**
 * Resume and arm a stopped goal, or rearm an active goal after a
 * session-start edge, while its round budget still has capacity.
 * @param agent - owning live agent.
 * @param ref - expected current revision.
 * @returns the active view.
 */
resume(agent: Agent, ref: GoalRef): GoalView
```

Resume and arm a stopped goal, or rearm an active goal after a session-start edge, while its round budget still has capacity.

- `agent` — owning live agent.
- `ref` — expected current revision.

**Returns** the active view.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/goal/goal/src/index.ts#L232)

### ctx.goals.complete(agent, ref)

```ts website-api
/**
 * Mark a current non-complete goal complete and disarm it.
 * @param agent - owning live agent.
 * @param ref - expected current revision.
 * @returns the completed view.
 */
complete(agent: Agent, ref: GoalRef): GoalView
```

Mark a current non-complete goal complete and disarm it.

- `agent` — owning live agent.
- `ref` — expected current revision.

**Returns** the completed view.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/goal/goal/src/index.ts#L257)

### ctx.goals.block(agent, ref, reason)

```ts website-api
/**
 * Mark an active goal blocked and disarm it.
 * @param agent - owning live agent.
 * @param ref - expected current revision.
 * @param reason - policy-owned stable code and human-readable explanation.
 * @returns the blocked view with its durable reason.
 */
block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
```

Mark an active goal blocked and disarm it.

- `agent` — owning live agent.
- `ref` — expected current revision.
- `reason` — policy-owned stable code and human-readable explanation.

**Returns** the blocked view with its durable reason.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/goal/goal/src/index.ts#L275)

### ctx.goals.clear(agent, ref)

```ts website-api
/**
 * Clear the current goal while retaining a durable tombstone and history.
 * @param agent - owning live agent.
 * @param ref - expected current revision.
 * @returns the tombstone ref whose revision is one past the cleared snapshot.
 */
clear(agent: Agent, ref: GoalRef): GoalRef
```

Clear the current goal while retaining a durable tombstone and history.

- `agent` — owning live agent.
- `ref` — expected current revision.

**Returns** the tombstone ref whose revision is one past the cleared snapshot.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/goal/goal/src/index.ts#L296)