deepseek-harness/website/zh-CN/api/harness/goals.md

ctx.goals

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

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

Source

ctx.goals.get(agent)

/**
 * 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

ctx.goals.disarm(agent)

/**
 * Remove process-local continuation authority without changing durable goal
 * phase or revision. Lifecycle owners use this before unloading a driver;
 * a later human-authorized {@link resume} records the new activation edge.
 * @param agent - owning live agent.
 * @returns a fresh disarmed view, or `undefined` when no goal is current.
 */
disarm(agent: Agent): GoalView | undefined

Remove process-local continuation authority without changing durable goal phase or revision. Lifecycle owners use this before unloading a driver; a later human-authorized resume records the new activation edge.

• agent — owning live agent.

Returns a fresh disarmed view, or undefined when no goal is current.

Source

ctx.goals.create(agent, request)

/**
 * 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

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

/**
 * 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

ctx.goals.pause(agent, ref)

/**
 * 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

ctx.goals.resume(agent, ref)

/**
 * 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

ctx.goals.complete(agent, ref)

/**
 * 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

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

/**
 * 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

ctx.goals.clear(agent, ref)

/**
 * 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