@pasko70/pibo 1.9.11 → 1.10.0

package/dist/loops/templates.js

@@ -0,0 +1,232 @@
+const promiseCompletePolicy = {
+    mode: 'any',
+    conditions: [{ id: 'promise-complete', type: 'pibo.loop.promise-complete' }],
+};
+const goalStatusPolicy = {
+    mode: 'any',
+    conditions: [{ id: 'goal-status', type: 'pibo.loop.goal-status' }],
+};
+const singleRunPolicy = {
+    mode: 'any',
+    conditions: [{ id: 'max-iterations', type: 'pibo.loop.max-iterations' }],
+};
+function markdown(strings) {
+    return String.raw(strings).replaceAll('\\`', '`');
+}
+export const BUILT_IN_LOOP_JOB_TEMPLATES = [
+    {
+        id: 'goal-objective',
+        name: 'Goal objective',
+        description: 'Default same-session goal loop: keep pursuing the full objective across turns until completion is proven or another stop condition is satisfied.',
+        category: 'general',
+        job: {
+            mode: 'goal',
+            name: 'Goal loop',
+            description: 'Long-running objective continued in one Pibo Session.',
+            prompt: markdown `# Objective
+
+<Describe the complete requested end state.>
+
+# Success criteria
+
+- <Observable completion criterion>
+- <Required verification>
+- <Behavior that must not regress>
+
+# Constraints
+
+- <Scope, safety, or approval boundary>`,
+            stopPolicy: goalStatusPolicy,
+        },
+    },
+    {
+        id: 'prd-single-story-standard',
+        name: 'PRD single story standard',
+        description: 'Legacy Ralph loop: pick the highest-priority failing PRD user story, implement exactly one story, test, commit, update progress, then stop or continue on the next run.',
+        category: 'prd',
+        job: {
+            mode: 'ralph',
+            name: 'Ralph PRD single story',
+            description: 'One PRD user story per Loop iteration.',
+            prompt: markdown `# Ralph Auftrag: <Project / Change Name>
+
+## Worktree
+
+Work from the host worktree, not from a container copy:
+
+\`\`\`bash
+cd <host-worktree>
+\`\`\`
+
+Branch: \`<branch-name>\`  
+Base: \`<base-branch-or-commit>\`  
+PRDs: \`<path-to-prds>/prd_*.json\`  
+Progress log: \`<path-to-prds>/progress.txt\`
+
+If a container is required for build, gateway, or browser checks, use it only for running commands. Edit files and run git commands in the host worktree. Do not edit \`/app\` inside a container.
+
+## Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project.
+
+### Your Task
+
+1. Work from the host worktree above.
+2. Read all PRD JSON files matching \`<path-to-prds>/prd_*.json\`.
+3. Read the progress log. If it does not exist, create it.
+4. Read the \`## Codebase Patterns\` section at the top of the progress log if present.
+5. Pick the highest-priority user story where \`passes: false\`.
+6. Implement that single user story only.
+7. Run quality checks:
+   - Always run \`npm run typecheck\`.
+   - Run relevant tests for touched areas.
+   - For UI stories, run browser verification in the configured dev container/browser environment.
+8. If checks pass, update the PRD JSON to set \`passes: true\` for the completed story.
+9. Commit all changes from the host worktree with message:
+   \`feat: [Story ID] - [Story Title]\`
+10. Append your progress to the progress log.
+
+### Progress Report Format
+
+Append to the progress log. Never replace; always append.
+
+\`\`\`md
+## [Date/Time] - [Story ID]
+- What was implemented
+- Files changed
+- Quality checks run
+- Browser verification, if UI changed
+- **Learnings for future iterations:**
+  - Patterns discovered
+  - Gotchas encountered
+  - Useful context
+---
+\`\`\`
+
+### Consolidate Patterns
+
+If you discover a reusable pattern, add it to the \`## Codebase Patterns\` section at the top of the progress log. Only add general reusable patterns, not story-specific notes.
+
+## Quality Requirements
+
+- All commits must pass quality checks.
+- Do not commit broken code.
+- Keep changes focused and minimal.
+- Follow existing code patterns.
+- For UI stories, browser verification is mandatory.
+
+## Stop Condition
+
+After completing one user story, check whether all stories in all PRD JSON files have \`passes: true\`.
+
+If all stories are complete and passing, reply with the XML completion marker on its own line. Compose it from the opening tag \`<promise>\`, the word \`COMPLETE\`, and the closing tag \`</promise>\`.
+
+Do not quote, negate, explain, or mention that literal marker unless all stories are complete and you intend to stop the job. If any story remains with \`passes: false\`, end normally so another iteration can pick up the next story and say only that the completion marker was omitted.`,
+            stopPolicy: promiseCompletePolicy,
+        },
+    },
+    {
+        id: 'prd-batch-stories',
+        name: 'PRD batch stories',
+        description: 'Batch loop: implement several failing PRD user stories in priority order in one Loop run, committing after each completed story.',
+        category: 'prd',
+        job: {
+            mode: 'ralph',
+            name: 'Ralph PRD batch',
+            description: 'Multiple PRD user stories per Loop run.',
+            prompt: markdown `# Ralph Auftrag: <Project / Change Name> Batch
+
+## Worktree
+
+Work from the host worktree:
+
+\`\`\`bash
+cd <host-worktree>
+\`\`\`
+
+PRDs: \`<path-to-prds>/prd_*.json\`  
+Progress log: \`<path-to-prds>/progress.txt\`  
+Batch limit: \`<max-stories-this-run>\`
+
+## Task
+
+1. Read the PRD JSON files and progress log.
+2. Work through failing user stories in priority order.
+3. Complete up to \`<max-stories-this-run>\` stories in this run.
+4. Keep each story isolated:
+   - implement one story;
+   - run relevant checks;
+   - set that story's \`passes\` to \`true\` only after checks pass;
+   - commit with \`feat: [Story ID] - [Story Title]\`;
+   - append a progress-log entry.
+5. Stop early if a story is blocked, ambiguous, or tests fail. Do not continue with later stories after a failed story.
+
+## Quality Requirements
+
+- Always run \`npm run typecheck\` before each story commit unless the repository has a documented narrower check for this batch.
+- Run relevant tests for touched areas.
+- Browser verification is mandatory for UI changes.
+- Keep changes focused; do not bundle unrelated refactors.
+
+## Stop Condition
+
+If all stories in all PRD JSON files are complete and passing, reply with the XML completion marker on its own line. Compose it from the opening tag \`<promise>\`, the word \`COMPLETE\`, and the closing tag \`</promise>\`.
+
+Do not quote, negate, explain, or mention that literal marker unless all stories are complete and you intend to stop the job. Otherwise report the stories completed and the next remaining failing story, and say only that the completion marker was omitted.`,
+            stopPolicy: promiseCompletePolicy,
+        },
+    },
+    {
+        id: 'single-run-objective',
+        name: 'Single-run objective',
+        description: 'Non-PRD template for one focused objective with explicit done criteria. Stops after one completed run attempt by max-iterations.',
+        category: 'general',
+        job: {
+            mode: 'ralph',
+            name: 'Ralph single-run objective',
+            description: 'One focused non-PRD objective.',
+            maxIterations: 1,
+            stopPolicy: singleRunPolicy,
+            prompt: markdown `# Ralph Auftrag: <Objective>
+
+## Worktree
+
+\`\`\`bash
+cd <host-worktree>
+\`\`\`
+
+Branch: \`<branch-name>\`
+
+## Objective
+
+<Describe the concrete outcome.>
+
+## Done Criteria
+
+- <Pass/fail criterion 1>
+- <Pass/fail criterion 2>
+- <Required verification command or manual check>
+
+## Instructions
+
+1. Inspect the relevant code and docs before editing.
+2. State assumptions in code comments or docs only when they matter for maintainers.
+3. Implement the smallest focused change that satisfies the done criteria.
+4. Run \`npm run typecheck\` and relevant tests.
+5. Commit with a concise message if checks pass.
+6. End with a short report listing files changed and verification run.
+
+This is not a PRD loop. Do not edit PRD JSON progress unless the objective explicitly asks for it.`,
+        },
+    },
+];
+export function listLoopJobTemplates() {
+    return BUILT_IN_LOOP_JOB_TEMPLATES.map((template) => cloneTemplate(template));
+}
+export function getLoopJobTemplate(id) {
+    const template = BUILT_IN_LOOP_JOB_TEMPLATES.find((item) => item.id === id);
+    return template ? cloneTemplate(template) : undefined;
+}
+function cloneTemplate(template) {
+    return JSON.parse(JSON.stringify(template));
+}

