@xingular/harness 1.3.1-unstable.9 → 1.5.0-unstable

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CHANGELOG.md +82 -6
  2. package/NOTICE.md +28 -0
  3. package/builtin/skills/plugin-authoring/SKILL.md +20 -1
  4. package/dist/cli.js +911 -335
  5. package/dist/sdk/commands/registry.d.ts +7 -0
  6. package/dist/sdk/commands/registry.js +1 -0
  7. package/dist/sdk/plugins/discover.js +80 -4
  8. package/dist/sdk/plugins/install.js +26 -0
  9. package/dist/sdk/plugins/manifest.d.ts +2 -0
  10. package/dist/sdk/plugins/manifest.js +20 -1
  11. package/dist/sdk/prompt/compile.d.ts +6 -3
  12. package/dist/sdk/prompt/compile.js +12 -24
  13. package/dist/sdk/prompt/reporting.d.ts +2 -0
  14. package/dist/sdk/prompt/reporting.js +72 -0
  15. package/dist/sdk/prompt/standard.d.ts +15 -0
  16. package/dist/sdk/prompt/standard.js +57 -2
  17. package/dist/sdk/sessions/completionCheck.d.ts +11 -11
  18. package/dist/sdk/sessions/completionCheck.js +39 -26
  19. package/dist/sdk/sessions/contracts.d.ts +90 -0
  20. package/dist/sdk/sessions/contracts.js +15 -2
  21. package/dist/sdk/sessions/goal.d.ts +145 -0
  22. package/dist/sdk/sessions/goal.js +405 -0
  23. package/dist/sdk/sessions/goalLoop.d.ts +37 -0
  24. package/dist/sdk/sessions/goalLoop.js +125 -0
  25. package/dist/sdk/sessions/goalPrompts.d.ts +4 -0
  26. package/dist/sdk/sessions/goalPrompts.js +93 -0
  27. package/dist/sdk/sessions/goalStop.d.ts +27 -0
  28. package/dist/sdk/sessions/goalStop.js +41 -0
  29. package/dist/sdk/sessions/runStore.js +1 -0
  30. package/dist/sdk/sessions/runner.d.ts +6 -3
  31. package/dist/sdk/sessions/runner.js +21 -13
  32. package/dist/sdk/sessions/sessions.d.ts +10 -0
  33. package/dist/sdk/sessions/sessions.js +47 -37
  34. package/dist/sdk/sessions/workSlice.d.ts +2 -0
  35. package/dist/sdk/sessions/workSlice.js +2 -2
  36. package/dist/sdk/terminal/piExtension.d.ts +2 -1
  37. package/dist/sdk/terminal/piExtension.js +70 -28
  38. package/dist/sdk/terminal/terminals.js +3 -2
  39. package/dist/sdk/terminal/tui/commands.d.ts +2 -0
  40. package/dist/sdk/terminal/tui/commands.js +3 -0
  41. package/dist/sdk/terminal/tui/goalCommand.d.ts +19 -0
  42. package/dist/sdk/terminal/tui/goalCommand.js +83 -0
  43. package/dist/sdk/terminal/tui/runtime.d.ts +3 -0
  44. package/dist/sdk/terminal/tui/runtime.js +7 -1
  45. package/dist/sdk/tools/askUser.js +1 -1
  46. package/dist/sdk/tools/todo.js +4 -2
  47. package/dist/terminal-opentui.js +902 -274
  48. package/dist/terminal-pi.js +611 -380
  49. package/docs/architecture/02-sessions-and-runs.md +28 -22
  50. package/docs/architecture/04-prompt.md +81 -54
  51. package/docs/architecture/06-plugins-and-capabilities.md +16 -1
  52. package/docs/architecture/07-tools-and-gate.md +7 -4
  53. package/docs/architecture/10-server-protocol.md +14 -6
  54. package/docs/architecture/11-terminal.md +22 -6
  55. package/docs/decisions/ADR-0008-flexible-reporting-guidance.md +3 -0
  56. package/docs/decisions/ADR-0068-scope-and-completion-report.md +5 -2
  57. package/docs/decisions/ADR-0069-stop-gate-and-finish.md +8 -2
  58. package/docs/decisions/ADR-0070-terminal-slice-continuation.md +4 -1
  59. package/docs/decisions/ADR-0071-completion-check.md +3 -2
  60. package/docs/decisions/ADR-0072-codex-prompts-and-goal.md +108 -0
  61. package/docs/decisions/ADR-0073-large-reporting-prompt.md +89 -0
  62. package/docs/decisions/ADR-0074-report-content-not-report-blocks.md +90 -0
  63. package/docs/decisions/ADR-0075-no-todo-gate.md +84 -0
  64. package/docs/decisions/ADR-0076-codex-final-answer-verbatim.md +93 -0
  65. package/docs/parity.md +4 -1
  66. package/docs/releases/1.4.0-unstable.md +25 -0
  67. package/docs/releases/1.5.0-unstable.md +23 -0
  68. package/docs/releases/README.md +1 -1
  69. package/docs/study/00-index.md +7 -0
  70. package/docs/study/STUDY-0004-turn-end-controls.md +9 -0
  71. package/docs/study/STUDY-0005-skill-installation-guidance.md +146 -0
  72. package/docs/study/STUDY-0006-reporting-prompts.md +119 -0
  73. package/docs/study/arms/04-skills.md +6 -0
  74. package/docs/terminal-tui.md +17 -7
  75. package/package.json +1 -1
  76. package/dist/sdk/sessions/stopGate.d.ts +0 -89
  77. package/dist/sdk/sessions/stopGate.js +0 -171
