import { JudgeConfig } from "std/agent/options_types"
// Goal object: a typed, long-running objective the agent converges on. A goal
// bundles an `objective`, machine-checkable `success_criteria`, `constraints`,
// and a `budget`. It renders into the outbound prompt through the existing
// per-turn context-profile fragment harness.runtime.channel(#2631) — NO new hook surface —
// composes a turn-end-judge via the core `turn_end_condition` agent_loop seam
// (`std/agent/judge`), and re-loops on "not yet met" by reusing agent_loop's own
// bounded completion loop (`verify_completion` veto -> feedback -> re-run),
// never a hand-written loop. Generalizes the legacy `session_goal` +
// `goal-judge`
// (design-only there; built here).
import { pin } from "std/agent/pins"
import { __with_prompt_fragment } from "std/agent/preflight"
import { system_prompt_part } from "std/llm/prompts"
// Bounded re-loop cap: if the goal is not met at loop end, re-enter with
// findings at most this many times before stopping honestly. Mirrors the
// legacy policy's
// GOAL_JUDGE_MAX_RELOOPS.
const __GOAL_MAX_RELOOPS = 3
// Default done_sentinel for goal_reloop: the completion signal the agent emits
// to claim it is finished. Each emission triggers a `verify_completion` check;
// an unmet goal vetoes it and drives another bounded attempt.
const __GOAL_DONE_MARKER = "<<GOAL-DONE>>"
/**
* A `check` may be an anonymous closure or a named `fn`; the runtime reports
* these as "closure", "function", or "fn" (mirrors std/agent/loop callable
* detection). Gating on "closure" alone silently skips named-fn criteria.
*/
fn __goal_callable(value: any) {
const kind = type_of(value)
return kind == "closure" || kind == "function" || kind == "fn"
}
/**
* A single success criterion. `description` is the human/LLM-checkable statement;
* `check` is an OPTIONAL host-fact callback `(facts) -> bool` that makes the
* criterion machine-checkable (deterministic floor) instead of LLM-judged.
*/
pub type GoalCriterion = {id?: string, description: string, check?: any}
/**
* GoalSpec is the normalized shape returned by `goal(spec)`. `retired_criteria`
* is set only by `goal_under_obligations`: the criteria an operator retarget
* retired, kept so a reader can tell them from criteria that were met.
*/
pub type GoalSpec = {
objective: string,
success_criteria?: list<GoalCriterion>,
constraints?: list<string>,
budget?: dict,
retired_criteria?: list<GoalCriterion>,
}
pub type GoalJudgeOptions = {
model?: string,
provider?: string,
max_invocations?: int,
feedback_fallback?: string,
}
fn __string_list(value: list?) {
if type_of(value) != "list" {
return []
}
let out = []
for item in value {
out = out.appending(to_string(item))
}
return out
}
fn __normalize_criteria(value: list?) {
if type_of(value) != "list" {
return []
}
let out = []
let index = 0
for raw in value {
const entry = if type_of(raw) == "dict" {
raw
} else {
{description: to_string(raw)}
}
const description = to_string(entry?.description ?? "")
if description == "" {
throw "goal: each success criterion needs a non-empty description"
}
// A `check` that is set but not callable is silently ignored by `goal_check`
// (it gates on `__goal_callable`), quietly dropping the deterministic floor for
// that criterion. Fail loudly at config time instead.
if entry?.check != nil && !__goal_callable(entry.check) {
throw "goal: success criterion `" + description
+ "` has a `check` that must be a callable or nil; got "
+ type_of(entry.check)
}
out = out.appending(
{check: entry?.check, description: description, id: entry?.id ?? ("sc_" + to_string(index))},
)
index = index + 1
}
return out
}
/**
* goal(spec) validates and normalizes a GoalSpec. `spec.objective` is required
* and non-empty. `success_criteria` may be strings or `{description, check?}`
* dicts; `constraints` is a list of strings; `budget` is a free dict.
*
* @effects: []
* @errors: [runtime]
* @api_stability: stable
* @example: goal({objective: "Fix the flaky test", success_criteria: ["suite green twice"]})
*/
pub fn goal(spec: dict) {
if type_of(spec) != "dict" {
throw "goal(spec): spec must be a dict"
}
const objective = to_string(spec?.objective ?? "")
if objective == "" {
throw "goal(spec): spec.objective is required and must be non-empty"
}
return {
budget: if type_of(spec?.budget) == "dict" {
spec.budget
} else {
{}
},
constraints: __string_list(spec?.constraints),
objective: objective,
success_criteria: __normalize_criteria(spec?.success_criteria),
}
}
fn __render_goal_text(g: any) {
let lines = ["## Goal", "Objective: " + g.objective]
if len(g.success_criteria) > 0 {
lines = lines.appending("Success criteria:")
for crit in g.success_criteria {
lines = lines.appending("- " + crit.description)
}
}
const retired = g.retired_criteria ?? []
if len(retired) > 0 {
lines = lines.appending("Retired by the operator's retarget (no longer owed, not met):")
for crit in retired {
lines = lines.appending("- " + crit.description)
}
}
if len(g.constraints) > 0 {
lines = lines.appending("Constraints:")
for c in g.constraints {
lines = lines.appending("- " + c)
}
}
if len(g.budget.keys()) > 0 {
lines = lines.appending("Budget: " + json_stringify(g.budget))
}
return join(lines, "\n")
}
/**
* goal_text(goal) renders the goal into its canonical prompt block. Exposed for
* callers that assemble prompts by hand.
*
* @effects: []
* @errors: []
* @api_stability: stable
*/
pub fn goal_text(g: dict) {
return __render_goal_text(g)
}
/**
* goal_prompt_part(goal) returns an `llm::prompt` reducer system-prompt part
* (position "before") rendering the goal. Feed it through
* `with_system_fragments` for direct `llm_call` callers; for `agent_loop` use
* `with_goal(...)`, which routes through the context-profile fragment channel
* the loop assembles per turn.
*
* @effects: []
* @errors: []
* @api_stability: stable
*/
pub fn goal_prompt_part(g: dict) {
return system_prompt_part(__render_goal_text(g), {label: "goal", position: "before"})
}
/**
* goal_context_fragment(goal) returns the goal as a context-profile prompt
* fragment (`{body, id, source}`) — the channel `agent_loop` folds into its
* per-turn system prompt (preflight `context_profile.prompt_fragments`).
*
* @effects: []
* @errors: []
* @api_stability: stable
*/
pub fn goal_context_fragment(g: dict) {
return {body: __render_goal_text(g), id: "goal", source: "goal"}
}
/**
* with_goal(agent_options, goal) renders the goal into the agent_loop options so
* the objective/criteria/constraints appear in every outbound request, using the
* existing `context_profile.prompt_fragments` harness.runtime.channel(the same per-turn
* fragment reducer, #2631) — preserving any fragments/profile the caller already
* set. No new hook surface.
*
* @effects: []
* @errors: []
* @api_stability: stable
* @example: agent_loop(harness, task, nil, with_goal({provider: "anthropic"}, g))
*/
pub fn with_goal(agent_options: any, g: GoalSpec) {
return __with_prompt_fragment(agent_options, goal_context_fragment(g))
}
/**
* goal_pin(harness, goal) returns a self-replacing `goal`-kind PinSpec carrying the
* rendered goal, so the goal survives compaction as a pin.
*
* @effects: []
* @errors: []
* @api_stability: stable
*/
pub fn goal_pin(random: HarnessRandom, g: dict) {
return pin(random, "goal", __render_goal_text(g), {dedupe_key: "pin/goal"})
}
/**
* goal_under_obligations(goal, obligations?) returns the goal as a run's
* completion obligations leave it. An accepted steer that retargeted the run
* (`obligations.retarget`, read from the recorded control row) replaces the
* objective, and every success criterion set under the previous objective moves
* to `retired_criteria`: no longer owed, and not met either. Constraints and
* budget stand. Without a retarget the goal is returned unchanged.
*
* @effects: []
* @errors: []
* @api_stability: experimental
* @example: goal_under_obligations(g, payload?.obligations)
*/
pub fn goal_under_obligations(g: GoalSpec, obligations: any = nil) -> GoalSpec {
const objective = trim(to_string(obligations?.retarget?.objective ?? ""))
if objective == "" {
return g
}
return g
+ {
objective: objective,
success_criteria: [],
retired_criteria: (g.retired_criteria ?? []) + (g.success_criteria ?? []),
}
}
/**
* goal_check(goal, facts?) evaluates the machine-checkable success criteria
* (those carrying a `check` host-fact callback) against `facts`. Returns
* `{checkable, done, met, unmet}` where `met`/`unmet` are criterion ids and
* `done` is true when no checkable criterion is unmet. Criteria without a
* `check` are LLM-judged (see `goal_judge`) and excluded from this floor.
*
* @effects: []
* @errors: []
* @api_stability: stable
*/
pub fn goal_check(g: GoalSpec, facts: any = nil) {
const bindings = if type_of(facts) == "dict" {
facts
} else {
{}
}
let met = []
let unmet = []
for crit in g.success_criteria {
if __goal_callable(crit?.check) {
if crit.check(bindings) {
met = met.appending(crit.id)
} else {
unmet = unmet.appending(crit.id)
}
}
}
return {checkable: len(met) + len(unmet), done: len(unmet) == 0, met: met, unmet: unmet}
}
fn __goal_judge_system(g: any) {
let lines = [
"You are the goal completion judge. Decide whether the stated goal is fully met by the work so far.",
"Return `action: \"accept\"` only if every success criterion is satisfied. Otherwise return `action: \"continue\"` with one concrete repair and the remaining specific gaps.",
"",
__render_goal_text(g),
]
return join(lines, "\n")
}
/**
* goal_judge(goal, opts?) returns a `turn_end_condition` JudgeConfig (see
* `std/agent/judge`) whose system prompt embeds the goal. Spread it into
* agent_loop options as `turn_end_condition:` — it composes with the existing
* `agent_evaluate_completion` turn-end-judge seam (the semantic ceiling). Pair with
* `goal_check` host-fact callbacks for the deterministic floor. `opts` may carry
* `model`, `provider`, and `max_invocations`. Completion judges always fail
* closed when their model call is unavailable or invalid.
*
* @effects: []
* @errors: []
* @api_stability: stable
* @example: agent_loop(harness, task, nil, {turn_end_condition: goal_judge(g), loop_until_done: true})
*/
pub fn goal_judge(g: GoalSpec, opts: GoalJudgeOptions? = nil) -> JudgeConfig {
const o = opts ?? {}
let config: JudgeConfig = {
feedback_fallback: o?.feedback_fallback
?? "The goal is not yet met; keep working toward the success criteria.",
max_invocations: o?.max_invocations ?? __GOAL_MAX_RELOOPS,
system: __goal_judge_system(g),
}
if o?.model != nil {
config.model = o.model
}
if o?.provider != nil {
config.provider = o.provider
}
return config
}
/**
* Feedback that threads the unmet success criteria (the findings) into the next
* attempt. agent_evaluate_completion injects this into the transcript on a vetoed
* completion, so the re-run agent sees exactly which criteria remain.
*/
fn __goal_unmet_feedback(g: GoalSpec, unmet_ids: string | list) {
let lines = ["The goal is not yet met. Address these unmet success criteria before finishing:"]
let any = false
for crit in g.success_criteria {
if contains(unmet_ids, crit.id) {
lines = lines.appending("- " + crit.description)
any = true
}
}
if !any {
lines = lines.appending("- " + g.objective)
}
return join(lines, "\n")
}
// Reloop-only control keys that must NOT leak into the agent_loop options.
const __GOAL_RELOOP_CONTROL_KEYS = ["done_sentinel", "facts_fn", "judge", "max_attempts"]
/**
* goal_reloop(goal, opts?) returns agent_loop options that drive a BOUNDED
* re-loop over the goal using agent_loop's OWN completion loop — NOT a
* hand-written loop, and NOT the workflow stage tier (a producing stage cannot
* re-run the agent on a verify gate on current main; a `kind:"verify"` stage
* evaluates its gate once and terminates without re-running the producer). Each
* completion attempt is gated by `verify_completion`, which runs `goal_check`
* against the facts `opts.facts_fn(payload)` extracts; an unmet goal vetoes the
* completion, threads the unmet criteria (the findings) into the transcript as
* feedback, and the agent re-runs — up to `opts.max_attempts` (default 3) times
* (the iteration bound). Spread the result into
* `agent_loop(harness, task, nil, goal_reloop(g, opts))`.
*
* `opts`: `facts_fn` (`(payload) -> facts` dict for `goal_check`; required for
* machine-checkable convergence), `max_attempts`, `done_sentinel` (the
* completion signal that triggers each gate check), `judge` (set true to also
* compose the semantic `goal_judge` ceiling), plus any agent_loop options to
* pass through (caller wins). The goal renders into the system prompt via the
* existing context-profile fragment channel.
*
* @effects: []
* @errors: [runtime]
* @api_stability: stable
* @example: agent_loop(harness, task, nil, goal_reloop(g, {facts_fn: read_facts, max_attempts: 3}))
*/
pub fn goal_reloop(g: any, opts: any = nil) {
const o = if type_of(opts) == "dict" {
opts
} else {
{}
}
const max_attempts = o?.max_attempts ?? __GOAL_MAX_RELOOPS
const facts_fn = o?.facts_fn
// A `facts_fn` that is set but not callable is silently ignored below (the
// `__goal_callable` gate falls back to empty facts), so the machine-checkable
// convergence quietly evaporates. Fail loudly at config time instead — mirroring
// the criterion `check` validation in `__normalize_criteria`.
if facts_fn != nil && !__goal_callable(facts_fn) {
throw "goal_reloop: `facts_fn` must be a callable or nil; got " + type_of(facts_fn)
}
const verify_completion = { payload ->
// Held to the goal as accepted steering left it: a retarget retires the
// frozen criteria, and the reminder names the objective now in force.
const current = goal_under_obligations(g, payload?.obligations)
const facts = if __goal_callable(facts_fn) {
facts_fn(payload)
} else {
{}
}
const check = goal_check(current, facts)
if check.done {
return {confirm: true}
}
return {confirm: false, feedback: __goal_unmet_feedback(current, check.unmet)}
}
let base = {
done_sentinel: o?.done_sentinel ?? __GOAL_DONE_MARKER,
loop_until_done: true,
max_iterations: max_attempts,
verify_completion: verify_completion,
}
if o?.judge == true {
base = base + {turn_end_condition: goal_judge(g, o)}
}
return with_goal(base + __dict_omit(o, __GOAL_RELOOP_CONTROL_KEYS), g)
}