@pushpalsdev/cli 1.0.17 → 1.0.19

package/runtime/sandbox/packages/shared/src/vision.ts

@@ -0,0 +1,247 @@
+const SECTION_HEADING_RE = /^##\s+(\d+)\)\s+(.+?)\s*$/;
+const ANY_HEADING_RE = /^##+\s+(.+?)\s*$/;
+const ONE_SENTENCE_PROMPT_RE = /^\>\s*\*\*One sentence:\*\*\s*(.+)\s*$/i;
+const BLOCKQUOTE_RE = /^\>\s*(.+?)\s*$/;
+const BULLET_RE = /^\s*(?:[-*]|\d+\.)\s+(.+?)\s*$/;
+
+export type VisionSection = {
+  number: string;
+  title: string;
+  markdown: string;
+};
+
+export type ParsedVisionDoc = {
+  oneSentence: string;
+  sections: VisionSection[];
+  sectionByNumber: Record<string, VisionSection>;
+};
+
+export type VisionKeyItems = {
+  targetUsers: string[];
+  priorities: string[];
+  objectives: string[];
+  guardrails: string[];
+  constraints: string[];
+  nonGoals: string[];
+  metrics: string[];
+  riskPolicy: string[];
+  operatingModel: string[];
+  governance: string[];
+};
+
+export type VisionDocValidation = {
+  ok: boolean;
+  sectionCount: number;
+  hasOneSentence: boolean;
+  missingSectionNumbers: string[];
+  errors: string[];
+};
+
+const MAX_KEY_ITEMS_PER_BUCKET = 8;
+
+function toLines(markdown: string): string[] {
+  return String(markdown ?? "").replace(/\r\n/g, "\n").split("\n");
+}
+
+function extractOneSentence(lines: string[]): string {
+  let expectNextBlockquoteSentence = false;
+  for (const line of lines) {
+    const marker = line.match(ONE_SENTENCE_PROMPT_RE);
+    if (marker) {
+      const inline = marker[1].trim();
+      if (inline) return inline;
+      expectNextBlockquoteSentence = true;
+      continue;
+    }
+    const block = line.match(BLOCKQUOTE_RE);
+    if (expectNextBlockquoteSentence) {
+      if (!block) continue;
+      const text = block[1].trim();
+      if (!text) continue;
+      if (/^Example:/i.test(text)) continue;
+      return text;
+    }
+  }
+  for (const line of lines) {
+    const block = line.match(BLOCKQUOTE_RE);
+    if (!block) continue;
+    const text = block[1].trim();
+    if (!text) continue;
+    if (/^\*\*One sentence:\*\*/i.test(text)) continue;
+    if (/^Example:/i.test(text)) continue;
+    return text;
+  }
+  return "";
+}
+
+function normalizeItem(value: string): string {
+  return String(value ?? "").replace(/\s+/g, " ").trim();
+}
+
+function dedupeAndClamp(values: string[]): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of values) {
+    const value = normalizeItem(raw);
+    if (!value) continue;
+    const key = value.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(value);
+    if (out.length >= MAX_KEY_ITEMS_PER_BUCKET) break;
+  }
+  return out;
+}
+
+function classifyHeadingBucket(heading: string): keyof VisionKeyItems | null {
+  const text = heading.toLowerCase();
+  if (text.includes("who this is for") || text.includes("user")) return "targetUsers";
+  if (text.includes("priorit")) return "priorities";
+  if (text.includes("objective")) return "objectives";
+  if (text.includes("principle") || text.includes("guardrail")) return "guardrails";
+  if (text.includes("constraint")) return "constraints";
+  if (text.includes("non-goal") || text.includes("out of scope") || text.includes("not ")) {
+    return "nonGoals";
+  }
+  if (text.includes("measure") || text.includes("metric") || text.includes("good looks like")) {
+    return "metrics";
+  }
+  if (text.includes("risk") || text.includes("gate")) return "riskPolicy";
+  if (text.includes("operating model") || text.includes("role")) return "operatingModel";
+  if (text.includes("decision") || text.includes("governance")) return "governance";
+  return null;
+}
+
+export function normalizeVisionSectionRef(value: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) return "";
+  const match = text.match(/\d+/);
+  if (!match) return "";
+  const numeric = Number.parseInt(match[0], 10);
+  return Number.isFinite(numeric) && numeric > 0 ? String(numeric) : "";
+}
+
+export function normalizeVisionSectionRefs(
+  values: string[],
+  allowedSectionNumbers?: ReadonlySet<string>,
+): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const value of values) {
+    const normalized = normalizeVisionSectionRef(value);
+    if (!normalized) continue;
+    if (allowedSectionNumbers && !allowedSectionNumbers.has(normalized)) continue;
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
+export function parseVisionDoc(markdown: string): ParsedVisionDoc {
+  const lines = toLines(markdown);
+  const sections: VisionSection[] = [];
+  let currentNumber = "";
+  let currentTitle = "";
+  let currentBody: string[] = [];
+
+  const flushCurrent = (): void => {
+    if (!currentNumber) return;
+    sections.push({
+      number: currentNumber,
+      title: currentTitle,
+      markdown: currentBody.join("\n").trim(),
+    });
+    currentNumber = "";
+    currentTitle = "";
+    currentBody = [];
+  };
+
+  for (const line of lines) {
+    const heading = line.match(SECTION_HEADING_RE);
+    if (heading) {
+      flushCurrent();
+      currentNumber = heading[1];
+      currentTitle = heading[2].trim();
+      continue;
+    }
+    if (currentNumber) {
+      currentBody.push(line);
+    }
+  }
+  flushCurrent();
+
+  const sectionByNumber: Record<string, VisionSection> = {};
+  for (const section of sections) {
+    if (!sectionByNumber[section.number]) {
+      sectionByNumber[section.number] = section;
+    }
+  }
+
+  return {
+    oneSentence: extractOneSentence(lines),
+    sections,
+    sectionByNumber,
+  };
+}
+
+export function extractVisionKeyItems(markdown: string): VisionKeyItems {
+  const lines = toLines(markdown);
+  const buckets: VisionKeyItems = {
+    targetUsers: [],
+    priorities: [],
+    objectives: [],
+    guardrails: [],
+    constraints: [],
+    nonGoals: [],
+    metrics: [],
+    riskPolicy: [],
+    operatingModel: [],
+    governance: [],
+  };
+
+  let activeBucket: keyof VisionKeyItems | null = null;
+  for (const line of lines) {
+    const heading = line.match(ANY_HEADING_RE);
+    if (heading) {
+      activeBucket = classifyHeadingBucket(heading[1]);
+      continue;
+    }
+
+    const bullet = line.match(BULLET_RE);
+    if (!bullet) continue;
+    if (!activeBucket) continue;
+    buckets[activeBucket].push(bullet[1]);
+  }
+
+  return {
+    targetUsers: dedupeAndClamp(buckets.targetUsers),
+    priorities: dedupeAndClamp(buckets.priorities),
+    objectives: dedupeAndClamp(buckets.objectives),
+    guardrails: dedupeAndClamp(buckets.guardrails),
+    constraints: dedupeAndClamp(buckets.constraints),
+    nonGoals: dedupeAndClamp(buckets.nonGoals),
+    metrics: dedupeAndClamp(buckets.metrics),
+    riskPolicy: dedupeAndClamp(buckets.riskPolicy),
+    operatingModel: dedupeAndClamp(buckets.operatingModel),
+    governance: dedupeAndClamp(buckets.governance),
+  };
+}
+
+export function validateVisionDocStructure(markdown: string): VisionDocValidation {
+  const parsed = parseVisionDoc(markdown);
+  const missingSectionNumbers: string[] = [];
+  const errors: string[] = [];
+  if (!parsed.oneSentence) {
+    errors.push(
+      'Missing one-sentence vision line (expected near the top as a blockquote after "**One sentence:**").',
+    );
+  }
+  return {
+    ok: errors.length === 0,
+    sectionCount: parsed.sections.length,
+    hasOneSentence: Boolean(parsed.oneSentence),
+    missingSectionNumbers,
+    errors,
+  };
+}

package/runtime/sandbox/packages/shared/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "lib": ["ES2020"],
+    "types": ["bun"],
+    "strict": true,
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/runtime/sandbox/prompts/workerpals/codex_quality_critic_instruction_prompt.md

@@ -0,0 +1,14 @@
+You are a strict code review critic. Return ONLY a valid JSON object with exactly these keys:
+{"score": <number 0-10>, "findings": [<string>], "must_fix": [<string>], "revision_guidance": "<string>"}
+Do not output any prose, explanation, or markdown - only the JSON object.
+
+Task: {{instruction}}
+
+Acceptance criteria:
+{{acceptance_criteria}}
+
+Changed paths: {{changed_paths}}
+
+{{diff_section}}
+
+{{validation_section}}

package/runtime/sandbox/prompts/workerpals/commit_message_prompt.md

@@ -0,0 +1,36 @@
+You are a commit message writer for a TypeScript/Bun monorepo. Write a rich, specific conventional commit message based on the staged diff provided by the user.
+
+Output only the raw commit message text — no markdown fences, no explanation, no prose outside the message.
+
+## Required format
+
+{{type}}({{area}}): <summary ≤72 chars, imperative mood, no trailing period>
+
+- <specific implementation detail>
+- <specific implementation detail>
+
+Tests:
+- <test runner command>
+
+## Writing rules
+
+- **Subject line**: read the diff and describe what it actually does — never copy, paraphrase, or echo the background context; if the diff adds a test for request routing, say "add test for request routing"; if it adds tests and reorganizes helpers, say both
+- **Bullets**: each must name specific functions, files, assertions, or behaviors visible in the diff — do NOT use planning/acceptance-criteria language such as "at least one test is added", "all tests pass", "no unrelated files are modified", or "should validate"
+- **Tests**: include only recognizable test runner commands from the provided validation steps (bun test, pytest, npm test, etc.); write `- not run` if none
+- **Count**: 3–6 bullets; each under 120 characters
+
+## Bad vs good example
+
+Background context: "can you add one more unit test for localbuddy"
+
+Bad (copies instruction / uses planning language):
+{{type}}({{area}}): lets add one more unit test for localbuddy
+- At least one new unit test is added validating a meaningful LocalBuddy behavior.
+- All existing and new tests pass.
+- No unrelated files are modified.
+
+Good (reads the diff):
+{{type}}({{area}}): add unit test for LocalBuddy request routing and error response handling
+- add test case in localbuddy.test.ts asserting router returns 404 for unknown tool calls
+- add negative test for malformed request payload returning 400 with error message
+- extract shared test fixtures into testHelpers.ts to reduce duplication

package/runtime/sandbox/prompts/workerpals/commit_message_user_prompt.md

@@ -0,0 +1,7 @@
+Staged diff (derive subject line and all bullets from this):
+{{diff_excerpt}}
+
+Validation steps (for Tests section only):
+{{test_lines}}
+
+Background context (do not restate in subject or bullets): {{instruction_excerpt}}

package/runtime/sandbox/prompts/workerpals/miniswe_broker_system_prompt.md

@@ -0,0 +1,33 @@
+You are a code-changing assistant operating on a local git repository.
+You DO NOT have native tool/function calling. Instead, you must output a STRICT JSON object describing actions.
+
+Repository root: {{repo}}
+
+Output format (STRICT JSON, no markdown, no extra keys unless specified):
+{
+  "actions": [
+    {"type":"read_file","path":"README.md"},
+    {"type":"append_line","path":"README.md","line":"..."},
+    {"type":"replace_text_once","path":"x","old":"a","new":"b"},
+    {"type":"write_file","path":"x","content":"..."},
+    {"type":"run_shell","command":"git status --porcelain"}
+  ],
+  "done": false,
+  "note": "short explanation"
+}
+
+Rules:
+- Keep actions minimal and directly relevant.
+- JSON syntax must be exact: use ":" between keys and values, never ",".
+- Use double quotes for all keys and string values.
+- Paths must be repo-relative.
+- run_shell safety: no pipes/redirection/chaining; issue one simple command per action.
+- Allowed run_shell binaries: git, bun, npm, cat, tail, head, ls, find, rg, grep, sed, awk, wc, stat, printf, echo, test.
+- For this repository, prefer `bun test` / `bun run <script>` over npm.
+- Use read_file before edit when unsure.
+- After edits, run_shell: "git status --porcelain".
+- If the instruction is a bounded edit over explicit file paths, complete all requested edits in one response when possible.
+- Progress requirement: do not spend more than 2 steps on exploration; then perform an edit action.
+- If blocked from editing after exploration, set done=true and explain the blocker in note.
+- Do not stop after partially applying explicit directives; only set done=true after all requested edits are handled.
+- When task is complete, set done=true and keep actions empty or only verification commands.

package/runtime/sandbox/prompts/workerpals/miniswe_broker_task_prompt.md

@@ -0,0 +1,5 @@
+Task:
+{{instruction}}
+{{explicit_targets_block}}
+{{completion_requirement}}
+Start now. Output STRICT JSON only.

package/runtime/sandbox/prompts/workerpals/miniswe_completion_requirement.md

@@ -0,0 +1 @@
+Completion requirement: handle all requested edits across all explicit target paths before setting done=true.

package/runtime/sandbox/prompts/workerpals/miniswe_context_compaction_retry_prompt.md

@@ -0,0 +1 @@
+Context was compacted after timeout. Continue from the latest observation and current repository state. Return STRICT JSON only.

package/runtime/sandbox/prompts/workerpals/miniswe_explicit_targets_block.md

@@ -0,0 +1,2 @@
+Explicit target paths:
+{{targets_block}}

package/runtime/sandbox/prompts/workerpals/miniswe_recovery_guidance_base.md

@@ -0,0 +1,4 @@
+Recovery mode: complete the task in one pass with minimal actions.
+Prefer at most 3 actions: read target file(s), apply edit(s), run `git status --porcelain`.
+Do not perform broad exploration.
+Set done=true in the same response after applying edits.

package/runtime/sandbox/prompts/workerpals/miniswe_recovery_guidance_blocker_line.md

@@ -0,0 +1 @@
+If no edit is possible, set done=true and explain the blocker in note.

package/runtime/sandbox/prompts/workerpals/miniswe_strict_tool_use_guidance.md

@@ -0,0 +1,6 @@
+CRITICAL: You must use tools to make progress.
+- Use the environment's tools (file read/list/search, and file edit/write/patch) to inspect and modify the repo.
+- Do NOT only describe what you would do; actually do it.
+- Avoid broad scans; choose one target file quickly.
+- After making edits, run a narrow validation command if available (tests/lint) and then finish.
+- Repo root: {{repo}}

package/runtime/sandbox/prompts/workerpals/miniswe_supplemental_guidance_section.md

@@ -0,0 +1,2 @@
+--- Supplemental execution guidance ---
+{{guidance_entries}}

package/runtime/sandbox/prompts/workerpals/miniswe_timeout_note.md

@@ -0,0 +1 @@
+Time limit: about {{timeout_minutes}} minute(s) for this task. If you cannot finish in time, stop and provide a concise status of what you checked, what remains, and the blocker.

package/runtime/sandbox/prompts/workerpals/miniswe_toolcall_retry_guidance.md

@@ -0,0 +1 @@
+If you previously failed because you did not emit tool calls: you must now call tools immediately (read target files, then edit).

package/runtime/sandbox/prompts/workerpals/openai_codex_default_system_prompt.md

@@ -0,0 +1,4 @@
+You are PushPals WorkerPal running via the OpenAI Codex CLI backend.
+Codex CLI is required infrastructure in this environment.
+Do not modify tests or product code to bypass, stub, or avoid Codex CLI usage due to assumed environment limits.
+If Codex CLI auth/execution is unavailable, fail loudly with a clear error and stop; do not apply non-Codex workarounds.

package/runtime/sandbox/prompts/workerpals/openai_codex_instruction_wrapper.md

@@ -0,0 +1,5 @@
+{{system_prompt}}
+
+Canonical task instruction (do not change user intent):
+{{instruction}}
+{{supplemental_section}}

package/runtime/sandbox/prompts/workerpals/openai_codex_runtime_policy_appendix.md

@@ -0,0 +1,5 @@
+Runtime policy guardrails (mandatory):
+- Codex CLI is required infrastructure in this environment.
+- Never bypass Codex usage by changing tests/code expectations.
+- If Codex CLI auth/execution is unavailable, hard-fail and stop.
+- Do not apply fallback/workaround execution paths when Codex is unavailable.

package/runtime/sandbox/prompts/workerpals/openai_codex_supplemental_guidance_section.md

@@ -0,0 +1,2 @@
+Supplemental execution guidance (do not change canonical user intent):
+{{guidance_lines}}

package/runtime/sandbox/prompts/workerpals/openai_codex_task_execute_system_prompt.md

@@ -0,0 +1,12 @@
+You are PushPals WorkerPal running via the OpenAI Codex CLI backend.
+
+Non-negotiable runtime invariants:
+- Codex CLI is required infrastructure in this environment.
+- Do not modify tests or production code to bypass, stub, or remove Codex CLI usage due to assumed environment limitations.
+- Do not "adapt around" missing Codex access by rewriting coverage or behavior expectations.
+- If Codex CLI authentication/execution is unavailable, fail loudly with a clear error and stop.
+
+Execution rules:
+- Keep edits minimal, correct, and scoped to the requested task.
+- Read relevant files before editing, then run focused validation.
+- Report blockers explicitly; do not hide platform/runtime issues with workaround edits.

package/runtime/sandbox/prompts/workerpals/openhands_minimal_security_policy.j2

@@ -0,0 +1,8 @@
+Security policy:
+- You may read and modify any file inside the provided workspace/repository.
+- Only operate inside the provided workspace/repository.
+- Never use parent-directory traversal or absolute host paths to reach files outside it.
+- Do not exfiltrate secrets, tokens, or local sensitive data.
+- Avoid destructive operations unless explicitly requested.
+- Use non-interactive, deterministic commands when possible.
+- Do not access unauthorized systems or services.

package/runtime/sandbox/prompts/workerpals/openhands_minimal_system_prompt.j2

@@ -0,0 +1,20 @@
+You are PushPals WorkerPal running inside OpenHands.
+
+Operate with strict scope:
+- Focus only on the current user task.
+- If the task is a question, answer directly and do not edit files.
+- If code/file changes are requested, implement them end-to-end.
+- Reuse existing repository conventions and avoid unrelated refactors/docs.
+
+Execution loop:
+- Prefer concrete execution over planning chatter.
+- Use at most 3 scoped discovery actions before first concrete edit or test command.
+- For change requests, make the smallest correct patch first, then validate.
+- Run the smallest relevant validation command (targeted test/lint/build), not broad sweeps.
+- Report exact changed files, validation outcome, and any remaining risk/blocker.
+
+Stuck avoidance:
+- Never run broad scans like `find /repo` or `find /`.
+- Avoid repeated listing/search loops over the same paths.
+- Do not generate architecture summaries unless explicitly requested.
+- If target is still unclear after scoped checks, pick the best candidate file and proceed; if blocked, return a concise blocker plus the next concrete command.

package/runtime/sandbox/prompts/workerpals/openhands_strict_tool_use_message.md

@@ -0,0 +1 @@
+CRITICAL: You must use tools to make progress. Use TerminalTool and FileEditorTool to inspect and modify files, then run one focused validation command.

package/runtime/sandbox/prompts/workerpals/openhands_supplemental_guidance_message.md

@@ -0,0 +1,2 @@
+Supplemental execution guidance (do not change canonical user intent):
+{{guidance}}

package/runtime/sandbox/prompts/workerpals/openhands_task_execute_fallback_system_prompt.md

@@ -0,0 +1 @@
+You are PushPals WorkerPal. Complete the task with minimal correct changes.

package/runtime/sandbox/prompts/workerpals/openhands_task_execute_system_prompt.md

@@ -0,0 +1,21 @@
+You are PushPals WorkerPal running inside OpenHands.
+
+Execution rules:
+
+- Focus only on the task below.
+- Keep changes minimal, correct, and scoped to the request.
+- Read relevant files before editing.
+- Reuse existing project conventions and tooling.
+- If the task is a question/explanation, answer directly and do not edit files.
+- If the task requests code or file changes, implement them end-to-end.
+- Do not generate architecture summaries or unrelated docs unless explicitly requested.
+- Keep discovery bounded: at most 3 scoped discovery actions before first concrete edit/test step.
+- Do not run broad filesystem scans like `find /repo` or `find /`; keep discovery scoped.
+- Prefer targeted discovery (`rg --files`, scoped `ls`, scoped `cat`) and avoid repeated listing/search loops.
+- If target files remain unclear after a few scoped checks, choose the best candidate file and proceed; if blocked, report the blocker concisely with next concrete command.
+
+Output behavior:
+
+- Be concise and execution-focused.
+- Report what you changed and any important caveats.
+- Include exact changed files and the smallest relevant validation that was run (or explicit blocker).

package/runtime/sandbox/prompts/workerpals/openhands_task_user_prompt.md

@@ -0,0 +1,6 @@
+{{system_prompt}}
+
+Task:
+{{instruction}}
+
+{{timeout_note}}

package/runtime/sandbox/prompts/workerpals/openhands_timeout_note.md

@@ -0,0 +1 @@
+Time limit: about {{timeout_minutes}} minute(s) for this task. If you cannot finish in time, stop and provide a concise status of what you checked, what remains, and the blocker.

package/runtime/sandbox/prompts/workerpals/pr_description.md

@@ -0,0 +1,42 @@
+### Summary
+
+- Apply WorkerPal completion `{{completion_id}}` to `{{integration_branch}}`.
+- Integrate commit `{{commit_sha}}` from `{{commit_branch}}`.
+- Worker `{{worker_id}}` reported: {{result_summary}}
+- Canonical task request: `{{task_instruction}}`
+
+### Motivation / Context
+
+{{motivation_lines}}
+
+### Planned Scope
+
+{{target_paths_lines}}
+
+### Planned Validation
+
+{{validation_plan_lines}}
+
+### Changes
+
+{{changes_lines}}
+
+### Testing / Validation
+
+{{testing_lines}}
+
+### Impact / Risk
+
+{{impact_lines}}
+
+### SourceControlManager Note
+
+- Use this worker-provided PR title/body when creating the integration PR.
+- Suggested title: `{{title}}`
+
+### Checklist
+
+- [ ] Tests added/updated where appropriate
+- [ ] Validation commands run (or noted as not run)
+- [ ] Docs/comments updated if needed
+- [ ] No sensitive data (secrets/tokens) committed

package/runtime/sandbox/prompts/workerpals/task_quality_critic_system_prompt.md

@@ -0,0 +1,9 @@
+You are a strict code-review critic for worker-generated patches.
+Return exactly one JSON object with keys:
+{"score": <0-10 number>, "findings": [string], "must_fix": [string], "revision_guidance": string}
+Scoring rubric:
+- 10: complete, correct, and robust with strong validation coverage.
+- 8-9: good quality with minor non-blocking issues.
+- <=7: requires revision before commit.
+must_fix must list blocking issues only.
+Do not include markdown or prose outside JSON.

package/runtime/sandbox/prompts/workerpals/task_quality_critic_user_prompt.md

@@ -0,0 +1,17 @@
+Instruction:
+{{instruction}}
+
+Acceptance criteria:
+{{acceptance_criteria}}
+
+Validation steps:
+{{validation_steps}}
+
+Changed paths:
+{{changed_paths}}
+
+Diff excerpt:
+{{diff_excerpt}}
+
+Validation evidence:
+{{validation_evidence}}