7.9 KiB
ctx.goals
GoalService — provided by @deepseek-ai/dsh-goal.
Goal service (ctx.goals) backed exclusively by the owning session log.
ctx.goals.resolveCreate(request)
/**
* Materialize deployment defaults and validate one create request.
* @param request - objective plus optional caller-selected round cap.
* @returns detached, fully resolved create specification.
*/
resolveCreate(request: CreateGoalRequest): CreateGoalSpec
Materialize deployment defaults and validate one create request.
request— objective plus optional caller-selected round cap.
Returns detached, fully resolved create specification.
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.
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.
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.
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.
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.
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.
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.
ctx.goals.block(agent, ref)
/**
* Mark an active goal blocked and disarm it.
* @param agent - owning live agent.
* @param ref - expected current revision.
* @returns the blocked view.
*/
block(agent: Agent, ref: GoalRef): GoalView
Mark an active goal blocked and disarm it.
agent— owning live agent.ref— expected current revision.
Returns the blocked view.
ctx.goals.markUsageLimited(agent, ref)
/**
* Mark an active goal stopped by an external usage limit.
* @param agent - owning live agent.
* @param ref - expected current revision.
* @returns the usage-limited view.
*/
markUsageLimited(agent: Agent, ref: GoalRef): GoalView
Mark an active goal stopped by an external usage limit.
agent— owning live agent.ref— expected current revision.
Returns the usage-limited view.
ctx.goals.markBudgetLimited(agent, ref)
/**
* Mark an active goal stopped at its configured round cap.
* @param agent - owning live agent.
* @param ref - expected current revision.
* @returns the budget-limited view.
*/
markBudgetLimited(agent: Agent, ref: GoalRef): GoalView
Mark an active goal stopped at its configured round cap.
agent— owning live agent.ref— expected current revision.
Returns the budget-limited view.
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.