aligndev 0.23.2 → 0.24.0
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/README.md +24 -12
- package/dist/code/code-cli.d.ts +3 -1
- package/dist/code/code-cli.js +98 -31
- package/dist/code/coding-agent.d.ts +1 -1
- package/dist/code/coding-agent.js +13 -4
- package/dist/code/models.d.ts +1 -1
- package/dist/code/models.js +9 -2
- package/dist/code/pi-agent.d.ts +2 -0
- package/dist/code/pi-agent.js +229 -0
- package/dist/code/quota.js +3 -0
- package/dist/code/run-agent.d.ts +4 -1
- package/dist/code/run-agent.js +15 -3
- package/dist/code/session-file.js +1 -1
- package/dist/config.js +6 -3
- package/dist/guide/code-guide.d.ts +1 -1
- package/dist/guide/code-guide.js +13 -5
- package/package.json +1 -1
- package/templates/guide/code.md +86 -20
- package/templates/guide/playbook/consultation.md +5 -0
- package/templates/guide/playbook/playbook.md +12 -2
- package/templates/guide/playbook/project-workspace-setup.md +1 -1
- package/templates/guide/playbook/working-session.md +10 -0
package/README.md
CHANGED
|
@@ -26,17 +26,17 @@ A task can also start at any intermediate step.
|
|
|
26
26
|
|
|
27
27
|
## Two Ways to Run the Assistant
|
|
28
28
|
|
|
29
|
-
**In your coding agent.** A Claude Code or
|
|
29
|
+
**In your coding agent.** A Claude Code, Codex or persistent Pi session becomes the assistant of the repository it starts in. You keep chatting in the same session; the agents it launches work in the background.
|
|
30
30
|
|
|
31
31
|
**As an OpenClaw bot.** [AlignDev for OpenClaw](#start-as-an-openclaw-bot) deploys the assistant on a server, under its own name in Slack or Discord. It works on every project of the host, one thread per task.
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
For a coding-agent assistant, parent host and delegated child are independent: `code.agent` selects Claude Code, Codex or Pi. Without that setting, the detected parent kind is the default child. OpenClaw deployment templates still offer Claude Code or Codex.
|
|
34
34
|
|
|
35
|
-
## Start in Claude Code or
|
|
35
|
+
## Start in Claude Code, Codex or Pi
|
|
36
36
|
|
|
37
37
|
The project needs an AlignFirst `.plans` directory, in its repository or in a [companion directory](https://github.com/paleo/alignfirst/tree/main/packages/alignfirst#companion-directories). The [setup guide](https://github.com/paleo/alignfirst/blob/main/skills/alignfirst-setup-guide/references/coding-agent-assistant.md) prepares it.
|
|
38
38
|
|
|
39
|
-
The
|
|
39
|
+
The child needs network access and writes outside the repository. Claude Code/Codex parents request their established sandbox bypass or elevation; approve that request when it comes. Pi uses ordinary OS permissions and saved project trust. It has no implied sandbox or per-command approval boundary, and `code.skipPermissions` has no effect on Pi.
|
|
40
40
|
|
|
41
41
|
### With the Skill
|
|
42
42
|
|
|
@@ -46,11 +46,22 @@ Install the `aligndev` skill:
|
|
|
46
46
|
npx skills add https://github.com/paleo/alignfirst --global --skill aligndev
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
Then start a session in the project and invoke `/aligndev` in Claude Code, or
|
|
49
|
+
Then start a session in the project and invoke `/aligndev` in Claude Code, `$aligndev` in Codex, or `/skill:aligndev` in Pi. To target Pi explicitly, add `--agent pi` to the installer command. Pi discovers global `~/.agents/skills/`; verify the current installer's target/layout when upgrading.
|
|
50
|
+
|
|
51
|
+
### Pi's Separate Tools
|
|
52
|
+
|
|
53
|
+
The skill supplies instructions, not executable tools. Install only the package needed by each role:
|
|
54
|
+
|
|
55
|
+
- **Persistent Pi parent assistant:** `pi install npm:@alignfirst/pi-background` supplies the generic `background` tool. The playbook uses it to launch ordinary `aligndev code new/resume ... --quiet --meta <unique-run-key>` commands. On completion it validates the job handle, then retrieves the exact durable run through `code status <file> --result` or its unique meta key. A one-shot Pi process exits after its answer and cannot serve this role.
|
|
56
|
+
- **Pi coding child or direct AlignFirst user:** `pi install npm:@alignfirst/pi-subagent` supplies synchronous isolated plan/review delegation. If parent and child are both Pi, their respective environments need both capabilities. Neither package installs the skill or the other package.
|
|
57
|
+
|
|
58
|
+
Before replacing a local extension that already registers `subagent`, obtain the user's approval and disable that extension explicitly with `pi config`. Keep existing profiles; do not overwrite them or load two implementations. Reload after installation; `/reload` cancels active jobs and subagents.
|
|
59
|
+
|
|
60
|
+
Background reporting uses Pi's native follow-up delivery. Manual compaction and cancelled/failed navigation may delay notices until another turn; interruption or queue clearing can lose automatic continuation. Submitted notices may appear after reload/navigation and must be checked for current ownership. There is no exactly-once or crash-recovery guarantee. Normal session shutdown cancels owned work. See the [extension architecture](https://github.com/paleo/alignfirst/blob/main/docs/pi-extensions.md) and each package README for limits.
|
|
50
61
|
|
|
51
62
|
### Without a Skill
|
|
52
63
|
|
|
53
|
-
Add this section to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or the equivalent):
|
|
64
|
+
Add this section to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.pi/agent/AGENTS.md`, or the equivalent):
|
|
54
65
|
|
|
55
66
|
```markdown
|
|
56
67
|
## AlignDev
|
|
@@ -63,7 +74,8 @@ Then ask your session to work with aligndev.
|
|
|
63
74
|
### Requirements
|
|
64
75
|
|
|
65
76
|
- Node.js 22.11 or later. The assistant runs `aligndev` through `npx`, so there is nothing to install.
|
|
66
|
-
-
|
|
77
|
+
- The selected child installed and authenticated: `claude` then `/login`, `codex login`, or `pi` then `/login <provider>` (or configured provider credentials). Pi requires Node.js 22.19 or later; the Pi adapter and extensions target Pi 1.3.0.
|
|
78
|
+
- For Pi, select a usable native model, preferably `provider/model` (optional thinking suffix). Authenticate in the same account/configuration used by the child; never expose credential values in diagnostics.
|
|
67
79
|
- Linux or macOS, or Windows through WSL.
|
|
68
80
|
|
|
69
81
|
## Configuration
|
|
@@ -78,13 +90,13 @@ Then ask your session to work with aligndev.
|
|
|
78
90
|
|
|
79
91
|
- `platform` — `codingAgent` (default) for a coding-agent assistant, `openclaw` for an OpenClaw bot.
|
|
80
92
|
- `projectsRoot` — the projects directory of an OpenClaw host. Required by `openclaw`. `~/` expands to the home directory; a relative path resolves against `~/.alignfirst/`.
|
|
81
|
-
- `code.agent` — the
|
|
82
|
-
- `code.defaultModel` — the model of a new session
|
|
83
|
-
- `code.models` —
|
|
84
|
-
- `code.skipPermissions` — `true` runs Claude Code with `--dangerously-skip-permissions` instead of `--permission-mode auto`, and Codex with `--dangerously-bypass-approvals-and-sandbox` instead of `--sandbox workspace-write`. Default: `false`.
|
|
93
|
+
- `code.agent` — the child: `claude`, `codex` or `pi`. Default: the coding agent running the assistant, detected from its environment. Set it to choose another child or resolve mixed host markers. It never selects the parent's launch tool.
|
|
94
|
+
- `code.defaultModel` — the model of a new session without `--model`, one of the accepted models. Default: the child's own default. A resumed session keeps its recorded model; Pi resumes require the original worktree.
|
|
95
|
+
- `code.models` — a nonempty list restricts accepted selectors. Defaults: Claude's `fable`, `opus`, `sonnet`, `haiku`, or Codex's `astra`, `sol`, `terra`, `luna`. Pi accepts any nonblank native selector by default, preferably `provider/model`; an absent or empty list adds no allowlist.
|
|
96
|
+
- `code.skipPermissions` — `true` runs Claude Code with `--dangerously-skip-permissions` instead of `--permission-mode auto`, and Codex with `--dangerously-bypass-approvals-and-sandbox` instead of `--sandbox workspace-write`. Default: `false`. Irrelevant to Pi's ordinary OS permissions.
|
|
85
97
|
- `code.unset` — environment variables to hide from the agent, such as an API key meant for another tool on the host.
|
|
86
98
|
|
|
87
|
-
Unknown keys and invalid values are errors.
|
|
99
|
+
Unknown keys and invalid values are errors. `aligndev code quota` is unsupported for Pi; consult the selected provider directly.
|
|
88
100
|
|
|
89
101
|
## Start as an OpenClaw Bot
|
|
90
102
|
|
package/dist/code/code-cli.d.ts
CHANGED
|
@@ -22,6 +22,7 @@ export type CodeCommand = {
|
|
|
22
22
|
} | {
|
|
23
23
|
kind: "status";
|
|
24
24
|
target: StatusTarget;
|
|
25
|
+
includeResult: boolean;
|
|
25
26
|
} | {
|
|
26
27
|
kind: "quota";
|
|
27
28
|
} | {
|
|
@@ -50,10 +51,11 @@ export interface SessionArgs {
|
|
|
50
51
|
message?: string;
|
|
51
52
|
model?: string;
|
|
52
53
|
meta?: string;
|
|
54
|
+
quiet?: boolean;
|
|
53
55
|
}
|
|
54
56
|
export declare function runCode(tokens: string[], config: LoadedConfig, ctx: CodeContext): Promise<number>;
|
|
55
57
|
export declare function parseCodeArgs(tokens: string[], aligndev: string): CodeCommand;
|
|
56
|
-
export declare function validateSessionArgs(args: SessionArgs, models: readonly string[]): string | undefined;
|
|
58
|
+
export declare function validateSessionArgs(args: SessionArgs, models: readonly string[] | undefined): string | undefined;
|
|
57
59
|
export declare function checkLaunchGuards(args: SessionArgs, agent: CodingAgent, realCwd: string, ticket: string | undefined, records: SessionRecord[]): string | undefined;
|
|
58
60
|
export declare function resolveTicket(args: SessionArgs, records: SessionRecord[]): string | undefined;
|
|
59
61
|
export interface RunInput {
|
package/dist/code/code-cli.js
CHANGED
|
@@ -9,7 +9,7 @@ import { createAgentAdapter } from "./coding-agent.js";
|
|
|
9
9
|
import { resolveModels } from "./models.js";
|
|
10
10
|
import { buildPrompt, PROTOCOLS } from "./prompt.js";
|
|
11
11
|
import { buildAgentEnv, runAgent } from "./run-agent.js";
|
|
12
|
-
import { applyCompletion, findNewestSessionFile, listSessionRecords, readPidStartTime, reconcileSessionFile, resolveSessionFilePath, writeInitialSessionFile, } from "./session-file.js";
|
|
12
|
+
import { applyCompletion, findNewestSessionFile, listSessionRecords, readPidStartTime, reconcileSessionFile, resolveSessionFilePath, RESULT_MARKER, writeInitialSessionFile, } from "./session-file.js";
|
|
13
13
|
// Distinct from 1 (ordinary run failure) so a script can branch on an auth failure that needs an
|
|
14
14
|
// operator re-login rather than a retry.
|
|
15
15
|
const EXIT_AUTH_REQUIRED = 2;
|
|
@@ -21,6 +21,7 @@ const SESSION_OPTIONS = {
|
|
|
21
21
|
message: { type: "string", short: "m" },
|
|
22
22
|
model: { type: "string" },
|
|
23
23
|
meta: { type: "string" },
|
|
24
|
+
quiet: { type: "boolean" },
|
|
24
25
|
help: { type: "boolean", short: "h", default: false },
|
|
25
26
|
};
|
|
26
27
|
// Items the agent would not find in the repository: a new session gets `alignfirst context`.
|
|
@@ -36,7 +37,7 @@ export async function runCode(tokens, config, ctx) {
|
|
|
36
37
|
try {
|
|
37
38
|
const command = parseCodeArgs(tokens, ctx.forms.aligndev);
|
|
38
39
|
if (command.kind === "status")
|
|
39
|
-
return showStatus(ctx, command.target);
|
|
40
|
+
return showStatus(ctx, command.target, command.includeResult);
|
|
40
41
|
const code = resolveCodeConfig(config, ctx.env);
|
|
41
42
|
if (command.kind === "quota")
|
|
42
43
|
return await showQuota(ctx, code);
|
|
@@ -58,11 +59,16 @@ export async function runCode(tokens, config, ctx) {
|
|
|
58
59
|
return 1;
|
|
59
60
|
}
|
|
60
61
|
}
|
|
61
|
-
function showStatus(ctx, target) {
|
|
62
|
+
function showStatus(ctx, target, includeResult) {
|
|
62
63
|
const tree = sessionTreeOf(readReport(ctx), ctx.cwd);
|
|
63
64
|
const sessionFilePath = resolveStatusTargetSessionFile(tree, target);
|
|
64
65
|
const completion = reconcileSessionFile(sessionFilePath);
|
|
65
66
|
ctx.stdout.write(renderSessionStatus(tree.cwd, sessionFilePath, completion.frontmatter));
|
|
67
|
+
if (includeResult &&
|
|
68
|
+
completion.frontmatter.status !== "running" &&
|
|
69
|
+
completion.result !== undefined) {
|
|
70
|
+
ctx.stdout.write(`${RESULT_MARKER}\n${completion.result}\n`);
|
|
71
|
+
}
|
|
66
72
|
return 0;
|
|
67
73
|
}
|
|
68
74
|
function readReport(ctx) {
|
|
@@ -194,6 +200,7 @@ function parseStatusCommand(tokens) {
|
|
|
194
200
|
ticket: { type: "string" },
|
|
195
201
|
"no-ticket": { type: "boolean", default: false },
|
|
196
202
|
meta: { type: "string" },
|
|
203
|
+
result: { type: "boolean", default: false },
|
|
197
204
|
help: { type: "boolean", short: "h", default: false },
|
|
198
205
|
},
|
|
199
206
|
strict: true,
|
|
@@ -209,16 +216,17 @@ function parseStatusCommand(tokens) {
|
|
|
209
216
|
throw new Error("Error: `aligndev code status` takes exactly one of <session-file>, --ticket <id>, --no-ticket " +
|
|
210
217
|
"or --meta <key>.");
|
|
211
218
|
}
|
|
219
|
+
const includeResult = values.result;
|
|
212
220
|
if (values.meta !== undefined)
|
|
213
|
-
return { kind: "status", target: { kind: "meta", meta: values.meta } };
|
|
221
|
+
return { kind: "status", target: { kind: "meta", meta: values.meta }, includeResult };
|
|
214
222
|
if (values.ticket !== undefined) {
|
|
215
223
|
if (!isPathSafeTicket(values.ticket))
|
|
216
224
|
throw new Error(TICKET_PATH_ERROR);
|
|
217
|
-
return { kind: "status", target: { kind: "ticket", ticket: values.ticket } };
|
|
225
|
+
return { kind: "status", target: { kind: "ticket", ticket: values.ticket }, includeResult };
|
|
218
226
|
}
|
|
219
227
|
if (values["no-ticket"])
|
|
220
|
-
return { kind: "status", target: { kind: "noTicket" } };
|
|
221
|
-
return { kind: "status", target: { kind: "file", sessionFile: positionals[0] } };
|
|
228
|
+
return { kind: "status", target: { kind: "noTicket" }, includeResult };
|
|
229
|
+
return { kind: "status", target: { kind: "file", sessionFile: positionals[0] }, includeResult };
|
|
222
230
|
}
|
|
223
231
|
function parseNewCommand(tokens) {
|
|
224
232
|
const { values } = parseArgs({
|
|
@@ -233,6 +241,7 @@ function parseNewCommand(tokens) {
|
|
|
233
241
|
args: {
|
|
234
242
|
ticket: values.ticket,
|
|
235
243
|
noTicket: values["no-ticket"],
|
|
244
|
+
quiet: values.quiet,
|
|
236
245
|
protocol: values.protocol,
|
|
237
246
|
catchup: values.catchup,
|
|
238
247
|
messageFile: values["message-file"],
|
|
@@ -260,6 +269,7 @@ function parseResumeCommand(tokens) {
|
|
|
260
269
|
resume: positionals[0],
|
|
261
270
|
ticket: values.ticket,
|
|
262
271
|
noTicket: false,
|
|
272
|
+
quiet: values.quiet,
|
|
263
273
|
protocol: values.protocol,
|
|
264
274
|
catchup: values.catchup,
|
|
265
275
|
messageFile: values["message-file"],
|
|
@@ -283,8 +293,12 @@ export function validateSessionArgs(args, models) {
|
|
|
283
293
|
if (args.protocol !== undefined && !PROTOCOLS.includes(args.protocol)) {
|
|
284
294
|
return `Error: --protocol must be one of: ${PROTOCOLS.join(", ")}.`;
|
|
285
295
|
}
|
|
286
|
-
if (args.model !== undefined
|
|
287
|
-
|
|
296
|
+
if (args.model !== undefined) {
|
|
297
|
+
if (args.model.trim() === "")
|
|
298
|
+
return "Error: --model must be nonblank.";
|
|
299
|
+
if (models !== undefined && !models.includes(args.model)) {
|
|
300
|
+
return `Error: --model must be one of: ${models.join(", ")}.`;
|
|
301
|
+
}
|
|
288
302
|
}
|
|
289
303
|
if (args.protocol === undefined && !hasMessage && args.catchup !== true) {
|
|
290
304
|
return "Error: --message is required when --protocol is not specified.";
|
|
@@ -373,7 +387,9 @@ async function runSession(args, code, ctx) {
|
|
|
373
387
|
sessionId: null,
|
|
374
388
|
result: message,
|
|
375
389
|
});
|
|
376
|
-
|
|
390
|
+
writeFailureDiagnostic(ctx, sessionFilePath, args.quiet === true
|
|
391
|
+
? `Could not resolve the ${agent} model; check --model, code.models and the agent installation.`
|
|
392
|
+
: message);
|
|
377
393
|
return 1;
|
|
378
394
|
}
|
|
379
395
|
const runConfig = buildRunConfig({
|
|
@@ -389,17 +405,42 @@ async function runSession(args, code, ctx) {
|
|
|
389
405
|
contextContent,
|
|
390
406
|
alignfirst: forms.alignfirst,
|
|
391
407
|
});
|
|
392
|
-
createMissingCompanion(report
|
|
408
|
+
createMissingCompanion(report);
|
|
393
409
|
const result = await runAgent(runConfig, createAgentAdapter(agent), stdout);
|
|
394
410
|
if (args.resume === undefined && result.sessionId) {
|
|
395
411
|
stdout.write(`\nSession ID: ${result.sessionId}\n`);
|
|
396
412
|
}
|
|
397
413
|
if (result.authRequired) {
|
|
398
|
-
|
|
399
|
-
|
|
414
|
+
writeFailureDiagnostic(ctx, sessionFilePath, "coding agent not authenticated — an administrator must re-login on the host " +
|
|
415
|
+
`(${authenticationInstruction(agent)}).`);
|
|
400
416
|
return EXIT_AUTH_REQUIRED;
|
|
401
417
|
}
|
|
402
|
-
|
|
418
|
+
if (result.status === "succeeded")
|
|
419
|
+
return 0;
|
|
420
|
+
writeFailureDiagnostic(ctx, sessionFilePath, failureDiagnostic(agent, result.result));
|
|
421
|
+
return 1;
|
|
422
|
+
}
|
|
423
|
+
function authenticationInstruction(agent) {
|
|
424
|
+
switch (agent) {
|
|
425
|
+
case "claude":
|
|
426
|
+
return "`claude`, then `/login`";
|
|
427
|
+
case "codex":
|
|
428
|
+
return "`codex login`";
|
|
429
|
+
case "pi":
|
|
430
|
+
return "`pi`, then `/login <provider>`, or configure provider credentials";
|
|
431
|
+
}
|
|
432
|
+
}
|
|
433
|
+
function writeFailureDiagnostic(ctx, sessionFilePath, message) {
|
|
434
|
+
ctx.stderr.write(`aligndev code: ${message}\nSession file: ${displayPath(ctx.cwd, sessionFilePath)}\n`);
|
|
435
|
+
}
|
|
436
|
+
// Keep arbitrary provider output (which may contain credentials) in the durable file.
|
|
437
|
+
function failureDiagnostic(agent, result) {
|
|
438
|
+
if (result.includes("ENOENT"))
|
|
439
|
+
return `${agent} could not start; check its installation and PATH.`;
|
|
440
|
+
if (result.includes("Could not send prompt:")) {
|
|
441
|
+
return `Could not send the prompt to ${agent}; inspect the session file before retrying.`;
|
|
442
|
+
}
|
|
443
|
+
return `${agent} run failed; inspect the session file for the failure details.`;
|
|
403
444
|
}
|
|
404
445
|
// Fail-fast launch guards, run against the (healed) session records before anything is written.
|
|
405
446
|
// Returns the error to print, or `undefined` when the launch may proceed.
|
|
@@ -424,6 +465,10 @@ export function checkLaunchGuards(args, agent, realCwd, ticket, records) {
|
|
|
424
465
|
return (`Error: session ${args.resume} belongs to agent ${latest.frontmatter.agent}, but the ` +
|
|
425
466
|
`selected agent is ${agent}.`);
|
|
426
467
|
}
|
|
468
|
+
if (agent === "pi" && !sameRealDirectory(latest.frontmatter.cwd, realCwd)) {
|
|
469
|
+
return (`Error: pi session ${args.resume} must resume from its recorded directory ` +
|
|
470
|
+
`${latest.frontmatter.cwd ?? "(missing; start a new session)"}.`);
|
|
471
|
+
}
|
|
427
472
|
}
|
|
428
473
|
// Protocol runs only, against other protocol runs: they share the working tree, and
|
|
429
474
|
// `alignfirst ticket --next` reserves no work-file prefix within a ticket.
|
|
@@ -438,6 +483,16 @@ export function checkLaunchGuards(args, agent, realCwd, ticket, records) {
|
|
|
438
483
|
}
|
|
439
484
|
return;
|
|
440
485
|
}
|
|
486
|
+
function sameRealDirectory(recorded, realCwd) {
|
|
487
|
+
if (recorded === null)
|
|
488
|
+
return false;
|
|
489
|
+
try {
|
|
490
|
+
return realpathSync(recorded) === realCwd;
|
|
491
|
+
}
|
|
492
|
+
catch {
|
|
493
|
+
return false;
|
|
494
|
+
}
|
|
495
|
+
}
|
|
441
496
|
function busyProtocolError(record, scope) {
|
|
442
497
|
return (`Error: a ${record.frontmatter.protocol} protocol run is already active ${scope} ` +
|
|
443
498
|
`(${record.path}, pid ${record.frontmatter.pid}); one protocol run at a time per worktree ` +
|
|
@@ -548,6 +603,8 @@ function formatCommand(args) {
|
|
|
548
603
|
}
|
|
549
604
|
if (args.meta !== undefined)
|
|
550
605
|
parts.push("--meta", JSON.stringify(args.meta));
|
|
606
|
+
if (args.quiet === true)
|
|
607
|
+
parts.push("--quiet");
|
|
551
608
|
return parts.join(" ");
|
|
552
609
|
}
|
|
553
610
|
export function buildRunConfig(input) {
|
|
@@ -565,29 +622,34 @@ export function buildRunConfig(input) {
|
|
|
565
622
|
sessionFilePath: input.sessionFilePath,
|
|
566
623
|
cwd: input.cwd,
|
|
567
624
|
resume: args.resume,
|
|
625
|
+
quiet: args.quiet,
|
|
568
626
|
executableModel: input.executableModel,
|
|
569
627
|
skipPermissions: code.skipPermissions,
|
|
570
|
-
additionalDirectories: !code.skipPermissions && report.companion !== null
|
|
628
|
+
additionalDirectories: code.agent !== "pi" && !code.skipPermissions && report.companion !== null
|
|
629
|
+
? [report.companion.dir]
|
|
630
|
+
: [],
|
|
571
631
|
unset: code.unset,
|
|
572
632
|
env: input.env,
|
|
573
633
|
};
|
|
574
634
|
}
|
|
575
635
|
// A registered companion becomes writable before its directory exists: create it for the agent.
|
|
576
|
-
function createMissingCompanion(report
|
|
636
|
+
function createMissingCompanion(report) {
|
|
577
637
|
const { companion } = report;
|
|
578
|
-
if (companion === null || companion.exists
|
|
638
|
+
if (companion === null || companion.exists)
|
|
579
639
|
return;
|
|
580
|
-
}
|
|
581
640
|
mkdirSync(companion.dir, { recursive: true });
|
|
582
641
|
}
|
|
583
642
|
function renderHelp(agent, models, forms) {
|
|
584
643
|
const { aligndev, alignfirst } = forms;
|
|
585
|
-
const permissionMode = agent === "
|
|
586
|
-
? "
|
|
587
|
-
:
|
|
644
|
+
const permissionMode = agent === "pi"
|
|
645
|
+
? "Ordinary OS permissions; code.skipPermissions has no effect. Saved project trust is honored."
|
|
646
|
+
: agent === "claude"
|
|
647
|
+
? "--permission-mode auto (dangerous opt-out: --dangerously-skip-permissions)"
|
|
648
|
+
: "--sandbox workspace-write (dangerous opt-out: --dangerously-bypass-approvals-and-sandbox)";
|
|
588
649
|
const modelBehavior = agent === "codex"
|
|
589
650
|
? "Codex aliases astra, sol, terra, and luna resolve on demand; configured full slugs pass through."
|
|
590
|
-
: "Claude model values pass through unchanged
|
|
651
|
+
: `${agent === "pi" ? "Pi native selectors (including provider/model:thinking)" : "Claude model values"} pass through unchanged.`;
|
|
652
|
+
const modelPolicy = models === undefined ? "Any nonblank pi-native selector" : `One of ${models.join(", ")}`;
|
|
591
653
|
const requires = forms.viaNpx
|
|
592
654
|
? "Requires: the alignfirst CLI, run through npx, for the project layout, side tickets and the\ndelegated protocols."
|
|
593
655
|
: "Requires: the alignfirst CLI on PATH (npm install -g alignfirst), for the project layout, side\ntickets and the delegated protocols.";
|
|
@@ -598,7 +660,7 @@ Usage:
|
|
|
598
660
|
${aligndev} code new --catchup --ticket <id> [--protocol <protocol>] [--message-file <path|->]
|
|
599
661
|
${aligndev} code new --message "..."
|
|
600
662
|
${aligndev} code resume <sessionId> [--protocol <protocol>] [--message "..."]
|
|
601
|
-
${aligndev} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>)
|
|
663
|
+
${aligndev} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>) [--result]
|
|
602
664
|
${aligndev} code quota
|
|
603
665
|
${aligndev} code -h, --help
|
|
604
666
|
|
|
@@ -609,14 +671,18 @@ Commands:
|
|
|
609
671
|
run of the ticket, of no-ticket work, or of the --meta key. Includes
|
|
610
672
|
contextTokens, the context-window occupancy the run ended on, and
|
|
611
673
|
contextCompacted. Does not start an agent.
|
|
612
|
-
quota Show
|
|
674
|
+
quota Show account limits and reset times (unsupported for pi).
|
|
613
675
|
|
|
614
676
|
Options (status):
|
|
615
677
|
--ticket <id> Newest run of that ticket.
|
|
616
678
|
--no-ticket Newest run of no-ticket work.
|
|
617
679
|
--meta <key> Newest run tagged with \`--meta <key>\`, wherever it sits.
|
|
680
|
+
--result Append the terminal run's final Result block, when present, without the
|
|
681
|
+
transcript. Running sessions show status only; default is metadata only.
|
|
618
682
|
|
|
619
683
|
Options (new, resume):
|
|
684
|
+
--quiet Suppress the live transcript on stdout; keep all durable session output,
|
|
685
|
+
the initial Session file line, new Session ID, and failure diagnostics.
|
|
620
686
|
--protocol <p> One of: ${PROTOCOLS.join(", ")}.
|
|
621
687
|
--ticket <id> Ticket ID. \`new --protocol\` requires it or a side ticket through
|
|
622
688
|
--no-ticket.
|
|
@@ -626,7 +692,7 @@ Options (new, resume):
|
|
|
626
692
|
--catchup Load the ticket history before the message. new only.
|
|
627
693
|
-m, --message "..." Message to send. Required for spec/aad, or without protocol/catchup.
|
|
628
694
|
--message-file <path> Read the message from a UTF-8 file, or stdin with -. Exclusive with -m.
|
|
629
|
-
--model <model>
|
|
695
|
+
--model <model> ${modelPolicy}. A new session defaults to
|
|
630
696
|
code.defaultModel, else to the coding agent's default. A resume keeps the
|
|
631
697
|
session's model.
|
|
632
698
|
--meta "..." Opaque handoff string, stored verbatim in the session file frontmatter
|
|
@@ -636,7 +702,7 @@ Options (new, resume):
|
|
|
636
702
|
${requires}
|
|
637
703
|
|
|
638
704
|
Config (~/.alignfirst/aligndev.settings.json):
|
|
639
|
-
code.agent Coding agent: claude or
|
|
705
|
+
code.agent Coding agent: claude, codex or pi (selected: ${agent}). Defaults to the coding
|
|
640
706
|
agent that runs aligndev.
|
|
641
707
|
code.defaultModel Default model of a new session, one of the models accepted by --model.
|
|
642
708
|
code.models List replacing the models accepted by --model.
|
|
@@ -644,13 +710,14 @@ Config (~/.alignfirst/aligndev.settings.json):
|
|
|
644
710
|
code.unset Env vars to strip from the coding agent child.
|
|
645
711
|
|
|
646
712
|
Selected-agent permissions: ${permissionMode}
|
|
647
|
-
The
|
|
713
|
+
The project's companion directory is prepared before launch; pi uses ordinary OS access.
|
|
648
714
|
${modelBehavior}
|
|
649
715
|
|
|
650
|
-
${aligndev} code runs a coding agent in the foreground and blocks until it finishes
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
detach
|
|
716
|
+
${aligndev} code runs a coding agent in the foreground and blocks until it finishes. The transcript
|
|
717
|
+
is durable in a session file under .plans/ or its companion; stdout also streams it unless --quiet.
|
|
718
|
+
Coding runs can be very long. The host owns background execution and completion delivery;
|
|
719
|
+
verify its capability before launch, use --quiet, and never detach the command. On completion,
|
|
720
|
+
retrieve status --result with the exact session-file path or a unique per-run --meta key.
|
|
654
721
|
|
|
655
722
|
Run \`${aligndev} guide code\` for the full delegation guide.
|
|
656
723
|
`;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { AgentAdapter } from "./run-agent.js";
|
|
2
|
-
export declare const CODING_AGENTS: readonly ["claude", "codex"];
|
|
2
|
+
export declare const CODING_AGENTS: readonly ["claude", "codex", "pi"];
|
|
3
3
|
export type CodingAgent = (typeof CODING_AGENTS)[number];
|
|
4
4
|
export declare function createAgentAdapter(agent: CodingAgent): AgentAdapter;
|
|
5
5
|
export declare function detectCodingAgents(env: NodeJS.ProcessEnv): CodingAgent[];
|
|
@@ -1,16 +1,25 @@
|
|
|
1
1
|
import { createClaudeAdapter } from "./claude-agent.js";
|
|
2
2
|
import { createCodexAdapter } from "./codex-agent.js";
|
|
3
|
-
|
|
3
|
+
import { createPiAdapter } from "./pi-agent.js";
|
|
4
|
+
export const CODING_AGENTS = ["claude", "codex", "pi"];
|
|
4
5
|
export function createAgentAdapter(agent) {
|
|
5
|
-
|
|
6
|
+
switch (agent) {
|
|
7
|
+
case "claude":
|
|
8
|
+
return createClaudeAdapter();
|
|
9
|
+
case "codex":
|
|
10
|
+
return createCodexAdapter();
|
|
11
|
+
case "pi":
|
|
12
|
+
return createPiAdapter();
|
|
13
|
+
}
|
|
6
14
|
}
|
|
7
|
-
//
|
|
8
|
-
// Codex sets `CODEX_THREAD_ID`.
|
|
15
|
+
// Host markers select the child only when code.agent is absent.
|
|
9
16
|
export function detectCodingAgents(env) {
|
|
10
17
|
const detected = [];
|
|
11
18
|
if (env.CLAUDECODE === "1")
|
|
12
19
|
detected.push("claude");
|
|
13
20
|
if (env.CODEX_THREAD_ID !== undefined && env.CODEX_THREAD_ID !== "")
|
|
14
21
|
detected.push("codex");
|
|
22
|
+
if (env.PI_CODING_AGENT === "true" || env.AI_AGENT === "pi")
|
|
23
|
+
detected.push("pi");
|
|
15
24
|
return detected;
|
|
16
25
|
}
|
package/dist/code/models.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { CodingAgent } from "./coding-agent.js";
|
|
2
2
|
export declare const CLAUDE_DEFAULT_MODELS: readonly ["fable", "opus", "sonnet", "haiku"];
|
|
3
3
|
export declare const CODEX_DEFAULT_MODELS: readonly ["astra", "sol", "terra", "luna"];
|
|
4
|
-
export declare function resolveModels(agent: CodingAgent, override: readonly string[] | undefined): readonly string[];
|
|
4
|
+
export declare function resolveModels(agent: CodingAgent, override: readonly string[] | undefined): readonly string[] | undefined;
|
|
5
5
|
export interface ModelDiscoveryContext {
|
|
6
6
|
cwd: string;
|
|
7
7
|
env: NodeJS.ProcessEnv;
|
package/dist/code/models.js
CHANGED
|
@@ -8,14 +8,21 @@ const CODEX_CATALOG_TIMEOUT_MS = 30_000;
|
|
|
8
8
|
export function resolveModels(agent, override) {
|
|
9
9
|
if (override !== undefined && override.length > 0)
|
|
10
10
|
return override;
|
|
11
|
-
|
|
11
|
+
switch (agent) {
|
|
12
|
+
case "claude":
|
|
13
|
+
return CLAUDE_DEFAULT_MODELS;
|
|
14
|
+
case "codex":
|
|
15
|
+
return CODEX_DEFAULT_MODELS;
|
|
16
|
+
case "pi":
|
|
17
|
+
return;
|
|
18
|
+
}
|
|
12
19
|
}
|
|
13
20
|
export function createExecutableModelResolver(runCatalog = runCodexModelCatalog) {
|
|
14
21
|
let cachedSlugs;
|
|
15
22
|
return async (agent, selectedModel, context) => {
|
|
16
23
|
if (selectedModel === undefined)
|
|
17
24
|
return;
|
|
18
|
-
if (agent
|
|
25
|
+
if (agent !== "codex" || !CODEX_ALIASES.has(selectedModel))
|
|
19
26
|
return selectedModel;
|
|
20
27
|
try {
|
|
21
28
|
cachedSlugs ??= parseBundledModelSlugs(await runCatalog(context));
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
const MISSING_USAGE = "Pi's latest assistant message did not report valid context usage.";
|
|
2
|
+
const STOP_REASONS = new Set([
|
|
3
|
+
"pending",
|
|
4
|
+
"stop",
|
|
5
|
+
"length",
|
|
6
|
+
"toolUse",
|
|
7
|
+
"error",
|
|
8
|
+
"aborted",
|
|
9
|
+
"deferred",
|
|
10
|
+
]);
|
|
11
|
+
export function createPiAdapter() {
|
|
12
|
+
return {
|
|
13
|
+
executable: "pi",
|
|
14
|
+
buildArgs: buildPiArgs,
|
|
15
|
+
createState: createPiState,
|
|
16
|
+
interpretLine: interpretPiLine,
|
|
17
|
+
assess: assessPiState,
|
|
18
|
+
isAuthenticationError: isPiAuthenticationError,
|
|
19
|
+
authenticationMessage: piAuthenticationMessage,
|
|
20
|
+
failureMessage: piFailure,
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
function buildPiArgs(config) {
|
|
24
|
+
const args = ["--mode", "json"];
|
|
25
|
+
if (config.executableModel !== undefined)
|
|
26
|
+
args.push("--model", config.executableModel);
|
|
27
|
+
if (config.resume !== undefined)
|
|
28
|
+
args.push("--session", config.resume);
|
|
29
|
+
return args;
|
|
30
|
+
}
|
|
31
|
+
function createPiState(config) {
|
|
32
|
+
return {
|
|
33
|
+
expectedSessionId: config.resume,
|
|
34
|
+
headerSeen: false,
|
|
35
|
+
settledAborted: false,
|
|
36
|
+
protocolComplete: false,
|
|
37
|
+
protocolFailed: false,
|
|
38
|
+
authEvidence: false,
|
|
39
|
+
contextCompacted: false,
|
|
40
|
+
contextTokensError: MISSING_USAGE,
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
function interpretPiLine(line, state) {
|
|
44
|
+
let event;
|
|
45
|
+
try {
|
|
46
|
+
event = JSON.parse(line);
|
|
47
|
+
}
|
|
48
|
+
catch {
|
|
49
|
+
return invalidProtocol(state, "invalid JSON record");
|
|
50
|
+
}
|
|
51
|
+
if (!isRecord(event) || typeof event.type !== "string") {
|
|
52
|
+
return invalidProtocol(state, "expected an event object with a type");
|
|
53
|
+
}
|
|
54
|
+
if (!state.headerSeen && event.type !== "session") {
|
|
55
|
+
invalidProtocol(state, "missing initial session header");
|
|
56
|
+
}
|
|
57
|
+
switch (event.type) {
|
|
58
|
+
case "session":
|
|
59
|
+
return captureHeader(event, state);
|
|
60
|
+
case "agent_start":
|
|
61
|
+
case "turn_start":
|
|
62
|
+
state.stopReason = undefined;
|
|
63
|
+
state.result = undefined;
|
|
64
|
+
state.protocolComplete = false;
|
|
65
|
+
return;
|
|
66
|
+
case "auto_retry_start":
|
|
67
|
+
case "compaction_start":
|
|
68
|
+
state.protocolComplete = false;
|
|
69
|
+
return;
|
|
70
|
+
case "message_start":
|
|
71
|
+
state.protocolComplete = false;
|
|
72
|
+
if (isRecord(event.message) && event.message.role === "assistant") {
|
|
73
|
+
state.stopReason = undefined;
|
|
74
|
+
state.result = undefined;
|
|
75
|
+
captureUsage(undefined, state);
|
|
76
|
+
}
|
|
77
|
+
return;
|
|
78
|
+
case "message_end":
|
|
79
|
+
return captureMessage(event, state);
|
|
80
|
+
case "agent_settled":
|
|
81
|
+
if (typeof event.aborted !== "boolean") {
|
|
82
|
+
return invalidProtocol(state, "agent_settled requires an aborted boolean");
|
|
83
|
+
}
|
|
84
|
+
state.protocolComplete = true;
|
|
85
|
+
state.settledAborted = event.aborted;
|
|
86
|
+
return;
|
|
87
|
+
case "tool_execution_start":
|
|
88
|
+
case "tool_execution_end":
|
|
89
|
+
return renderTool(event);
|
|
90
|
+
case "compaction_end":
|
|
91
|
+
if (event.aborted === false && isRecord(event.result))
|
|
92
|
+
state.contextCompacted = true;
|
|
93
|
+
return;
|
|
94
|
+
case "auto_retry_end":
|
|
95
|
+
if (event.success === false && typeof event.finalError === "string") {
|
|
96
|
+
state.failure = event.finalError;
|
|
97
|
+
state.authEvidence = isPiAuthenticationError(event.finalError);
|
|
98
|
+
}
|
|
99
|
+
return;
|
|
100
|
+
default:
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
function invalidProtocol(state, detail) {
|
|
105
|
+
state.protocolFailed = true;
|
|
106
|
+
state.failure = `Invalid pi JSON stream: ${detail}.`;
|
|
107
|
+
return `[error] ${state.failure}`;
|
|
108
|
+
}
|
|
109
|
+
function isRecord(value) {
|
|
110
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
111
|
+
}
|
|
112
|
+
function captureHeader(event, state) {
|
|
113
|
+
if (state.headerSeen ||
|
|
114
|
+
event.version !== 3 ||
|
|
115
|
+
typeof event.id !== "string" ||
|
|
116
|
+
!/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/i.test(event.id) ||
|
|
117
|
+
typeof event.cwd !== "string" ||
|
|
118
|
+
event.cwd.trim() === "" ||
|
|
119
|
+
typeof event.timestamp !== "string" ||
|
|
120
|
+
!Number.isFinite(Date.parse(event.timestamp))) {
|
|
121
|
+
return invalidProtocol(state, "invalid or unsupported session header (requires pi 1.3.0)");
|
|
122
|
+
}
|
|
123
|
+
state.headerSeen = true;
|
|
124
|
+
if (state.expectedSessionId !== undefined && event.id !== state.expectedSessionId) {
|
|
125
|
+
return invalidProtocol(state, `resumed session ID ${event.id} differs from ${state.expectedSessionId}`);
|
|
126
|
+
}
|
|
127
|
+
state.sessionId = event.id;
|
|
128
|
+
return `[init] session ${event.id}`;
|
|
129
|
+
}
|
|
130
|
+
function captureMessage(event, state) {
|
|
131
|
+
state.protocolComplete = false;
|
|
132
|
+
const message = event.message;
|
|
133
|
+
if (!isRecord(message) || typeof message.role !== "string") {
|
|
134
|
+
return invalidProtocol(state, "message_end requires a message with a role");
|
|
135
|
+
}
|
|
136
|
+
if (message.role !== "assistant")
|
|
137
|
+
return;
|
|
138
|
+
captureUsage(message.usage, state);
|
|
139
|
+
if (!Array.isArray(message.content) ||
|
|
140
|
+
typeof message.stopReason !== "string" ||
|
|
141
|
+
!STOP_REASONS.has(message.stopReason) ||
|
|
142
|
+
message.content.some((block) => !isRecord(block) ||
|
|
143
|
+
typeof block.type !== "string" ||
|
|
144
|
+
(block.type === "text" && typeof block.text !== "string"))) {
|
|
145
|
+
return invalidProtocol(state, "invalid assistant message_end content or stop reason");
|
|
146
|
+
}
|
|
147
|
+
state.stopReason = message.stopReason;
|
|
148
|
+
const text = message.content
|
|
149
|
+
.flatMap((block) => isRecord(block) && block.type === "text" && typeof block.text === "string"
|
|
150
|
+
? [block.text]
|
|
151
|
+
: [])
|
|
152
|
+
.join("\n");
|
|
153
|
+
state.result = text.trim() === "" ? undefined : text;
|
|
154
|
+
// A malformed protocol remains fatal even if a later model response succeeds.
|
|
155
|
+
if (!state.protocolFailed) {
|
|
156
|
+
state.failure = typeof message.errorMessage === "string" ? message.errorMessage : undefined;
|
|
157
|
+
}
|
|
158
|
+
state.authEvidence =
|
|
159
|
+
(message.stopReason === "error" || message.stopReason === "aborted") &&
|
|
160
|
+
typeof message.errorMessage === "string" &&
|
|
161
|
+
isPiAuthenticationError(message.errorMessage);
|
|
162
|
+
return state.result ?? (state.failure === undefined ? undefined : `[error] ${state.failure}`);
|
|
163
|
+
}
|
|
164
|
+
function captureUsage(usage, state) {
|
|
165
|
+
state.contextTokens = undefined;
|
|
166
|
+
state.contextTokensError = MISSING_USAGE;
|
|
167
|
+
if (!isRecord(usage))
|
|
168
|
+
return;
|
|
169
|
+
let total = 0;
|
|
170
|
+
for (const key of ["input", "output", "cacheRead", "cacheWrite"]) {
|
|
171
|
+
const count = usage[key];
|
|
172
|
+
if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)
|
|
173
|
+
return;
|
|
174
|
+
total += count;
|
|
175
|
+
}
|
|
176
|
+
if (!Number.isSafeInteger(total))
|
|
177
|
+
return;
|
|
178
|
+
state.contextTokens = total;
|
|
179
|
+
state.contextTokensError = undefined;
|
|
180
|
+
}
|
|
181
|
+
function renderTool(event) {
|
|
182
|
+
if (typeof event.toolName !== "string")
|
|
183
|
+
return;
|
|
184
|
+
const outcome = event.type === "tool_execution_start" ? "start" : event.isError === true ? "error" : "done";
|
|
185
|
+
return `[tool: ${event.toolName}] ${outcome}`;
|
|
186
|
+
}
|
|
187
|
+
function assessPiState(state) {
|
|
188
|
+
const succeeded = state.sessionId !== undefined &&
|
|
189
|
+
state.protocolComplete &&
|
|
190
|
+
!state.protocolFailed &&
|
|
191
|
+
!state.settledAborted &&
|
|
192
|
+
state.stopReason === "stop" &&
|
|
193
|
+
state.result !== undefined &&
|
|
194
|
+
state.failure === undefined;
|
|
195
|
+
return {
|
|
196
|
+
succeeded,
|
|
197
|
+
sessionId: state.sessionId,
|
|
198
|
+
result: state.result,
|
|
199
|
+
error: succeeded || (!state.headerSeen && !state.protocolFailed) ? undefined : piFailure(state),
|
|
200
|
+
authEvidence: state.authEvidence,
|
|
201
|
+
contextTokens: state.contextTokens,
|
|
202
|
+
contextCompacted: state.contextCompacted,
|
|
203
|
+
contextTokensError: state.contextTokensError,
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
function piFailure(state) {
|
|
207
|
+
if (state.failure !== undefined)
|
|
208
|
+
return state.failure;
|
|
209
|
+
if (state.sessionId === undefined)
|
|
210
|
+
return "Pi stream ended without valid session identity.";
|
|
211
|
+
if (!state.protocolComplete)
|
|
212
|
+
return "Pi stream ended before agent_settled.";
|
|
213
|
+
if (state.settledAborted)
|
|
214
|
+
return "Pi run settled after an abort.";
|
|
215
|
+
if (state.stopReason !== "stop")
|
|
216
|
+
return `Pi final assistant stop reason: ${state.stopReason ?? "missing"}.`;
|
|
217
|
+
return "Pi run settled without a meaningful final assistant result.";
|
|
218
|
+
}
|
|
219
|
+
function isPiAuthenticationError(message) {
|
|
220
|
+
return message
|
|
221
|
+
.split("\n")
|
|
222
|
+
.some((line) => /^(?:Error:\s*)?No API key found for [^\r\n]+\.\s*$/.test(line.trim()) ||
|
|
223
|
+
/^(?:Error:\s*)?Authentication failed for "[^"]+"[.:\s]/.test(line.trim()));
|
|
224
|
+
}
|
|
225
|
+
function piAuthenticationMessage(detail) {
|
|
226
|
+
const base = "Coding agent not authenticated: run `pi`, then `/login <provider>`, or configure " +
|
|
227
|
+
"the provider's credentials before running `aligndev code` again.";
|
|
228
|
+
return detail === undefined || detail.trim() === "" ? base : `${base}\n\n${detail}`;
|
|
229
|
+
}
|
package/dist/code/quota.js
CHANGED
|
@@ -17,6 +17,9 @@ const DEFAULT_QUOTA_PROCESS_ADAPTER = {
|
|
|
17
17
|
export const readQuota = createQuotaReader();
|
|
18
18
|
export function createQuotaReader(adapter = DEFAULT_QUOTA_PROCESS_ADAPTER, timeoutMs = QUOTA_TIMEOUT_MS) {
|
|
19
19
|
return async (agent, context) => {
|
|
20
|
+
if (agent === "pi") {
|
|
21
|
+
throw new Error("Pi account quota is unsupported: check the selected provider's account limits directly.");
|
|
22
|
+
}
|
|
20
23
|
const env = buildAgentEnv(context.env, context.unset);
|
|
21
24
|
return agent === "claude"
|
|
22
25
|
? readClaudeQuota({ ...context, env: translateClaudePrivacyOptOut(env) }, adapter, timeoutMs)
|
package/dist/code/run-agent.d.ts
CHANGED
|
@@ -6,6 +6,7 @@ export interface RunConfig {
|
|
|
6
6
|
sessionFilePath: string;
|
|
7
7
|
cwd: string;
|
|
8
8
|
resume?: string;
|
|
9
|
+
quiet?: boolean;
|
|
9
10
|
executableModel: string | undefined;
|
|
10
11
|
skipPermissions: boolean;
|
|
11
12
|
additionalDirectories: readonly string[];
|
|
@@ -27,6 +28,8 @@ export interface AgentProtocolState {
|
|
|
27
28
|
authEvidence: boolean;
|
|
28
29
|
contextTokens?: number;
|
|
29
30
|
peakContextTokens?: number;
|
|
31
|
+
contextCompacted?: boolean;
|
|
32
|
+
contextTokensError?: string;
|
|
30
33
|
streamTotalTokens?: number;
|
|
31
34
|
}
|
|
32
35
|
export interface AgentAssessment {
|
|
@@ -43,7 +46,7 @@ export interface AgentAdapter {
|
|
|
43
46
|
executable: string;
|
|
44
47
|
env?: Readonly<Record<string, string>>;
|
|
45
48
|
buildArgs(config: RunConfig): string[];
|
|
46
|
-
createState(): AgentProtocolState;
|
|
49
|
+
createState(config: RunConfig): AgentProtocolState;
|
|
47
50
|
interpretLine(line: string, state: AgentProtocolState): string | undefined;
|
|
48
51
|
assess(state: AgentProtocolState): AgentAssessment;
|
|
49
52
|
isAuthenticationError(message: string): boolean;
|
package/dist/code/run-agent.js
CHANGED
|
@@ -18,9 +18,14 @@ const ASSISTANT_SESSION_VARIABLES = [
|
|
|
18
18
|
"CODEX_THREAD_ID",
|
|
19
19
|
"CODEX_CI",
|
|
20
20
|
"CODEX_SANDBOX_NETWORK_DISABLED",
|
|
21
|
+
"PI_SESSION_ID",
|
|
22
|
+
"PI_SESSION_FILE",
|
|
23
|
+
"PI_PROVIDER",
|
|
24
|
+
"PI_MODEL",
|
|
25
|
+
"PI_REASONING_LEVEL",
|
|
21
26
|
];
|
|
22
27
|
export async function runAgent(config, adapter, out, spawnProcess = spawnDirectChild) {
|
|
23
|
-
const state = adapter.createState();
|
|
28
|
+
const state = adapter.createState(config);
|
|
24
29
|
const outcome = await spawnAgent(config, adapter, state, out, spawnProcess);
|
|
25
30
|
const assessment = adapter.assess(state);
|
|
26
31
|
const failed = outcome.exitCode !== 0 || !assessment.succeeded;
|
|
@@ -111,7 +116,8 @@ function emitLine(config, adapter, line, state, out) {
|
|
|
111
116
|
if (rendered === undefined)
|
|
112
117
|
return;
|
|
113
118
|
appendTranscript(config.sessionFilePath, `${rendered}\n`);
|
|
114
|
-
|
|
119
|
+
if (config.quiet !== true)
|
|
120
|
+
out.write(`${rendered}\n`);
|
|
115
121
|
}
|
|
116
122
|
function drainLines(buffer, onLine) {
|
|
117
123
|
const lines = buffer.split("\n");
|
|
@@ -126,6 +132,10 @@ export function buildAgentEnv(baseEnv, unset) {
|
|
|
126
132
|
const env = { ...baseEnv };
|
|
127
133
|
for (const name of ASSISTANT_SESSION_VARIABLES)
|
|
128
134
|
delete env[name];
|
|
135
|
+
if (env.PI_CODING_AGENT === "true")
|
|
136
|
+
delete env.PI_CODING_AGENT;
|
|
137
|
+
if (env.AI_AGENT === "pi")
|
|
138
|
+
delete env.AI_AGENT;
|
|
129
139
|
for (const name of unset) {
|
|
130
140
|
const trimmed = name.trim();
|
|
131
141
|
if (trimmed !== "")
|
|
@@ -195,12 +205,14 @@ export function buildTerminationUpdate(signal, state, now) {
|
|
|
195
205
|
result: `Terminated by ${signal} before completion.`,
|
|
196
206
|
contextTokens: state.contextTokens ?? null,
|
|
197
207
|
contextCompacted: isCompacted(state),
|
|
198
|
-
contextTokensError: null,
|
|
208
|
+
contextTokensError: state.contextTokensError ?? null,
|
|
199
209
|
};
|
|
200
210
|
}
|
|
201
211
|
// Occupancy only falls when the agent compacts the conversation, so a peak above the final figure
|
|
202
212
|
// is the compaction itself.
|
|
203
213
|
export function isCompacted(state) {
|
|
214
|
+
if (state.contextCompacted !== undefined)
|
|
215
|
+
return state.contextCompacted;
|
|
204
216
|
const { contextTokens, peakContextTokens } = state;
|
|
205
217
|
if (contextTokens === undefined || peakContextTokens === undefined)
|
|
206
218
|
return false;
|
|
@@ -226,7 +226,7 @@ export function parseFrontmatter(block) {
|
|
|
226
226
|
};
|
|
227
227
|
}
|
|
228
228
|
function parseAgent(raw) {
|
|
229
|
-
return raw === "claude" || raw === "codex" ? raw : null;
|
|
229
|
+
return raw === "claude" || raw === "codex" || raw === "pi" ? raw : null;
|
|
230
230
|
}
|
|
231
231
|
function parsePid(raw) {
|
|
232
232
|
if (raw === null || raw === undefined)
|
package/dist/config.js
CHANGED
|
@@ -77,15 +77,18 @@ function resolveAgent(config, env) {
|
|
|
77
77
|
if (detected.length === 1)
|
|
78
78
|
return detected[0];
|
|
79
79
|
const problem = detected.length === 0
|
|
80
|
-
?
|
|
81
|
-
:
|
|
80
|
+
? `no coding agent detected (${CODING_AGENTS.join(", ")}): run from a supported agent, or set`
|
|
81
|
+
: `multiple coding agents detected (${detected.join(", ")}): set`;
|
|
82
82
|
throw new Error(`Error: ${problem} "code.agent" (${CODING_AGENTS.join(" or ")}) in ${config.path}.`);
|
|
83
83
|
}
|
|
84
84
|
function checkDefaultModel(code, path) {
|
|
85
85
|
if (code.defaultModel === undefined)
|
|
86
86
|
return;
|
|
87
87
|
const models = resolveModels(code.agent, code.models);
|
|
88
|
-
if (
|
|
88
|
+
if (code.defaultModel.trim() === "") {
|
|
89
|
+
throw new Error(`Error: code.defaultModel must be nonblank, in ${path}.`);
|
|
90
|
+
}
|
|
91
|
+
if (models === undefined || models.includes(code.defaultModel))
|
|
89
92
|
return;
|
|
90
93
|
throw new Error(`Error: code.defaultModel must be one of: ${models.join(", ")}, in ${path}.`);
|
|
91
94
|
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
import type { CodingAgent } from "../code/coding-agent.js";
|
|
2
2
|
import type { CommandForms } from "../command-form.js";
|
|
3
3
|
import type { Platform } from "../config.js";
|
|
4
|
-
export declare function renderCodeGuide(platform: Platform, agent: CodingAgent, models: readonly string[], defaultModel: string | undefined, forms: CommandForms): string;
|
|
4
|
+
export declare function renderCodeGuide(platform: Platform, agent: CodingAgent, models: readonly string[] | undefined, defaultModel: string | undefined, forms: CommandForms): string;
|
package/dist/guide/code-guide.js
CHANGED
|
@@ -2,11 +2,19 @@ import { renderGuideTemplate } from "./render-template.js";
|
|
|
2
2
|
export function renderCodeGuide(platform, agent, models, defaultModel, forms) {
|
|
3
3
|
return renderGuideTemplate("code.md", { platform }, forms, {
|
|
4
4
|
AGENT: agent,
|
|
5
|
-
AUTH_COMMAND: agent === "
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
5
|
+
AUTH_COMMAND: agent === "pi"
|
|
6
|
+
? "`pi`, then `/login <provider>`, or configure provider credentials"
|
|
7
|
+
: agent === "claude"
|
|
8
|
+
? "`claude`, then `/login`"
|
|
9
|
+
: "`codex login`",
|
|
10
|
+
PERMISSIONS: agent === "pi"
|
|
11
|
+
? "Pi uses ordinary OS permissions, including companion access. `code.skipPermissions` has no effect. Saved project trust is honored; no forced approval is passed"
|
|
12
|
+
: agent === "claude"
|
|
13
|
+
? "Normal runs use `--permission-mode auto`, plus `--add-dir <companion>` for a project with a companion directory. `code.skipPermissions: true` in the aligndev settings selects `--dangerously-skip-permissions`"
|
|
14
|
+
: "Normal runs use `--sandbox workspace-write`, plus `--add-dir <companion>` for a project with a companion directory. `code.skipPermissions: true` in the aligndev settings selects `--dangerously-bypass-approvals-and-sandbox`",
|
|
15
|
+
MODEL_POLICY: models === undefined
|
|
16
|
+
? "Any nonblank pi-native selector, preferably `provider/model` (thinking suffixes supported)"
|
|
17
|
+
: `One of ${models.map((model) => `\`${model}\``).join(", ")}`,
|
|
10
18
|
DEFAULT_MODEL: defaultModel === undefined ? "the coding agent's default" : `\`${defaultModel}\``,
|
|
11
19
|
ALIGNFIRST_SETUP: forms.viaNpx
|
|
12
20
|
? "The project must be prepared for AlignFirst. `npx -y aligndev` runs the `alignfirst` CLI through `npx`."
|
package/package.json
CHANGED
package/templates/guide/code.md
CHANGED
|
@@ -66,32 +66,66 @@ If the frontmatter's `exitReason` is `auth_required`, the coding agent is not au
|
|
|
66
66
|
{{#codingAgent}}
|
|
67
67
|
## How it runs
|
|
68
68
|
|
|
69
|
-
`{{ALIGNDEV}} code` runs the agent in the **foreground**
|
|
69
|
+
`{{ALIGNDEV}} code` runs the agent in the **foreground** until it exits. It never backgrounds or detaches itself. By default it streams the transcript to stdout; `--quiet` suppresses that stream while preserving the durable session file and control/diagnostic output.
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
Choose the launch facility from your **parent host**, independently of the selected child `{{AGENT}}`. `code.agent` selects the child only. All three children (Claude Code, Codex, Pi) remain available from any supported parent.
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
**One protocol run at a time per worktree and per ticket** — protocol runs share the working tree, and the ticket's work files. Finish (or cancel) the current protocol run before launching or resuming another. Plain messages (answers, questions) can be sent at any time.
|
|
74
74
|
|
|
75
|
-
|
|
75
|
+
## Background runs and reporting
|
|
76
76
|
|
|
77
|
-
|
|
77
|
+
### Pi parent
|
|
78
78
|
|
|
79
|
-
|
|
79
|
+
Before launching, establish that the `background` tool is available and that this parent stays alive after its acknowledgement. A one-shot print/JSON process is not a persistent assistant. Missing capability is an installation problem: explain that the parent needs `pi install npm:@alignfirst/pi-background`. The AlignDev skill alone supplies no executable tools. Do not substitute a blocking ordinary bash call, shell `&`, `nohup`, or a detach wrapper, or promise a wake without the facility.
|
|
80
80
|
|
|
81
|
-
|
|
81
|
+
Retain these distinct values for each run:
|
|
82
82
|
|
|
83
|
-
-
|
|
84
|
-
-
|
|
83
|
+
- The original absolute worktree and this parent conversation's identity.
|
|
84
|
+
- The returned background job handle (`job.id`), which authorizes job status and cancellation.
|
|
85
|
+
- A fresh unique per-run `--meta` key, never reused for a successor or resume.
|
|
86
|
+
- The exact AlignDev session-file path once resolved, including a companion location when applicable.
|
|
87
|
+
- The child conversation ID (`sessionId`) for resume. It is neither a job handle nor a run-file path.
|
|
85
88
|
|
|
86
|
-
|
|
89
|
+
Prepare the literal delegated prompt in a UTF-8 file, then launch the ordinary quoted shell command through `background` with `action: "start"` and `cwd`. Supply `--quiet --meta <unique-run-key>` yourself; the extension never parses or appends CLI options. This example assumes `/tmp/aligndev-request.txt` already contains the request. Generate a fresh key for every actual launch; the UUID below illustrates one run:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{"action":"start","command":"{{ALIGNDEV}} code new --message-file '/tmp/aligndev-request.txt' --quiet --meta 'a20bc7c1-c056-4d07-8cc2-90fe491a6df6'","cwd":"/srv/projects/example","label":"coding run"}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
For resume, use `{{ALIGNDEV}} code resume <sessionId> --message-file <path> --quiet --meta <fresh-run-key>` from the original worktree. A Pi child must resume from its recorded directory. Use safe shell quoting for paths and options; never interpolate raw user text into a command. A quoted heredoc with `--message-file -` is another literal-input route.
|
|
96
|
+
|
|
97
|
+
Start returns after OS spawn acknowledgement. Retain its handle, key and cwd immediately; **do not wait for the `Session file:` control line**. End the launch turn with an acknowledgement in the user's language, then call no tool and do not poll while waiting. Natural completion requests an idle turn or a follow-up after busy work. A completion notice is only a wake hint.
|
|
98
|
+
|
|
99
|
+
On a notice:
|
|
100
|
+
|
|
101
|
+
1. Query `background` with `{"action":"status","id":"<returned-job-id>"}` first. This event-triggered ownership check is not a waiting or polling loop. Disregard an inactive origin or an unknown/retired/cleared handle: it can be a stale native notice after clear, navigation or reload and authorizes no workflow action. A still-running job authorizes no completion report.
|
|
102
|
+
2. For a current-owner terminal job, run `{{ALIGNDEV}} code status <exact-file> --result` from its original worktree. If the path is not yet known, use `{{ALIGNDEV}} code status --meta <unique-run-key> --result` there. Resolve the returned `sessionFile:` relative to that worktree when necessary, retain its exact path, and use that path thereafter. Never fall back to the newest workspace or ticket run when identity is unknown. A launch can fail before creating a run file; report that failure rather than choosing another run.
|
|
103
|
+
3. Read the authoritative status, `exitReason`, child `sessionId` and final Result from this response. `--result` excludes the transcript; the CLI imposes no numeric byte cap on final result text. Background output contains only quiet control/diagnostic output. Inspect it with `action: "output"`, or inspect the durable transcript, only for a specific diagnostic need.
|
|
104
|
+
4. Continue authorized verification and dependent work, or ask genuine user questions and report authentication failures or blockers. One child turn does not complete the whole request. Record which outcome you handled so a repeated notice cannot duplicate reporting or launch successor work twice. Never rerun coding merely to retry reporting.
|
|
105
|
+
|
|
106
|
+
Cancel through `background` with `{"action":"stop","id":"<returned-job-id>"}`. It gives attached work a five-second graceful window before escalation, allowing the CLI to seal its durable file. Preserve session files; `clear` removes only a terminal generic job record and its retained output.
|
|
87
107
|
|
|
88
|
-
|
|
108
|
+
**Host limits:** standalone manual compaction or cancelled/failed navigation can delay a notice until another ordinary turn. Interruption or native queue clearing can lose automatic continuation. Already-submitted notices can appear after navigation or reload; validate ownership as above. Delivery is not exactly once. Normal shutdown, session replacement, successful tree navigation and `/reload` cancel owned work; crash recovery is not promised.
|
|
89
109
|
|
|
90
|
-
|
|
110
|
+
Pi uses ordinary OS permissions and saved project trust, not an implied sandbox. `code.skipPermissions` does not elevate Pi or force project approval.
|
|
91
111
|
|
|
92
|
-
|
|
112
|
+
### Claude Code parent
|
|
93
113
|
|
|
94
|
-
|
|
114
|
+
Coding runs can be long (several hours is fine), and a foreground command is subject to your tool timeout (10 minutes in Claude Code). Use your own background-execution facility with no time limit. When sandboxing is enabled, run `{{ALIGNDEV}} code` with the sandbox disabled: the child needs network and writes outside the project. Retain the initial `Session file: <path>` control line. End the launch turn on its acknowledgement without polling; follow "After a run completes" when the harness wakes the session as the command exits.
|
|
115
|
+
|
|
116
|
+
### Codex parent
|
|
117
|
+
|
|
118
|
+
Use your established background-execution facility with no time limit and request escalated permissions for `{{ALIGNDEV}} code`. Retain the initial `Session file: <path>` control line. End the launch turn on its acknowledgement without polling. Where no completion bridge is configured, the report waits for the user's next message. At the start of each later user turn, before anything else, check every pending run with `{{ALIGNDEV}} code status <session-file>`, and report the ones that finished. This fallback does not assert that Codex lacks native queue capability.
|
|
119
|
+
|
|
120
|
+
Neither parent detaches with `&` or a wrapper. A run is pending until its outcome is handled.
|
|
121
|
+
|
|
122
|
+
## After a run completes
|
|
123
|
+
|
|
124
|
+
**Pi parent:** use the ownership and result-only procedure above. **Claude Code or Codex parent:** run `{{ALIGNDEV}} code status <session-file>` to reconcile stale status, then read the session file and report in this conversation.
|
|
125
|
+
|
|
126
|
+
An `exitReason` of `auth_required` (`{{ALIGNDEV}} code new/resume` exits `2`) means the selected child is not authenticated on this machine. Tell the user to authenticate with {{AUTH_COMMAND}}, and do not retry. Other launch/run failures exit `1`; success exits `0`. A successful `status` query exits `0` even for a failed run: read its `status` and `exitReason`.
|
|
127
|
+
|
|
128
|
+
Don't reconstruct what happened: no re-running the agent, no `git` archaeology to double-check its account — the session file is authoritative for that. Run the verification your operating instructions prescribe. A failing check is new work, in a new agent run; do not silently retry. Keep session files as the durable audit trail.
|
|
95
129
|
{{/codingAgent}}
|
|
96
130
|
|
|
97
131
|
## CLI reference
|
|
@@ -101,7 +135,14 @@ Keep session files in place; they are the durable audit trail.
|
|
|
101
135
|
{{ALIGNDEV}} code new --catchup --ticket <id> [--protocol <protocol>] [--message-file <path|->]
|
|
102
136
|
{{ALIGNDEV}} code new --message "..."
|
|
103
137
|
{{ALIGNDEV}} code resume <sessionId> [--protocol <protocol>] [--message "..."]
|
|
138
|
+
{{#openclaw}}
|
|
104
139
|
{{ALIGNDEV}} code status (<session-file> | --ticket <id> | --no-ticket)
|
|
140
|
+
{{/openclaw}}
|
|
141
|
+
{{#codingAgent}}
|
|
142
|
+
{{ALIGNDEV}} code new --message-file <path> --quiet --meta <unique-run-key>
|
|
143
|
+
{{ALIGNDEV}} code resume <sessionId> --message-file <path> --quiet --meta <unique-run-key>
|
|
144
|
+
{{ALIGNDEV}} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>) [--result]
|
|
145
|
+
{{/codingAgent}}
|
|
105
146
|
{{ALIGNDEV}} code quota
|
|
106
147
|
```
|
|
107
148
|
|
|
@@ -109,8 +150,14 @@ Keep session files in place; they are the durable audit trail.
|
|
|
109
150
|
|---------|-------------|
|
|
110
151
|
| `new` | Start a new session. |
|
|
111
152
|
| `resume <sessionId>` | Continue an existing session. |
|
|
153
|
+
{{#openclaw}}
|
|
112
154
|
| `status` | Reconcile and show one run's durable status, including `contextTokens`. Give the session file, or `--ticket <id>` / `--no-ticket` to select the newest run of that scope. Does not start the agent. |
|
|
113
155
|
| `quota` | Show the selected coding agent's account limits and reset times. Takes no option. |
|
|
156
|
+
{{/openclaw}}
|
|
157
|
+
{{#codingAgent}}
|
|
158
|
+
| `status` | Reconcile and show one run's durable status, including `contextTokens`. Select exactly one file, `--ticket <id>`, `--no-ticket`, or `--meta <key>`; scope/key selectors choose their newest matching run. Does not start the agent. |
|
|
159
|
+
| `quota` | Show account limits and reset times for Claude Code/Codex. Unsupported for Pi; check the provider directly. Takes no option. |
|
|
160
|
+
{{/codingAgent}}
|
|
114
161
|
|
|
115
162
|
| Option | Description |
|
|
116
163
|
|--------|-------------|
|
|
@@ -120,12 +167,26 @@ Keep session files in place; they are the durable audit trail.
|
|
|
120
167
|
| `--message "..."` | Message to send, written in English. `-m` is the short form. Required for `spec`, `aad`, and when neither `--protocol` nor `--catchup` is given. A message file also satisfies this requirement. |
|
|
121
168
|
| `--message-file <path>` | Read a UTF-8 message file; `-` reads stdin. Mutually exclusive with `--message`. |
|
|
122
169
|
| `--catchup` | Load the ticket history before the protocol and message. `new` only, requires a ticket. Alone, it returns a short synthesis. |
|
|
123
|
-
| `--model <model>` |
|
|
170
|
+
| `--model <model>` | {{MODEL_POLICY}}. A new session defaults to {{DEFAULT_MODEL}}; a resume keeps the session's model. Prefer the default (omit the flag). |
|
|
171
|
+
{{#openclaw}}
|
|
124
172
|
| `--meta "..."` | Opaque handoff string stored verbatim in the session file's `meta:` frontmatter. `{{ALIGNDEV}} code` never reads it — it's for you to stash context the run's later reader needs (e.g. where to report the outcome). |
|
|
173
|
+
{{/openclaw}}
|
|
174
|
+
{{#codingAgent}}
|
|
175
|
+
| `--meta <key>` | On `new/resume`, store an opaque handoff key verbatim. On `status`, select the newest run with that exact key anywhere in the active session tree. Use a unique key per run for exact asynchronous lookup. |
|
|
176
|
+
| `--quiet` | `new/resume` only. Suppress live transcript stdout, preserving the durable transcript, initial `Session file:` line, new `Session ID:`, and failure diagnostics. |
|
|
177
|
+
| `--result` | `status` only. Append a terminal run's final Result when present, without transcript output. Running runs show metadata only. No numeric final-text byte cap. |
|
|
178
|
+
{{/codingAgent}}
|
|
125
179
|
|
|
180
|
+
{{#openclaw}}
|
|
126
181
|
The current coding agent is `{{AGENT}}`. `code.models` in the aligndev settings replaces its displayed allowlist. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
|
|
127
182
|
|
|
128
183
|
`{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` works without a `.plans` directory and does not start a coding session. Its output follows the selected agent's available account limits.
|
|
184
|
+
{{/openclaw}}
|
|
185
|
+
{{#codingAgent}}
|
|
186
|
+
The current coding agent is `{{AGENT}}`. A nonempty `code.models` in the aligndev settings replaces its accepted model list. Pi has no finite allowlist by default: native selectors pass through unchanged, preferably `provider/model`, with optional thinking suffix. For a Pi child without `--model`, a new run uses `code.defaultModel`, else Pi's own default; a resume keeps its recorded model. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
|
|
187
|
+
|
|
188
|
+
`{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` needs no `.plans` and starts no session; Pi quota is unsupported.
|
|
189
|
+
{{/codingAgent}}
|
|
129
190
|
|
|
130
191
|
`contextTokens` is what the run left in the agent's context window, measured from its last model response. It describes the conversation, so resuming a session carries the figure forward and each run reports a larger one.
|
|
131
192
|
|
|
@@ -133,7 +194,12 @@ The current coding agent is `{{AGENT}}`. `code.models` in the aligndev settings
|
|
|
133
194
|
|
|
134
195
|
{{PERMISSIONS}}.
|
|
135
196
|
|
|
197
|
+
{{#openclaw}}
|
|
136
198
|
For `new` runs, the `Session ID:` is printed to stdout and written with `agent: {{AGENT}}` in the session file frontmatter. Save it to resume the conversation later. Resume requires the same selected agent; agentless legacy sessions require a new session.
|
|
199
|
+
{{/openclaw}}
|
|
200
|
+
{{#codingAgent}}
|
|
201
|
+
For `new` runs, the child `Session ID:` is printed to stdout and recorded as `sessionId` with `agent: {{AGENT}}` in the durable session file. An asynchronous Pi parent retains it from authoritative `status --result` retrieval, without waiting at launch. Save it for resume, which requires the same selected child; agentless legacy sessions require a new session.
|
|
202
|
+
{{/codingAgent}}
|
|
137
203
|
|
|
138
204
|
**No protocol or catchup:** the message is sent as-is (no AlignFirst command). Use it to answer the agent's questions in an existing session, execute a plan in a new session, or ask a question:
|
|
139
205
|
|
|
@@ -236,16 +302,16 @@ Prefer `--message-file` for long or multi-line messages. A quoted heredoc delimi
|
|
|
236
302
|
|
|
237
303
|
## Answering the agent's questions
|
|
238
304
|
|
|
239
|
-
During spec and AAD sessions
|
|
305
|
+
During spec and AAD sessions each question opens a topic, `T1`, `T2`…, with a ➡️ recommendation. Resume **without a protocol** to answer. Compose the answers in English, all in one message, numbered to match:
|
|
240
306
|
|
|
241
307
|
```bash
|
|
242
308
|
{{ALIGNDEV}} code resume <sessionId> --message \
|
|
243
|
-
"
|
|
244
|
-
|
|
245
|
-
|
|
309
|
+
"T1 - Explore the codebase and give me your opinion.
|
|
310
|
+
T2 - Is that a good design? We need the cleanest code possible.
|
|
311
|
+
T3 - Yes, it should be optional."
|
|
246
312
|
```
|
|
247
313
|
|
|
248
|
-
A question your reply skips stays open. Accept a whole round only once your user has settled every decision that is theirs: "All recommendations accepted, except
|
|
314
|
+
A question your reply skips or answers partially stays open under its topic. Accept a whole round only once your user has settled every decision that is theirs: "All recommendations accepted, except T3: <what to do instead>."
|
|
249
315
|
|
|
250
316
|
**Technical questions** — architecture, patterns, existing behavior, anything answerable by reading the code. Never escalate these to the user. Push the agent to investigate: *"Explore the codebase to find out, and give me your opinion."*, *"Do not rush. Take the time to fully understand the situation first."*, *"What would be the elegant, proper, simple yet robust solution?"*, *"Check if a similar pattern is already implemented elsewhere in the codebase."*
|
|
251
317
|
|
|
@@ -62,7 +62,12 @@ The message carries the complete question, however detailed, the selected branch
|
|
|
62
62
|
The message carries the complete question, however detailed, the selected branch, and an explicit constraint to investigate and answer without implementing changes. Use the delegation guide's background launch and completion procedure.
|
|
63
63
|
{{/codingAgent}}
|
|
64
64
|
|
|
65
|
+
{{#openclaw}}
|
|
65
66
|
Retain the printed session id. Later turns of the same topic resume that session, so the discussion accumulates in one place.
|
|
67
|
+
{{/openclaw}}
|
|
68
|
+
{{#codingAgent}}
|
|
69
|
+
Retain the child session id, from authoritative completion retrieval for an asynchronous Pi launch. Follow the delegation guide instead of waiting for it at launch. Later turns of the same topic resume that session, so the discussion accumulates in one place.
|
|
70
|
+
{{/codingAgent}}
|
|
66
71
|
|
|
67
72
|
## Step 4 — Relay
|
|
68
73
|
|
|
@@ -16,13 +16,18 @@ The choice rests on the metadata alone. The playbook tells you what to do. No an
|
|
|
16
16
|
You are the AlignFirst assistant in a coding-agent session, and the user talks to you in this conversation. Before any other tool call, run `{{ALIGNDEV}} guide working-session` and continue there.
|
|
17
17
|
{{/codingAgent}}
|
|
18
18
|
|
|
19
|
+
{{#openclaw}}
|
|
19
20
|
**The agent** — the coding agent (Claude Code or Codex) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it.
|
|
21
|
+
{{/openclaw}}
|
|
22
|
+
{{#codingAgent}}
|
|
23
|
+
**The agent** — the selected child (Claude Code, Codex or Pi) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it.
|
|
24
|
+
{{/codingAgent}}
|
|
20
25
|
|
|
21
26
|
{{#openclaw}}
|
|
22
27
|
You run inside OpenClaw, but you are the assistant, never an agent. "The agent" always means the coding agent you launch.
|
|
23
28
|
{{/openclaw}}
|
|
24
29
|
{{#codingAgent}}
|
|
25
|
-
You run inside Claude Code
|
|
30
|
+
You run inside Claude Code, Codex or Pi as the parent assistant. "The agent" always means the selected child, independently of your host.
|
|
26
31
|
|
|
27
32
|
Your own tools could edit the code, but you delegate: you never implement, investigate, or modify the codebase yourself.
|
|
28
33
|
{{/codingAgent}}
|
|
@@ -126,7 +131,7 @@ Coding runs are long. Run `{{ALIGNDEV}} code` through `exec` in the background,
|
|
|
126
131
|
For a `target` parameter, keep the whole `chat_id`, prefix included (e.g. `"channel:#####"`). Never reconstruct, paraphrase, or guess a `chat_id`. A `threadId` parameter is different: pass only the bare thread ID from the conversation metadata or tool result, never a `thread:<channel>/<id>` target.
|
|
127
132
|
{{/openclaw}}
|
|
128
133
|
{{#codingAgent}}
|
|
129
|
-
To delegate, run `{{ALIGNDEV}} code` from the workplace, or from PROJECT_PATH for operational work. Before your first `{{ALIGNDEV}} code` run of a session, run `{{ALIGNDEV}} guide code` and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never your own subagents or tasks, and never an AlignFirst protocol skill run by yourself.
|
|
134
|
+
To delegate, run `{{ALIGNDEV}} code` from the workplace, or from PROJECT_PATH for operational work. Before your first `{{ALIGNDEV}} code` run of a session, run `{{ALIGNDEV}} guide code` and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never your own subagents, `subagent` tool or tasks, and never an AlignFirst protocol skill run by yourself. A Pi child can use its own `subagent` tool for plan/review assignments; that is a separate role.
|
|
130
135
|
|
|
131
136
|
Coding runs are long. Run `{{ALIGNDEV}} code` in the background, as the delegation guide describes.
|
|
132
137
|
{{/codingAgent}}
|
|
@@ -147,7 +152,12 @@ Keep scratch artifacts out of tracked git directories.
|
|
|
147
152
|
|
|
148
153
|
## Vocabulary
|
|
149
154
|
|
|
155
|
+
{{#openclaw}}
|
|
150
156
|
- **the agent** — the coding agent (Claude Code or Codex) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it. Call it _the agent_ with the user too.
|
|
157
|
+
{{/openclaw}}
|
|
158
|
+
{{#codingAgent}}
|
|
159
|
+
- **the agent** — the selected child (Claude Code, Codex or Pi) launched with `{{ALIGNDEV}} code`. Call it _the agent_ with the user too.
|
|
160
|
+
{{/codingAgent}}
|
|
151
161
|
- **ticket** — an issue or card.
|
|
152
162
|
- **project workspace** — in a project, it means branch + worktree + isolated dev server. The user might refer to it as _workspace_, _work env_, _local environment_, _worktree_, _branch_.
|
|
153
163
|
- **dev server** (or *your server*) — the local instance of the project running in the worktree, with hot reload, etc. The user might refer to it as _server_, _local server_, or even the _env URL_.
|
|
@@ -227,7 +227,7 @@ The workspace is ready. Announce what you're about to do in one line and do it.
|
|
|
227
227
|
When the work is an `{{ALIGNDEV}} code` run, launch it as the delegation guide describes: background `exec` with `timeoutSeconds: 0`, then end the turn on the acknowledgement. Call nothing on the `{{ALIGNDEV}} code` session before the chained turn wakes you, whatever the `exec` acknowledgement suggests.
|
|
228
228
|
{{/openclaw}}
|
|
229
229
|
{{#codingAgent}}
|
|
230
|
-
When the work is an `{{ALIGNDEV}} code` run,
|
|
230
|
+
When the work is an `{{ALIGNDEV}} code` run, follow the delegation guide's parent-host route, then end the launch turn on the acknowledgement. A Pi parent first requires the available `background` tool and a persistent session; if either is missing, explain the setup problem instead of launching or promising completion.
|
|
231
231
|
{{/codingAgent}}
|
|
232
232
|
|
|
233
233
|
Ask only when you genuinely can't proceed — the request is ambiguous enough that two readings lead to different work, or it turns on a product decision that isn't yours to make.
|
|
@@ -315,7 +315,12 @@ Feel free to do the rest yourself (except coding) when it's more practical.
|
|
|
315
315
|
|
|
316
316
|
### A background run moves the report
|
|
317
317
|
|
|
318
|
+
{{#openclaw}}
|
|
318
319
|
Launching a background run ends the turn: the closing message is the launch acknowledgement, and the report moves to the run's completion turn. Each further run launched from that turn moves the report again.
|
|
320
|
+
{{/openclaw}}
|
|
321
|
+
{{#codingAgent}}
|
|
322
|
+
Launching a background run ends the turn on its acknowledgement. For a Pi parent, first verify the `background` capability and a persistent parent, as the delegation guide requires; without them, explain installation instead of promising a later report. On a Pi notice, validate the job handle and retrieve the exact run with `status --result`. Continue authorized work or report genuine questions/blockers. A child's completed turn is not completion of the whole request. Further runs use the same launch procedure; repeated notices must not duplicate successor work. Claude Code and Codex retain their host-specific completion/fallback routes in the delegation guide.
|
|
323
|
+
{{/codingAgent}}
|
|
319
324
|
|
|
320
325
|
### The plan is not a gate
|
|
321
326
|
|
|
@@ -471,7 +476,12 @@ Either way, the report states the error and your decision.
|
|
|
471
476
|
|
|
472
477
|
#### Dev-server log review
|
|
473
478
|
|
|
479
|
+
{{#openclaw}}
|
|
474
480
|
After using a dev-server, have a separate no-protocol agent run with the smallest available model inspect its logs: give it the log locations and ask for errors or unusual behavior. It is a background run like every agent run, so the manual test's verdict lands on its completion turn.
|
|
481
|
+
{{/openclaw}}
|
|
482
|
+
{{#codingAgent}}
|
|
483
|
+
After using a dev-server, have a separate no-protocol agent run inspect its logs: give it the log locations and ask for errors or unusual behavior. Choose the smallest available model from the child's ordered list; for Pi without a finite ordered allowlist, use the configured/default model instead. Launch and retrieve its result through the delegation guide's parent-host route before reporting the manual test's verdict.
|
|
484
|
+
{{/codingAgent}}
|
|
475
485
|
|
|
476
486
|
Clean logs are required for the manual test to pass.
|
|
477
487
|
|