package/dist/loops/tools.js

@@ -0,0 +1,167 @@
+import { StringEnum, Type } from '@earendil-works/pi-ai';
+import { defineTool } from '@earendil-works/pi-coding-agent';
+import { createDefaultPiboLoopStore } from './store.js';
+export const PIBO_GOAL_TOOL_NAMES = ['get_goal', 'create_goal', 'update_goal'];
+let configuredStorePath;
+export function configurePiboGoalToolStorePath(path) {
+    configuredStorePath = path;
+}
+function toolResult(value, isError = false) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        details: value,
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function errorResult(error) {
+    return toolResult({ ok: false, error: error instanceof Error ? error.message : String(error) }, true);
+}
+function requireSessionContext(context) {
+    const piboSessionId = context.piboSessionId?.trim();
+    if (!piboSessionId)
+        throw new Error('Goal tools require the current Pibo Session ID');
+    return {
+        piboSessionId,
+        piboRoomId: context.piboRoomId?.trim() || undefined,
+        profileName: context.profileName?.trim() || 'base',
+    };
+}
+function positiveInteger(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 1)
+        throw new Error(`${field} must be a positive integer`);
+    return value;
+}
+function goalPayload(job) {
+    const tokensUsed = job.state.tokensUsed ?? 0;
+    const tokenBudget = job.tokenBudget;
+    return {
+        goalId: job.id,
+        objective: job.prompt,
+        status: effectiveGoalStatus(job),
+        tokenBudget: tokenBudget ?? null,
+        tokensUsed,
+        remainingTokens: tokenBudget === undefined ? null : Math.max(0, tokenBudget - tokensUsed),
+        timeUsedSeconds: job.state.timeUsedSeconds ?? 0,
+    };
+}
+function effectiveGoalStatus(job) {
+    return job.state.goalStatus ?? (job.enabled ? 'active' : 'paused');
+}
+async function withStore(options, action) {
+    if (options.store)
+        return await action(options.store);
+    const store = createDefaultPiboLoopStore({ path: configuredStorePath });
+    try {
+        return await action(store);
+    }
+    finally {
+        store.close();
+    }
+}
+function createGetGoalTool(context, options) {
+    return defineTool({
+        name: 'get_goal',
+        label: 'Get Goal',
+        description: 'Get the current goal for this Pibo Session, including status, token budget, consumed tokens, remaining tokens, and elapsed active time.',
+        promptSnippet: 'Use get_goal when you need the authoritative persisted status or accounting for the current Pibo Session goal.',
+        parameters: Type.Object({}),
+        async execute() {
+            try {
+                const { piboSessionId } = requireSessionContext(context);
+                return await withStore(options, (store) => {
+                    const job = store.getLatestGoalForSession(piboSessionId);
+                    return toolResult({ ok: true, goal: job ? goalPayload(job) : null });
+                });
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        },
+    });
+}
+function createCreateGoalTool(context, options) {
+    return defineTool({
+        name: 'create_goal',
+        label: 'Create Goal',
+        description: 'Create an active persisted Goal Loop for this Pibo Session only when explicitly requested. Fails while this session already has an unfinished goal.',
+        promptSnippet: 'Call create_goal only when the user or system explicitly requests a persistent goal. Do not infer a goal from an ordinary task.',
+        parameters: Type.Object({
+            objective: Type.String({ description: 'Concrete objective to pursue across automatic continuations.' }),
+            token_budget: Type.Optional(Type.Number({ description: 'Optional positive token budget. Omit unless explicitly requested.' })),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const session = requireSessionContext(context);
+                const objective = params.objective?.trim();
+                if (!objective)
+                    throw new Error('objective is required');
+                const tokenBudget = positiveInteger(params.token_budget, 'token_budget');
+                return await withStore(options, (store) => {
+                    const existing = store.getLatestGoalForSession(session.piboSessionId);
+                    if (existing && effectiveGoalStatus(existing) !== 'complete') {
+                        throw new Error('cannot create a new goal because this Pibo Session has an unfinished goal; complete the existing goal first');
+                    }
+                    const job = store.createJob({
+                        mode: 'goal',
+                        enabled: true,
+                        target: session.piboRoomId ? { kind: 'room', roomId: session.piboRoomId } : { kind: 'default-chat' },
+                        profile: session.profileName,
+                        prompt: objective,
+                        tokenBudget,
+                        initialPiboSessionId: session.piboSessionId,
+                    });
+                    return toolResult({ ok: true, goal: goalPayload(job) });
+                });
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        },
+    });
+}
+function createUpdateGoalTool(context, options) {
+    return defineTool({
+        name: 'update_goal',
+        label: 'Update Goal',
+        description: 'Mark the current goal complete or genuinely blocked. Complete requires verified achievement. Blocked requires the same impasse for at least three consecutive goal turns.',
+        promptSnippet: 'Use update_goal only with status complete after a requirement-by-requirement completion audit, or blocked after the strict repeated-blocker audit.',
+        parameters: Type.Object({
+            status: StringEnum(['complete', 'blocked'], { description: 'Terminal status for the current goal.' }),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const { piboSessionId } = requireSessionContext(context);
+                if (params.status !== 'complete' && params.status !== 'blocked')
+                    throw new Error('status must be complete or blocked');
+                const status = params.status;
+                return await withStore(options, (store) => {
+                    const existing = store.getLatestGoalForSession(piboSessionId);
+                    if (!existing)
+                        throw new Error('cannot update goal because this Pibo Session has no goal');
+                    const job = store.updateGoalStatus(existing.id, status);
+                    if (!job)
+                        throw new Error('goal no longer exists');
+                    return toolResult({
+                        ok: true,
+                        goal: goalPayload(job),
+                        ...(status === 'complete' && job.tokenBudget !== undefined
+                            ? { completionBudgetReport: `${job.state.tokensUsed ?? 0}/${job.tokenBudget} reported tokens consumed before the current model turn finishes` }
+                            : {}),
+                    });
+                });
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        },
+    });
+}
+export function createPiboGoalToolDefinitions(context, options = {}) {
+    return [
+        createGetGoalTool(context, options),
+        createCreateGoalTool(context, options),
+        createUpdateGoalTool(context, options),
+    ];
+}

package/dist/loops/types.js

@@ -0,0 +1 @@
+export {};

package/dist/plugins/builtin.js

@@ -112,6 +112,7 @@ function requireLogoutParams(event) {
 }
 function createBaseProfileBuilder(profileName, context) {
     return addPiboNativeToolingContext(new InitialSessionContextBuilder(profileName)
+        .withToolPackages({ goalControl: true })
         .addSkill(context.getSkill("pi-agent-harness")), context);
 }
 export const piboCorePlugin = definePiboPlugin({
@@ -148,6 +149,11 @@ export const piboCorePlugin = definePiboPlugin({
             path: builtinSkillPath("skill-creator"),
             kind: "builtin",
         });
+        api.registerSkill({
+            name: "loop",
+            path: builtinSkillPath("loop"),
+            kind: "builtin",
+        });
         api.registerSkill({
             name: "ralph-loop",
             path: builtinSkillPath("ralph-loop"),
@@ -167,6 +173,7 @@ export const piboCorePlugin = definePiboPlugin({
             create() {
                 return new InitialSessionContextBuilder(DEFAULT_PIBO_PROFILE_NAME)
                     .withBuiltinToolNames(["read", "bash", "edit", "write"])
+                    .withToolPackages({ goalControl: true })
                     .createSession();
             },
         });
@@ -451,6 +458,7 @@ export function selectDefaultPiboProfileName(registry) {
 export function createDefaultPiboProfile() {
     return new InitialSessionContextBuilder(DEFAULT_PIBO_PROFILE_NAME)
         .withBuiltinToolNames(["read", "bash", "edit", "write"])
+        .withToolPackages({ goalControl: true })
         .createSession();
 }
 export function resolvePiboProfileNameFromRegistryOrDefault(registry, profileName) {

package/dist/plugins/registry.js

@@ -33,7 +33,7 @@ export class PiboPluginRegistry {
     capabilityPackages = new Map();
     eventListeners = new Set();
     productEventListeners = new Set();
-    ralphStopConditions = new Map();
+    loopStopConditions = new Map();
     pluginIds = new Set();
     pluginNames = new Map();
     eventErrors = [];
@@ -133,20 +133,22 @@ export class PiboPluginRegistry {
     registerCapabilityPackage(pkg) {
         this.addUnique(this.capabilityPackages, pkg.name, { ...pkg, toolNames: [...pkg.toolNames] }, "capability package");
     }
-    registerRalphStopCondition(condition, pluginId) {
+    registerLoopStopCondition(condition, pluginId) {
         if (!condition.type.trim())
-            throw new Error('Ralph stop condition type is required');
+            throw new Error('Loop stop condition type is required');
         if (!condition.name.trim())
-            throw new Error(`Ralph stop condition "${condition.type}" name is required`);
+            throw new Error(`Loop stop condition "${condition.type}" name is required`);
         if (condition.phases.length === 0)
-            throw new Error(`Ralph stop condition "${condition.type}" must support at least one phase`);
-        this.addUnique(this.ralphStopConditions, condition.type, { definition: { ...condition, phases: [...condition.phases] }, pluginId }, 'Ralph stop condition');
+            throw new Error(`Loop stop condition "${condition.type}" must support at least one phase`);
+        this.addUnique(this.loopStopConditions, condition.type, { definition: { ...condition, phases: [...condition.phases] }, pluginId }, 'Loop stop condition');
     }
-    getRalphStopConditionDefinitions() {
-        return [...this.ralphStopConditions.values()].map((entry) => entry.definition);
+    registerRalphStopCondition(condition, pluginId) { this.registerLoopStopCondition(condition, pluginId); }
+    getLoopStopConditionDefinitions() {
+        return [...this.loopStopConditions.values()].map((entry) => entry.definition);
     }
-    getRalphStopConditionInfos() {
-        return [...this.ralphStopConditions.values()].map((entry) => ({
+    getRalphStopConditionDefinitions() { return this.getLoopStopConditionDefinitions(); }
+    getLoopStopConditionInfos() {
+        return [...this.loopStopConditions.values()].map((entry) => ({
             type: entry.definition.type,
             name: entry.definition.name,
             description: entry.definition.description,
@@ -157,6 +159,7 @@ export class PiboPluginRegistry {
             pluginName: entry.pluginId ? this.pluginNames.get(entry.pluginId) : undefined,
         }));
     }
+    getRalphStopConditionInfos() { return this.getLoopStopConditionInfos(); }
     onEvent(listener) {
         this.eventListeners.add(listener);
     }
@@ -203,6 +206,7 @@ export class PiboPluginRegistry {
                 builtinToolNames: [...sessionContext.builtinToolNames],
                 autoContextFiles: sessionContext.autoContextFiles,
                 runControl: sessionContext.toolPackages.runControl === true,
+                goalControl: sessionContext.toolPackages.goalControl !== false,
             };
         });
     }
@@ -255,6 +259,11 @@ export class PiboPluginRegistry {
                         "pibo_run_ack",
                     ],
                 },
+                {
+                    name: "pibo-goal-control",
+                    description: "Expose get_goal, create_goal, and update_goal as one native goal lifecycle package.",
+                    toolNames: ["get_goal", "create_goal", "update_goal"],
+                },
                 ...[...this.capabilityPackages.values()].map((pkg) => ({
                     ...pkg,
                     toolNames: [...pkg.toolNames],
@@ -264,7 +273,8 @@ export class PiboPluginRegistry {
             piboTools: listInstalledCliToolAgentContexts(),
             mcpServers: [],
             piPackages: listPiPackages(),
-            ralphStopConditions: this.getRalphStopConditionInfos(),
+            loopStopConditions: this.getLoopStopConditionInfos(),
+            ralphStopConditions: this.getLoopStopConditionInfos(),
         };
     }
     resolveProfileName(name) {
@@ -355,7 +365,8 @@ export class PiboPluginRegistry {
             registerAuthService: (service) => this.registerAuthService(service),
             registerWebApp: (app) => this.registerWebApp(app),
             registerCapabilityPackage: (pkg) => this.registerCapabilityPackage(withPluginPackageContext(pkg)),
-            registerRalphStopCondition: (condition) => this.registerRalphStopCondition(condition, pluginId),
+            registerLoopStopCondition: (condition) => this.registerLoopStopCondition(condition, pluginId),
+            registerRalphStopCondition: (condition) => this.registerLoopStopCondition(condition, pluginId),
             onEvent: (listener) => this.onEvent(listener),
             emitProductEvent: (event) => this.emitProductEvent(event),
             onProductEvent: (listener) => this.onProductEvent(listener),

package/dist/resources/lifecycle.js

@@ -243,15 +243,13 @@ function buildBrowserReapPlanItem(record, now, idleTimeoutMinutes) {
         preservesWorktree: true,
     };
 }
-async function planComputeReapSafely(options) {
+export async function planComputeReapSafely(options, planCompute = planReapWorkers) {
     try {
-        return await planReapWorkers(options);
+        return await planCompute(options);
     }
-    catch (error) {
-        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
-            throw error;
+    catch {
         const plan = buildComputeWorkerReapPlan([], options);
-        plan.nextCommands = ["Docker CLI is unavailable in this runtime; browser and stale-file cleanup remain active."];
+        plan.nextCommands = ["Docker compute cleanup is unavailable; browser and stale-file cleanup remain active."];
         return plan;
     }
 }

package/dist/resources/reaper-state.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -5,11 +6,37 @@ import { piboHomePath } from "../core/pibo-home.js";
 export function defaultResourceReaperStatePath() {
     return process.env.PIBO_RESOURCE_REAPER_STATE_PATH || piboHomePath("resource-reaper-state.json");
 }
-export async function writeResourceReaperState(path, state) {
+const DEFAULT_RENAME_RETRY_DELAYS_MS = [10, 25, 50, 100, 200];
+const TRANSIENT_RENAME_ERROR_CODES = new Set(["EACCES", "EBUSY", "ENOTEMPTY", "EPERM"]);
+export async function writeResourceReaperState(path, state, options = {}) {
     await mkdir(dirname(path), { recursive: true });
-    const temporaryPath = `${path}.${process.pid}.tmp`;
+    const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const renameFile = options.rename ?? rename;
+    const wait = options.wait ?? defaultWait;
+    const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RENAME_RETRY_DELAYS_MS;
     await writeFile(temporaryPath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
-    await rename(temporaryPath, path);
+    try {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await renameFile(temporaryPath, path);
+                return;
+            }
+            catch (error) {
+                if (!isTransientRenameError(error) || attempt >= retryDelaysMs.length)
+                    throw error;
+                await wait(retryDelaysMs[attempt]);
+            }
+        }
+    }
+    finally {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+function isTransientRenameError(error) {
+    return error instanceof Error && "code" in error && TRANSIENT_RENAME_ERROR_CODES.has(String(error.code));
+}
+async function defaultWait(delayMs) {
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
 }
 export async function claimResourceReaperOwnership(lockPath, pid = process.pid, isPidAlive = defaultIsPidAlive) {
     await mkdir(dirname(lockPath), { recursive: true });