@@ -1,16 +1,15 @@
1
- import type { TodoItem } from "./contracts.js";
2
- export type CheckVerdictKind = 'done' | 'continue' | 'needs_person';
1
+ export type CheckVerdictKind = 'done' | 'continue';
3
2
  export interface CheckVerdict {
4
3
  verdict: CheckVerdictKind;
5
4
  reason: string;
6
5
  /** The next concrete step, for `continue`. */
7
6
  next: string;
8
7
  }
9
- /** What the check sends; kept small so a check costs a fraction of a reply. */
10
- export declare const MAX_CHECK_TRANSCRIPT = 16000;
8
+ /** What the check sends; kept small so a check costs a fraction of a round. */
9
+ export declare const MAX_CHECK_TRANSCRIPT = 24000;
11
10
  export declare const CHECK_TIMEOUT_MS = 60000;
12
11
  /** The fixed instructions of the check. Answering is all it does: it has no tools. */
13
- export declare const CHECK_SYSTEM_PROMPT = "You review whether an AI coding agent may end its reply now. You do not do the work and you have no tools. You read the person's request, the agent's todo list, and a transcript of what the agent did in this reply, and you answer with one JSON object and nothing else:\n\n{\"verdict\":\"done\"|\"continue\"|\"needs_person\",\"reason\":\"one or two sentences\",\"next\":\"the next concrete step, for continue\"}\n\nThe agent works in the person's working folder. Inside it, without asking, the agent may read and change files, run commands and tests, install dependencies, create branches, worktrees and files, choose the order of steps, choose between reasonable implementations, and retry a failed check another way. A document the request points to (a handoff, a plan, a spec) is part of the request: its steps are the work.\n\nAnswer \"continue\" when any part of the request remains that the agent can still do by itself inside those bounds. In particular:\n- The agent asked the person something the request or the files already answer, or asked permission for something inside its bounds (\"should I start with step 1?\", \"create the worktree?\", \"install dependencies?\").\n- The agent marked todo items completed, but its own text or the transcript shows that work is not done or not checked.\n- The agent stopped after a failure it could work around or investigate itself.\n- The agent finished one part of a multi-part request and reported the rest as remaining.\n\nAnswer \"needs_person\" only when the remaining work truly requires the person: a deploy or production change, a secret or credential the agent does not have, writing to remote data, spending money, access the agent lacks, an environment problem only the person can fix, or a product choice the request leaves open with no reasonable default. Name exactly what the person must do.\n\nAnswer \"done\" when the request is fulfilled, when the request was a question and the reply answers it, or when everything the agent could do is done and nothing in the transcript contradicts that.\n\nJudge only from the request, the todo list and the transcript. Keep \"reason\" and \"next\" short and specific.";
12
+ export declare const CHECK_SYSTEM_PROMPT = "You verify whether an AI coding agent has achieved a goal a person gave it. You do not do the work and you have no tools. You read the goal objective and a transcript of what the agent did and said, and you answer with one JSON object and nothing else:\n\n{\"verdict\":\"done\"|\"continue\",\"reason\":\"one or two sentences\",\"next\":\"the next concrete step, for continue\"}\n\nTreat completion as unproven. Derive the concrete requirements from the objective and from any file, plan or spec it points to that the transcript shows. For every explicit requirement, numbered item, named artifact, command, test, gate and deliverable, look in the transcript for evidence that it was achieved and checked: command output, test results, file contents the agent read or wrote. Evidence that is weak, indirect or missing counts as not achieved. The agent saying the goal is complete is not evidence. Match the scope of the check to the scope of the requirement: a narrow check does not support a broad claim.\n\nAnswer \"done\" only when every requirement has evidence in the transcript. Quote the key evidence in \"reason\". Answer \"continue\" when any requirement is unmet, unchecked or unclear; name the unmet requirements in \"reason\" and the next step in \"next\". If the transcript does not contain clear evidence that the objective is met, answer \"continue\" with the reason \"insufficient evidence in transcript\".\n\nJudge only from the objective and the transcript. Keep \"reason\" and \"next\" short and specific.";
14
13
  /**
15
14
  * The reply's transcript: from the person's request onward, clipped to `limit` with the newest
16
15
  * messages kept. The request is found as the last user message that contains its opening text;
@@ -18,7 +17,7 @@ export declare const CHECK_SYSTEM_PROMPT = "You review whether an AI coding agen
18
17
  */
