@capagents/forgeqe 1.1.0 → 1.1.2

package/src/refine.ts

@@ -10,6 +10,7 @@ import { CAPABILITIES } from "./capabilities/registry.ts"
 import { allStatuses } from "./capabilities/status.ts"
 import { domainNotes } from "./domain.ts"
 import type { CodeEvent } from "./types.ts"
+import { steScore } from "./ste.ts"
 
 /**
  * The shell's Refine (ctrl+r): what the user typed becomes a precise request for ForgeQE's agent, checked against what
@@ -20,13 +21,18 @@ import type { CodeEvent } from "./types.ts"
 /** The only tools the refiner may call: each reads, none changes anything or starts a run. */
 export const REFINE_TOOLS = ["capabilities", "query_api", "find_test_cases", "list_sprints", "run_details"]
 
-/** The refined request as a task specification: what ForgeQE's agent is asked to do, in the parts its own prompt uses. */
-export type RefinedSpec = { goal: string; context: string[]; steps: string[]; rules: string[]; result: string }
+/**
+ * The refined request as a task specification, laid out as a system prompt: the role the agent takes, the objective,
+ * the context, the steps, the rules, the output format, and the objective again in one sentence at the end.
+ */
+export type RefinedSpec = { role: string; objective: string; context: string[]; steps: string[]; rules: string[]; output: string; summary: string }
 
 export type Refined = {
-  /** The request that is sent: the spec written out (Goal, Context, Steps, Rules, Result). */
+  /** The request that is sent: the spec written out (Role, Objective, Context, Steps, Rules, Output format, Summary). */
   refined: string
   spec?: RefinedSpec
+  /** The share of the request's sentences that keep the ASD-STE100 rules, 0 to 1. */
+  ste?: number
   grounded: { fact: string; checked: boolean }[]
   assumed: string[]
   missing: string[]
@@ -37,11 +43,13 @@ const lines = { type: "array", items: { type: "string" } } as const
 export const REFINE_SCHEMA = {
   type: "object",
   properties: {
-    goal: { type: "string", description: "One instruction that starts with a verb: what the agent must do" },
+    role: { type: "string", description: "The role the agent takes for this task, as one description, e.g. A release analyst who reads Azure DevOps deployments" },
+    objective: { type: "string", description: "One instruction that starts with a verb: what the agent must do" },
     context: { ...lines, description: "Facts the agent needs, one per line: system, project, work items, files, runs, with exact names and ids" },
     steps: { ...lines, description: "The actions in sequence, one per step; empty for a request with one action" },
     rules: { ...lines, description: "Limits the user gave or the setup sets, one per line" },
-    result: { type: "string", description: "What the agent must give back" },
+    output: { type: "string", description: "The output format: what the agent gives back and how it is laid out (sections, a table, a file)" },
+    summary: { type: "string", description: "The objective again, in one short sentence, as the last line" },
     grounded: {
       type: "array",
       items: { type: "object", properties: { fact: { type: "string" }, checked: { type: "boolean" } }, required: ["fact", "checked"] },
@@ -49,7 +57,7 @@ export const REFINE_SCHEMA = {
     assumed: { type: "array", items: { type: "string" } },
     missing: { type: "array", items: { type: "string" } },
   },
-  required: ["goal", "context", "steps", "rules", "result", "grounded", "assumed", "missing"],
+  required: ["role", "objective", "context", "steps", "rules", "output", "summary", "grounded", "assumed", "missing"],
 } as const
 
 const REFINE_AGENT = {
@@ -64,11 +72,14 @@ const REFINE_AGENT = {
 
 /** The spec as the request ForgeQE's agent gets: labelled parts, empty ones left out. */
 export function composeRefined(spec: RefinedSpec): string {
-  const parts = [`Goal: ${spec.goal}`]
+  const parts: string[] = []
+  if (spec.role) parts.push(`Role: ${spec.role}`)
+  parts.push(`Objective: ${spec.objective}`)
   if (spec.context.length) parts.push(["Context:", ...spec.context.map((c) => `- ${c}`)].join("\n"))
   if (spec.steps.length) parts.push(["Steps:", ...spec.steps.map((st, i) => `${i + 1}. ${st}`)].join("\n"))
   if (spec.rules.length) parts.push(["Rules:", ...spec.rules.map((r) => `- ${r}`)].join("\n"))
-  if (spec.result) parts.push(`Result: ${spec.result}`)
+  if (spec.output) parts.push(`Output format: ${spec.output}`)
+  if (spec.summary) parts.push(`Summary: ${spec.summary}`)
   return parts.join("\n\n")
 }
 
@@ -97,13 +108,18 @@ export function refineRequest(text: string, recent: { user: string; reply: strin
 }
 
 /** Keeps only what the schema allows, so the shell never shows a malformed answer. */
-export function cleanRefined(r: (Partial<Refined> & Partial<RefinedSpec>) | null | undefined, original: string): Refined {
+export function cleanRefined(r: (Partial<Refined> & Partial<RefinedSpec> & { goal?: string; result?: string }) | null | undefined, original: string): Refined {
   const strings = (v: unknown) => (Array.isArray(v) ? v.map(String).map((s) => s.trim()).filter(Boolean) : [])
-  const goal = String(r?.goal || "").trim()
-  const spec: RefinedSpec | undefined = goal ? { goal, context: strings(r?.context), steps: strings(r?.steps), rules: strings(r?.rules), result: String(r?.result || "").trim() } : undefined
+  const text = (v: unknown) => String(v || "").trim()
+  // goal and result: the names an older refine prompt (a project's own copy) gives the objective and the output.
+  const objective = text(r?.objective) || text(r?.goal)
+  const spec: RefinedSpec | undefined = objective
+    ? { role: text(r?.role), objective, context: strings(r?.context), steps: strings(r?.steps), rules: strings(r?.rules), output: text(r?.output) || text(r?.result), summary: text(r?.summary) }
+    : undefined
+  const refined = spec ? composeRefined(spec) : text(r?.refined) || original
   return {
-    refined: spec ? composeRefined(spec) : String(r?.refined || "").trim() || original,
-    ...(spec ? { spec } : {}),
+    refined,
+    ...(spec ? { spec, ste: steScore(refined).score } : {}),
     grounded: Array.isArray(r?.grounded) ? r!.grounded.filter((g) => g && String(g.fact || "").trim()).map((g) => ({ fact: String(g.fact).trim(), checked: g.checked === true })) : [],
     assumed: strings(r?.assumed),
     missing: strings(r?.missing),
@@ -150,7 +166,7 @@ export async function refine(opts: {
     })
     try {
       let out = await session.prompt(refineRequest(opts.text, opts.recent))
-      if (!out.report && !out.error && !opts.signal?.aborted) out = await session.prompt("Give the structured result: goal, context, steps, rules, result, grounded, assumed, and missing.")
+      if (!out.report && !out.error && !opts.signal?.aborted) out = await session.prompt("Give the structured result: role, objective, context, steps, rules, output, summary, grounded, assumed, and missing.")
       if (!out.report) throw new Error(out.error ? `Refine failed: ${out.error}` : "Refine gave no result.")
       return cleanRefined(out.report, opts.text)
     } finally {

package/src/run.ts

@@ -216,6 +216,7 @@ export async function executeRun(opts: ExecuteOptions): Promise<{ result: RunRes
       headed: Boolean(opts.headed) || !opts.config.browser.headless,
       maxSteps,
       allowedHosts: allowed,
+      browser: { provider: opts.config.browser.provider, remote: opts.config.browser.remote },
       extendSystemMessage: extend || undefined,
       memory,
       env,

package/src/ste.ts

@@ -91,8 +91,13 @@ export function countWords(text: string): number {
   return (collapse(text).match(/[A-Za-z0-9][\w'’./-]*/g) || []).length
 }
 
+/** "You MUST", "The agent SHOULD NOT": the RFC 2119 key word that makes a sentence a rule, with its subject. */
+export const RFC_LEAD = /^(([Yy]ou|[Tt]he agent|[Tt]he reply|[Ee]ach \w+|[Ee]very \w+)\s+)?(MUST NOT|MUST|SHOULD NOT|SHOULD|MAY|SHALL NOT|SHALL)\s+/
+
 export function isInstruction(sentence: string): boolean {
-  const s = collapse(sentence).replace(/^[\s>*_-]+/, "").replace(LEAD, "")
+  const lead = collapse(sentence).replace(/^[\s>*_-]+/, "").replace(LEAD, "")
+  // "You MUST run the tests." is an instruction: the verb after the key word decides, as without it.
+  const s = RFC_LEAD.test(lead) ? lead.replace(RFC_LEAD, "") : lead
   const first = (s.match(/^[A-Za-z']+/)?.[0] || "").toLowerCase()
   return VERBS.has(first)
 }
@@ -151,7 +156,8 @@ function splitSentences(text: string): string[] {
 }
 
 export function checkSentence(text: string): SteSentence {
-  const words = countWords(text)
+  // The subject and RFC 2119 key word of a rule ("You MUST NOT") do not count toward its length.
+  const words = countWords(text) - countWords(collapse(text).replace(/^[\s>*_-]+/, "").replace(LEAD, "").match(RFC_LEAD)?.[0] || "")
   const instruction = isInstruction(text)
   const issues: SteSentence["issues"] = []
   const limit = instruction ? 20 : 25

package/src/tui/App.tsx

@@ -519,6 +519,7 @@ export function App({ options }: { options: TuiOptions }) {
   }
 
   /** Refines what is in the prompt; the user then decides what is sent. */
+  const refineCount = useRef(0)
   const startRefine = () => {
     const text = promptTextRef.current.trim()
     const cfg = configRef.current
@@ -534,10 +535,19 @@ export function App({ options }: { options: TuiOptions }) {
     const controller = new AbortController()
     refineAbort.current = controller
     setRefine({ phase: "working", original: text })
-    void (options.refine || refine)({ config: cfg, cwd: sessionSetup(cfg, options.repo).cwd, text, recent: convoRef.current, signal: controller.signal })
+    // Refine is a model session of its own: its tokens count in the session total, under a key per refine.
+    const key = `refine-${++refineCount.current}`
+    const started = Date.now()
+    let used = 0
+    const onEvent = (e: CodeEvent) => {
+      if (e.kind !== "usage") return
+      used = e.usage.input + e.usage.output
+      useTokens(key, used)
+    }
+    void (options.refine || refine)({ config: cfg, cwd: sessionSetup(cfg, options.repo).cwd, text, recent: convoRef.current, signal: controller.signal, onEvent })
       .then((result) => {
         if (controller.signal.aborted || refiningRef.current?.phase !== "working") return
-        setRefine({ phase: "done", original: text, result, choice: initialChoice(result.missing) })
+        setRefine({ phase: "done", original: text, result, choice: initialChoice(result.missing), ...(used ? { tokens: used } : {}), ms: Date.now() - started })
       })
       .catch((err) => {
         if (controller.signal.aborted) return
@@ -914,6 +924,10 @@ export function App({ options }: { options: TuiOptions }) {
       case "info":
         push(e.ok === undefined ? "code" : e.ok ? "ok" : "err", e.text)
         return
+      case "call":
+        pushTool(e.text, e.ok)
+        if (!aborted()) setActivity(`Agent: ${clip(e.text, 60)}`)
+        return
       case "agent": {
         const ev = e.event
         inspect(ev)

package/src/tui/refine-panel.tsx

@@ -1,11 +1,12 @@
 import type { Refined } from "../refine.ts"
 import { Spinner } from "./components.tsx"
-import { theme } from "./theme.ts"
+import { formatDuration, formatTokens, theme } from "./theme.ts"
 
 /** Refine's panel, in the prompt's place: working, the result with what was checked, or why it could not refine. */
 export type RefineState =
   | { phase: "working"; original: string }
-  | { phase: "done"; original: string; result: Refined; choice: number }
+  /** `tokens` and `ms`: what Refine's own model session cost, shown in the title. */
+  | { phase: "done"; original: string; result: Refined; choice: number; tokens?: number; ms?: number }
   | { phase: "error"; original: string; message: string }
 
 export const REFINE_CHOICES = [
@@ -28,7 +29,10 @@ export function initialChoice(missing: string[]): number {
 
 export function RefinePanel(props: { state: RefineState; width: number; onChoose: (id: RefineChoice) => void; onHover: (i: number) => void }) {
   const { state, width } = props
-  const title = state.phase === "working" ? " ✦ Refining " : state.phase === "error" ? " ✦ Could not refine " : " ✦ Refined request "
+  const cost = state.phase === "done" && state.tokens ? ` · ${formatTokens(state.tokens)} tokens${state.ms ? ` · ${formatDuration(state.ms)}` : ""}` : ""
+  // How much of the request keeps the ASD-STE100 rules, as Refine's prompt asks.
+  const ste = state.phase === "done" && state.result.ste !== undefined ? ` · STE ${Math.round(state.result.ste * 100)}%` : ""
+  const title = state.phase === "working" ? " ✦ Refining " : state.phase === "error" ? " ✦ Could not refine " : ` ✦ Refined request${ste}${cost} `
   // Facts Refine checked that are also context lines are marked there, not repeated under Checked.
   const contextLines = state.phase === "done" ? state.result.refined.split("\n").filter((l) => l.startsWith("- ")).map((l) => norm(l.slice(2))) : []
   const inContext = new Set(contextLines)
@@ -61,9 +65,9 @@ export function RefinePanel(props: { state: RefineState; width: number; onChoose
           <text fg={theme.err}>{state.message}</text>
         ) : (
           <>
-            {/* The request as it is sent: its labelled parts (Goal, Context, Steps, Rules, Result) stand out. */}
+            {/* The request as it is sent: its labelled parts (Role, Objective, Context, Steps, Rules, Output format, Summary) stand out. */}
             {state.result.refined.split("\n").map((line, i) => {
-              const label = /^(Goal|Context|Steps|Rules|Result):/.exec(line)
+              const label = /^(Role|Objective|Context|Steps|Rules|Output format|Summary|Goal|Result):/.exec(line)
               // A context line Refine checked against the systems: ✓ in place of its dash, so it is not listed twice.
               if (line.startsWith("- ") && checked.has(norm(line.slice(2)))) {
                 return (