@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.
- package/CHANGELOG.md +82 -6
- package/NOTICE.md +28 -0
- package/builtin/skills/plugin-authoring/SKILL.md +20 -1
- package/dist/cli.js +911 -335
- package/dist/sdk/commands/registry.d.ts +7 -0
- package/dist/sdk/commands/registry.js +1 -0
- package/dist/sdk/plugins/discover.js +80 -4
- package/dist/sdk/plugins/install.js +26 -0
- package/dist/sdk/plugins/manifest.d.ts +2 -0
- package/dist/sdk/plugins/manifest.js +20 -1
- package/dist/sdk/prompt/compile.d.ts +6 -3
- package/dist/sdk/prompt/compile.js +12 -24
- package/dist/sdk/prompt/reporting.d.ts +2 -0
- package/dist/sdk/prompt/reporting.js +72 -0
- package/dist/sdk/prompt/standard.d.ts +15 -0
- package/dist/sdk/prompt/standard.js +57 -2
- package/dist/sdk/sessions/completionCheck.d.ts +11 -11
- package/dist/sdk/sessions/completionCheck.js +39 -26
- package/dist/sdk/sessions/contracts.d.ts +90 -0
- package/dist/sdk/sessions/contracts.js +15 -2
- package/dist/sdk/sessions/goal.d.ts +145 -0
- package/dist/sdk/sessions/goal.js +405 -0
- package/dist/sdk/sessions/goalLoop.d.ts +37 -0
- package/dist/sdk/sessions/goalLoop.js +125 -0
- package/dist/sdk/sessions/goalPrompts.d.ts +4 -0
- package/dist/sdk/sessions/goalPrompts.js +93 -0
- package/dist/sdk/sessions/goalStop.d.ts +27 -0
- package/dist/sdk/sessions/goalStop.js +41 -0
- package/dist/sdk/sessions/runStore.js +1 -0
- package/dist/sdk/sessions/runner.d.ts +6 -3
- package/dist/sdk/sessions/runner.js +21 -13
- package/dist/sdk/sessions/sessions.d.ts +10 -0
- package/dist/sdk/sessions/sessions.js +47 -37
- package/dist/sdk/sessions/workSlice.d.ts +2 -0
- package/dist/sdk/sessions/workSlice.js +2 -2
- package/dist/sdk/terminal/piExtension.d.ts +2 -1
- package/dist/sdk/terminal/piExtension.js +70 -28
- package/dist/sdk/terminal/terminals.js +3 -2
- package/dist/sdk/terminal/tui/commands.d.ts +2 -0
- package/dist/sdk/terminal/tui/commands.js +3 -0
- package/dist/sdk/terminal/tui/goalCommand.d.ts +19 -0
- package/dist/sdk/terminal/tui/goalCommand.js +83 -0
- package/dist/sdk/terminal/tui/runtime.d.ts +3 -0
- package/dist/sdk/terminal/tui/runtime.js +7 -1
- package/dist/sdk/tools/askUser.js +1 -1
- package/dist/sdk/tools/todo.js +4 -2
- package/dist/terminal-opentui.js +902 -274
- package/dist/terminal-pi.js +611 -380
- package/docs/architecture/02-sessions-and-runs.md +28 -22
- package/docs/architecture/04-prompt.md +81 -54
- package/docs/architecture/06-plugins-and-capabilities.md +16 -1
- package/docs/architecture/07-tools-and-gate.md +7 -4
- package/docs/architecture/10-server-protocol.md +14 -6
- package/docs/architecture/11-terminal.md +22 -6
- package/docs/decisions/ADR-0008-flexible-reporting-guidance.md +3 -0
- package/docs/decisions/ADR-0068-scope-and-completion-report.md +5 -2
- package/docs/decisions/ADR-0069-stop-gate-and-finish.md +8 -2
- package/docs/decisions/ADR-0070-terminal-slice-continuation.md +4 -1
- package/docs/decisions/ADR-0071-completion-check.md +3 -2
- package/docs/decisions/ADR-0072-codex-prompts-and-goal.md +108 -0
- package/docs/decisions/ADR-0073-large-reporting-prompt.md +89 -0
- package/docs/decisions/ADR-0074-report-content-not-report-blocks.md +90 -0
- package/docs/decisions/ADR-0075-no-todo-gate.md +84 -0
- package/docs/decisions/ADR-0076-codex-final-answer-verbatim.md +93 -0
- package/docs/parity.md +4 -1
- package/docs/releases/1.4.0-unstable.md +25 -0
- package/docs/releases/1.5.0-unstable.md +23 -0
- package/docs/releases/README.md +1 -1
- package/docs/study/00-index.md +7 -0
- package/docs/study/STUDY-0004-turn-end-controls.md +9 -0
- package/docs/study/STUDY-0005-skill-installation-guidance.md +146 -0
- package/docs/study/STUDY-0006-reporting-prompts.md +119 -0
- package/docs/study/arms/04-skills.md +6 -0
- package/docs/terminal-tui.md +17 -7
- package/package.json +1 -1
- package/dist/sdk/sessions/stopGate.d.ts +0 -89
- package/dist/sdk/sessions/stopGate.js +0 -171
|
@@ -1,16 +1,15 @@
|
|
|
1
|
-
|
|
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
|
|
10
|
-
export declare const MAX_CHECK_TRANSCRIPT =
|
|
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
|
|
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(
|
|
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
|
|
33
|
+
* `{ verdict: null }`, and the claim is accepted as it stands.
|
|
35
34
|
*/
|
|
36
35
|
export declare function runCompletionCheck(ask: CheckModel, input: {
|
|
37
|
-
|
|
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
|
-
/**
|
|
51
|
-
export declare function
|
|
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
|
|
2
|
-
export const MAX_CHECK_TRANSCRIPT =
|
|
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
|
|
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"
|
|
10
|
+
{"verdict":"done"|"continue","reason":"one or two sentences","next":"the next concrete step, for continue"}
|
|
11
11
|
|
|
12
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
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
|
|
88
|
-
`##
|
|
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'
|
|
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
|
|
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.
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
385
|
+
/** A goal stopped for the person (ADR-0072). */
|
|
386
386
|
'needs_person',
|
|
387
|
-
/**
|
|
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;
|