19
18
  export declare function replyTranscript(messages: readonly unknown[], request: string, limit?: number): string;
20
19
  /** The check's user message. */
21
- export declare function checkPrompt(request: string, todo: readonly TodoItem[], transcript: string): string;
20
+ export declare function checkPrompt(objective: string, transcript: string): string;
22
21
  /** The verdict in the check's text, or `null` when there is none: the first JSON object that parses. */
23
22
  export declare function parseVerdict(text: string): CheckVerdict | null;
24
23
  /** A model answer as the check needs it: its text, and what it cost for the run's usage. */
@@ -31,11 +30,10 @@ export interface CheckAnswer {
31
30
  export type CheckModel = (system: string, user: string, signal: AbortSignal) => Promise<CheckAnswer>;
32
31
  /**
33
32
  * Runs one check. Never throws: a timeout, an error or an answer without a verdict returns
34
- * `{ verdict: null }`, and the reply ends as it would have without the check.
33
+ * `{ verdict: null }`, and the claim is accepted as it stands.
35
34
  */
36
35
  export declare function runCompletionCheck(ask: CheckModel, input: {
37
- request: string;
38
- todo: readonly TodoItem[];
36
+ objective: string;
39
37
  messages: readonly unknown[];
40
38
  }, options?: {
41
39
  signal?: AbortSignal;
@@ -47,5 +45,7 @@ export declare function runCompletionCheck(ask: CheckModel, input: {
47
45
  }>;
48
46
  /** The text of a model's answer message. */
49
47
  export declare function answerText(message: unknown): string;
50
- /** `XINGULAR_STOP_GATE=off` / `XINGULAR_COMPLETION_CHECK=off` at launch switch a layer off, for experiments. */
51
- export declare function launchSwitchOff(name: 'XINGULAR_STOP_GATE' | 'XINGULAR_COMPLETION_CHECK'): boolean;
48
+ /** The model a goal-claim check asks: the session's own model, at low effort, through Pi's registry. */
49
+ export declare function sessionCheckModel(ctx: unknown): CheckModel | null;
50
+ /** `XINGULAR_COMPLETION_CHECK=off` at launch accepts every goal claim unchecked, for experiments. */
51
+ export declare function launchSwitchOff(name: 'XINGULAR_COMPLETION_CHECK'): boolean;
@@ -1,27 +1,19 @@
1
- /** What the check sends; kept small so a check costs a fraction of a reply. */
2
- export const MAX_CHECK_TRANSCRIPT = 16_000;
1
+ /** What the check sends; kept small so a check costs a fraction of a round. */
2
+ export const MAX_CHECK_TRANSCRIPT = 24_000;
3
3
  const MAX_TOOL_RESULT = 600;
4
4
  const MAX_TOOL_ARGS = 300;
5
5
  const MAX_TEXT = 2_000;
6
6
  export const CHECK_TIMEOUT_MS = 60_000;
7
7
  /** The fixed instructions of the check. Answering is all it does: it has no tools. */
8
- export const CHECK_SYSTEM_PROMPT = `You review whether an AI coding agent may end its reply now. You do not do the work and you have no tools. You read the person's request, the agent's todo list, and a transcript of what the agent did in this reply, and you answer with one JSON object and nothing else:
8
+ export const CHECK_SYSTEM_PROMPT = `You verify whether an AI coding agent has achieved a goal a person gave it. You do not do the work and you have no tools. You read the goal objective and a transcript of what the agent did and said, and you answer with one JSON object and nothing else:
9
9
 
10
- {"verdict":"done"|"continue"|"needs_person","reason":"one or two sentences","next":"the next concrete step, for continue"}
10
+ {"verdict":"done"|"continue","reason":"one or two sentences","next":"the next concrete step, for continue"}
11
11
 
12
- The agent works in the person's working folder. Inside it, without asking, the agent may read and change files, run commands and tests, install dependencies, create branches, worktrees and files, choose the order of steps, choose between reasonable implementations, and retry a failed check another way. A document the request points to (a handoff, a plan, a spec) is part of the request: its steps are the work.
12
+ Treat completion as unproven. Derive the concrete requirements from the objective and from any file, plan or spec it points to that the transcript shows. For every explicit requirement, numbered item, named artifact, command, test, gate and deliverable, look in the transcript for evidence that it was achieved and checked: command output, test results, file contents the agent read or wrote. Evidence that is weak, indirect or missing counts as not achieved. The agent saying the goal is complete is not evidence. Match the scope of the check to the scope of the requirement: a narrow check does not support a broad claim.
13
13
 
14
- Answer "continue" when any part of the request remains that the agent can still do by itself inside those bounds. In particular:
15
- - The agent asked the person something the request or the files already answer, or asked permission for something inside its bounds ("should I start with step 1?", "create the worktree?", "install dependencies?").
16
- - The agent marked todo items completed, but its own text or the transcript shows that work is not done or not checked.
17
- - The agent stopped after a failure it could work around or investigate itself.
18
- - The agent finished one part of a multi-part request and reported the rest as remaining.
14
+ Answer "done" only when every requirement has evidence in the transcript. Quote the key evidence in "reason". Answer "continue" when any requirement is unmet, unchecked or unclear; name the unmet requirements in "reason" and the next step in "next". If the transcript does not contain clear evidence that the objective is met, answer "continue" with the reason "insufficient evidence in transcript".
19
15
 
20
- Answer "needs_person" only when the remaining work truly requires the person: a deploy or production change, a secret or credential the agent does not have, writing to remote data, spending money, access the agent lacks, an environment problem only the person can fix, or a product choice the request leaves open with no reasonable default. Name exactly what the person must do.
21
-
22
- Answer "done" when the request is fulfilled, when the request was a question and the reply answers it, or when everything the agent could do is done and nothing in the transcript contradicts that.
23
-
24
- Judge only from the request, the todo list and the transcript. Keep "reason" and "next" short and specific.`;
16
+ Judge only from the objective and the transcript. Keep "reason" and "next" short and specific.`;
25
17
  const clip = (text, limit) => (text.length <= limit ? text : `${text.slice(0, limit - 1)}…`);
26
18
  const textOf = (content) => {
27
19
  if (typeof content === 'string')
@@ -32,8 +24,13 @@ const textOf = (content) => {
32
24
  };
33
25
  /** One message as the check reads it: visible text, tool calls and clipped tool results. Thinking is left out. */
34
26
  function renderMessage(message) {
35
- if (message.role === 'user')
36
- return `[User or harness]: ${clip(textOf(message.content), MAX_TEXT)}`;
27
+ if (message.role === 'user') {
28
+ const text = textOf(message.content);
29
+ // The goal's own continuation prompts repeat the same long audit text; the check needs only the objective.
30
+ if (text.startsWith('Continue working toward the active thread goal.'))
31
+ return '';
32
+ return `[User or harness]: ${clip(text, MAX_TEXT)}`;
33
+ }
37
34
  if (message.role === 'toolResult')
38
35
  return `[Tool result${message.toolName ? ` ${message.toolName}` : ''}${message.isError ? ', error' : ''}]: ${clip(textOf(message.content), MAX_TOOL_RESULT)}`;
39
36
  if (message.role === 'assistant') {
@@ -81,12 +78,10 @@ export function replyTranscript(messages, request, limit = MAX_CHECK_TRANSCRIPT)
81
78
  return kept.join('\n');
82
79
  }
83
80
  /** The check's user message. */
84
- export function checkPrompt(request, todo, transcript) {
85
- const list = todo.length ? todo.map((item) => `- [${item.status}] ${item.text}`).join('\n') : '(the agent wrote no todo list)';
81
+ export function checkPrompt(objective, transcript) {
86
82
  return [
87
- `## The person's request\n${clip(request.trim() || '(not recorded)', 4_000)}`,
88
- `## The agent's todo list\n${list}`,
89
- `## What the agent did in this reply\n${transcript || '(nothing recorded)'}`,
83
+ `## The goal's objective\n${clip(objective.trim() || '(not recorded)', 4_000)}`,
84
+ `## What the agent did\n${transcript || '(nothing recorded)'}`,
90
85
  '## Your answer\nOne JSON object: verdict, reason, next.'
91
86
  ].join('\n\n');
92
87
  }
@@ -100,7 +95,7 @@ export function parseVerdict(text) {
100
95
  try {
101
96
  const value = JSON.parse(text.slice(start, end + 1));
102
97
  const verdict = value.verdict;
103
- if (verdict !== 'done' && verdict !== 'continue' && verdict !== 'needs_person')
98
+ if (verdict !== 'done' && verdict !== 'continue')
104
99
  continue;
105
100
  return {
106
101
  verdict,
@@ -117,7 +112,7 @@ export function parseVerdict(text) {
117
112
  }
118
113
  /**
119
114
  * Runs one check. Never throws: a timeout, an error or an answer without a verdict returns
120
- * `{ verdict: null }`, and the reply ends as it would have without the check.
115
+ * `{ verdict: null }`, and the claim is accepted as it stands.
121
116
  */
122
117
  export async function runCompletionCheck(ask, input, options = {}) {
123
118
  const controller = new AbortController();
@@ -125,7 +120,7 @@ export async function runCompletionCheck(ask, input, options = {}) {
125
120
  options.signal?.addEventListener('abort', abort, { once: true });
126
121
  const timer = setTimeout(abort, options.timeoutMs ?? CHECK_TIMEOUT_MS);
127
122
  try {
128
- const user = checkPrompt(input.request, input.todo, replyTranscript(input.messages, input.request));
123
+ const user = checkPrompt(input.objective, replyTranscript(input.messages, ''));
129
124
  const answer = await ask(CHECK_SYSTEM_PROMPT, user, controller.signal);
130
125
  return { verdict: parseVerdict(answer.text), answer };
131
126
  }
@@ -141,7 +136,25 @@ export async function runCompletionCheck(ask, input, options = {}) {
141
136
  export function answerText(message) {
142
137
  return textOf(message?.content);
143
138
  }
144
- /** `XINGULAR_STOP_GATE=off` / `XINGULAR_COMPLETION_CHECK=off` at launch switch a layer off, for experiments. */
139
+ /** The model a goal-claim check asks: the session's own model, at low effort, through Pi's registry. */
140
+ export function sessionCheckModel(ctx) {
141
+ const session = (ctx ?? {});
142
+ const model = session.model;
143
+ const registry = session.modelRegistry;
144
+ if (!model || !registry)
145
+ return null;
146
+ // Some providers (opencode-go) reject a request without a session id.
147
+ const sessionId = session.sessionManager?.getSessionId?.();
148
+ return async (system, user, signal) => {
149
+ const context = { systemPrompt: system, messages: [{ role: 'user', content: user, timestamp: Date.now() }] };
150
+ const message = await registry.streamSimple(model, context, { ...(model.reasoning ? { reasoning: 'low' } : {}), ...(sessionId ? { sessionId } : {}), maxTokens: 4_000, signal }).result();
151
+ const failed = message.stopReason;
152
+ if (failed === 'error' || failed === 'aborted')
153
+ throw new Error(message.errorMessage || `the check request ended: ${failed}`);
154
+ return { text: answerText(message), message };
155
+ };
156
+ }
157
+ /** `XINGULAR_COMPLETION_CHECK=off` at launch accepts every goal claim unchecked, for experiments. */
145
158
  export function launchSwitchOff(name) {
146
159
  const value = process.env[name]?.trim().toLowerCase();
147
160
  return value === 'off' || value === '0' || value === 'false';
@@ -758,6 +758,44 @@ export type RunEvent = z.infer<typeof runEventSchema>;
758
758
  * the harness stores and returns them, and reads only `mode` (`chat` is an agent's own
759
759
  * conversation, `code` is a session in a project).
760
760
  */
761
+ /** A run's /goal as the run record keeps it (ADR-0072). */
762
+ export interface GoalModeRecord {
763
+ goalId: string;
764
+ objective: string;
765
+ status: 'active' | 'paused' | 'blocked' | 'usage_limited' | 'budget_limited' | 'complete';
766
+ limits: {
767
+ rounds: number;
768
+ hours: number;
769
+ };
770
+ rounds: number;
771
+ timeUsedSeconds: number;
772
+ createdAt: number;
773
+ updatedAt: number;
774
+ claimed: boolean;
775
+ lastReason: string;
776
+ }
777
+ export declare const goalModeSchema: z.ZodObject<{
778
+ goalId: z.ZodString;
779
+ objective: z.ZodString;
780
+ status: z.ZodEnum<{
781
+ blocked: "blocked";
782
+ active: "active";
783
+ paused: "paused";
784
+ usage_limited: "usage_limited";
785
+ budget_limited: "budget_limited";
786
+ complete: "complete";
787
+ }>;
788
+ limits: z.ZodObject<{
789
+ rounds: z.ZodNumber;
790
+ hours: z.ZodNumber;
791
+ }, z.core.$strip>;
792
+ rounds: z.ZodNumber;
793
+ timeUsedSeconds: z.ZodNumber;
794
+ createdAt: z.ZodNumber;
795
+ updatedAt: z.ZodNumber;
796
+ claimed: z.ZodBoolean;
797
+ lastReason: z.ZodString;
798
+ }, z.core.$strip>;
761
799
  export interface RunRecord {
762
800
  resumedFromRunId: string | null;
763
801
  /** Opaque run lineage supplied by the embedding application. */
@@ -780,6 +818,8 @@ export interface RunRecord {
780
818
  workspaceRoot?: string | null;
781
819
  worktreeId: string | null;
782
820
  goal: string | null;
821
+ /** The run's /goal (ADR-0072): its objective, status, rounds and time. Absent for a run without one. */
822
+ goalMode?: GoalModeRecord | null;
783
823
  attachmentCount: number;
784
824
  startedAt: string;
785
825
  endedAt: string | null;
@@ -855,6 +895,56 @@ export declare const runRecordSchema: z.ZodObject<{
855
895
  workspaceRoot: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
856
896
  worktreeId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
857
897
  goal: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
898
+ goalMode: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodObject<{
899
+ goalId: z.ZodString;
900
+ objective: z.ZodString;
901
+ status: z.ZodEnum<{
902
+ blocked: "blocked";
903
+ active: "active";
904
+ paused: "paused";
905
+ usage_limited: "usage_limited";
906
+ budget_limited: "budget_limited";
907
+ complete: "complete";
908
+ }>;
909
+ limits: z.ZodObject<{
910
+ rounds: z.ZodNumber;
911
+ hours: z.ZodNumber;
912
+ }, z.core.$strip>;
913
+ rounds: z.ZodNumber;
914
+ timeUsedSeconds: z.ZodNumber;
915
+ createdAt: z.ZodNumber;
916
+ updatedAt: z.ZodNumber;
917
+ claimed: z.ZodBoolean;
918
+ lastReason: z.ZodString;
919
+ }, z.core.$strip>>>, z.ZodTransform<{
920
+ goalId: string;
921
+ objective: string;
922
+ status: "blocked" | "active" | "paused" | "usage_limited" | "budget_limited" | "complete";
923
+ limits: {
924
+ rounds: number;
925
+ hours: number;
926
+ };
927
+ rounds: number;
928
+ timeUsedSeconds: number;
929
+ createdAt: number;
930
+ updatedAt: number;
931
+ claimed: boolean;
932
+ lastReason: string;
933
+ } | null, {
934
+ goalId: string;
935
+ objective: string;
936
+ status: "blocked" | "active" | "paused" | "usage_limited" | "budget_limited" | "complete";
937
+ limits: {
938
+ rounds: number;
939
+ hours: number;
940
+ };
941
+ rounds: number;
942
+ timeUsedSeconds: number;
943
+ createdAt: number;
944
+ updatedAt: number;
945
+ claimed: boolean;
946
+ lastReason: string;
947
+ } | null | undefined>>>;
858
948
  attachmentCount: z.ZodDefault<z.ZodNumber>;
859
949
  startedAt: z.ZodString;
860
950
  endedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
@@ -382,9 +382,9 @@ export const runStopCodeSchema = z.enum([
382
382
  'slice_budget',
383
383
  /** Three compactions in one reply ended it. */
384
384
  'compaction_thrash',
385
- /** The completion check found that the work left needs the person (ADR-0071). */
385
+ /** A goal stopped for the person (ADR-0072). */
386
386
  'needs_person',
387
- /** The reply ended with work left after the stop gate's nudges ran out or produced no work (ADR-0069, ADR-0071). */
387
+ /** A goal stopped on a limit, a pause or a stall with work left (ADR-0072, ADR-0075). */
388
388
  'unfinished',
389
389
  /** The model request failed (auth, quota, rate limit, network, unsupported model). */
390
390
  'provider_error',
@@ -465,6 +465,18 @@ export const runEventSchema = z
465
465
  context.addIssue({ code: 'custom', path: ['payload'], message: `Invalid payload for ${event.type}` });
466
466
  }
467
467
  });
468
+ export const goalModeSchema = z.object({
469
+ goalId: z.string(),
470
+ objective: z.string(),
471
+ status: z.enum(['active', 'paused', 'blocked', 'usage_limited', 'budget_limited', 'complete']),
472
+ limits: z.object({ rounds: z.number().int().positive(), hours: z.number().positive() }),
473
+ rounds: z.number().int().nonnegative(),
474
+ timeUsedSeconds: z.number().nonnegative(),
475
+ createdAt: z.number(),
476
+ updatedAt: z.number(),
477
+ claimed: z.boolean(),
478
+ lastReason: z.string()
479
+ });
468
480
  const text = z.string().nullish().transform((value) => value ?? null);
469
481
  export const runRecordSchema = z.object({
470
482
  resumedFromRunId: text,
@@ -484,6 +496,7 @@ export const runRecordSchema = z.object({
484
496
  workspaceRoot: text.optional(),
485
497
  worktreeId: text,
486
498
  goal: text,
499
+ goalMode: goalModeSchema.nullish().transform((value) => value ?? null).optional(),
487
500
  attachmentCount: z.number().int().nonnegative().default(0),
488
501
  startedAt: z.string(),
489
502
  endedAt: text,
@@ -0,0 +1,145 @@
1
+ import type { ToolSpec } from "../tools/types.js";
2
+ export declare const GET_GOAL = "get_goal";
3
+ export declare const UPDATE_GOAL = "update_goal";
4
+ export declare const GOAL_TOOLS: readonly ["get_goal", "update_goal"];
5
+ export declare const GOAL_CUSTOM_TYPE = "xingular-goal";
6
+ export declare const GOAL_STATE_ENTRY = "xingular-goal-state";
7
+ /** Codex limits a goal objective to this many characters. */
8
+ export declare const MAX_GOAL_OBJECTIVE = 4000;
9
+ export declare const DEFAULT_GOAL_ROUNDS = 30;
10
+ export declare const DEFAULT_GOAL_HOURS = 8;
11
+ /** Consecutive automatic rounds without activity, or with only failed commands, before a goal is blocked. */
12
+ export declare const GOAL_STRIKES = 3;
13
+ export type GoalStatus = 'active' | 'paused' | 'blocked' | 'usage_limited' | 'budget_limited' | 'complete';
14
+ export interface GoalLimits {
15
+ rounds: number;
16
+ hours: number;
17
+ }
18
+ export interface GoalState {
19
+ /** Changes when a goal is replaced, kept when its objective is edited. */
20
+ goalId: string;
21
+ objective: string;
22
+ status: GoalStatus;
23
+ limits: GoalLimits;
24
+ /** Automatic continuations started so far. */
25
+ rounds: number;
26
+ timeUsedSeconds: number;
27
+ createdAt: number;
28
+ updatedAt: number;
29
+ /** The model called update_goal(complete) and the harness has not checked the claim yet. */
30
+ claimed: boolean;
31
+ /** The latest verdict on a completion claim, while it matters. */
32
+ lastReason: string;
33
+ }
34
+ /** Thrown for a call the model may not make; the message goes back to the model as the tool result. */
35
+ export declare class GoalError extends Error {
36
+ }
37
+ export declare const withLimits: (limits?: Partial<GoalLimits>) => GoalLimits;
38
+ /** `59s`, `1m`, `1h 30m`, `2d 23h 42m`: Codex's elapsed-time format. */
39
+ export declare function formatElapsed(seconds: number): string;
40
+ export declare const continuationPrompt: (goal: GoalState) => string;
41
+ export declare const budgetLimitPrompt: (goal: GoalState) => string;
42
+ export declare const objectiveUpdatedPrompt: (goal: GoalState) => string;
43
+ /** The goal as the model's tools report it. */
44
+ export declare function goalReport(goal: GoalState | null): Record<string, unknown>;
45
+ /** The text a goal-aware session shows after it ends in `complete`. */
46
+ export declare const completionReport: (goal: GoalState) => string;
47
+ /** What one finished round did, as the loop saw it. */
48
+ export interface RoundOutcome {
49
+ /** The round produced text, reasoning, or a tool call. */
50
+ activity: boolean;
51
+ /** A command failed and no tool succeeded in the round. */
52
+ failedCommands: boolean;
53
+ /** The round ended with a provider error (not a usage limit). */
54
+ error?: boolean;
55
+ /** The round ended with a usage-limit error. */
56
+ usageLimit?: boolean;
57
+ }
58
+ export interface GoalControllerOptions {
59
+ now?: () => number;
60
+ /** Called after every change with the new state (null once cleared), to persist and show it. */
61
+ onChange?: (state: GoalState | null) => void;
62
+ }
63
+ /**
64
+ * One session's goal. All changes go through it, so the status rules live in one place:
65
+ * the model may only claim `complete`, report `blocked` or, on the person's word, `paused`;
66
+ * the person sets, edits, pauses, resumes and clears; the system alone limits.
67
+ */
68
+ export declare class GoalController {
69
+ private readonly options;
70
+ private state;
71
+ private idleStrikes;
72
+ private failureStrikes;
73
+ private startedAt;
74
+ private readonly now;
75
+ private readonly listeners;
76
+ constructor(options?: GoalControllerOptions);
77
+ get(): GoalState | null;
78
+ active(): boolean;
79
+ /** Restores a persisted goal; the in-memory strike counters start fresh. */
80
+ restore(state: GoalState | null): void;
81
+ /** Hears every change (a persisted copy, the footer, the model's tools). Returns the way to stop. */
82
+ subscribe(listener: (state: GoalState | null) => void): () => void;
83
+ private changed;
84
+ private touch;
85
+ /** The person sets a goal. Replaces a finished one; the caller confirms replacing an unfinished one. */
86
+ set(objective: string, limits?: Partial<GoalLimits>): GoalState;
87
+ /** The person edits the objective: the same goal, its usage kept. A finished goal becomes active again. */
88
+ edit(objective: string): GoalState;
89
+ pause(): GoalState | null;
90
+ resume(): GoalState;
91
+ clear(): boolean;
92
+ /** A round (a turn charged to the goal) begins. */
93
+ beginRound(): void;
94
+ /** Charges the round's wall time to the goal. Called at every stop, so an idle gap is not billed. */
95
+ endRound(): void;
96
+ /** The model's `update_goal`. Returns the tool result. */
97
+ update(status: string): {
98
+ text: string;
99
+ goal: GoalState;
100
+ };
101
+ /** The claim was checked and holds. */
102
+ accept(reason?: string): GoalState;
103
+ /** The claim was checked and does not hold: the goal stays active with the reason. */
104
+ reject(reason: string): GoalState;
105
+ /** The system limits the goal. */
106
+ limit(status: 'budget_limited' | 'usage_limited' | 'blocked', reason?: string): GoalState;
107
+ /** Counts one automatic round; returns the status the system moved the goal to, if any. */
108
+ settleRound(outcome: RoundOutcome): GoalStatus | null;
109
+ /** True once the goal has used its rounds or hours. */
110
+ overLimit(): boolean;
111
+ /** Starts the next automatic round. */
112
+ nextRound(): GoalState;
113
+ }
114
+ export declare function goalTools(goal: () => GoalController | null): ToolSpec[];
115
+ export type GoalCommand = {
116
+ kind: 'show';
117
+ } | {
118
+ kind: 'set';
119
+ objective: string;
120
+ limits: Partial<GoalLimits>;
121
+ } | {
122
+ kind: 'edit';
123
+ objective: string | null;
124
+ } | {
125
+ kind: 'pause';
126
+ } | {
127
+ kind: 'resume';
128
+ } | {
129
+ kind: 'clear';
130
+ } | {
131
+ kind: 'error';
132
+ message: string;
133
+ };
134
+ export declare const GOAL_USAGE = "Usage: /goal [<objective>|edit|pause|resume|clear]";
135
+ /**
136
+ * Parses the argument of `/goal`. Subcommands match only as the whole text, so "pause now" is
137
+ * an objective. `--rounds N` and `--hours H` before the objective set this goal's caps.
138
+ */
139
+ export declare function parseGoalCommand(argument: string): GoalCommand;
140
+ /** The text of a bare `/goal`. */
141
+ export declare function goalSummary(goal: GoalState | null): string;
142
+ /** The footer label (Codex's wording, with rounds in place of tokens). */
143
+ export declare function goalFooter(goal: GoalState | null): string | null;
144
+ /** The hidden message that records who changed the goal, so a pause can be checked as the person's. */
145
+ export declare function provenanceText(action: 'set' | 'paused' | 'cleared' | 'resumed' | 'edited', goal: GoalState | null): string;