Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Slashdo invocation resolver (#3089).
*
* A CoS task can name a bundled slashdo workflow (`plan-task`, `next`, `review`,
* …) instead of hand-written prose. How an agent actually *invokes* that workflow
* is NOT a prefix swap — slashdo installs itself differently per host CLI
* (`lib/slashdo/src/environments.js`), so the same command lands in three shapes:
*
* | Host CLI | namespacing | invocation |
* |--------------------------|---------------|--------------------------------|
* | Claude Code | `subdirectory`| `/do:<cmd> <args>` |
* | OpenCode | `flat` | `/do-<cmd> <args>` |
* | Codex / Grok / Antigravity | `directory` | Agent Skill, selected by NAME |
*
* There is no `$do:<cmd>` form. Because the provider is only known at spawn
* time (the task form's provider select defaults to "Auto"), a task persists the
* bare command name in `metadata.slashdoCommand` and this module resolves the
* concrete invocation when the prompt is built.
*
* Every host receives the bundled procedure independently of a global install.
* File-tool hosts read an entrypoint and phase-specific supporting files; API
* providers receive a self-contained body. Explicitly pinned reviewer choices
* prune unreachable variants before either form is rendered.
*/
import { isTruthyMeta } from './metadataFlags.js';
import { isClaudeProvider, isOpencodeProvider } from './providerModels.js';
import { inferTuiCommand } from './providerVendors.js';
import { PROVIDER_TYPES } from './aiToolkit/constants.js';
/** slashdo's command namespace — `commands/do/<cmd>.md` in the submodule. */
export const SLASHDO_NAMESPACE = 'do';
/**
* Inline budget for a resolved command body, in characters (issue #3110).
*
* Under it the body is inlined as before — the section stays self-contained and
* the agent needs no extra file read. Over it, a host with file tools gets a
* pointer at a resolved copy on disk instead (see `buildSlashdoSection`).
*
* 24,000 chars is approximately 6k tokens. Deferred bundles are always staged
* because their relative references need a filesystem base, even when the
* entrypoint is under this limit. Small self-contained commands stay inline.
*/
export const SLASHDO_INLINE_BUDGET_CHARS = 24000;
/**
* Reviewer-specific libraries that can be omitted once the run's reviewers are
* pinned. CLI reviewers share localAgent; local-model reviewers share localModel.
* Keep the multi-reviewer dispatcher for every non-empty list, even one reviewer.
*/
export const SLASHDO_REVIEWER_INCLUDES = Object.freeze({
copilot: 'copilot-review-loop',
username: 'github-reviewer-loop',
localAgent: 'local-agent-review-loop',
localModel: 'ollama-review-loop',
multi: 'multi-reviewer-loop',
});
/** Every reviewer-variant include name — the prunable universe. */
export const SLASHDO_REVIEWER_INCLUDE_NAMES = Object.freeze(Object.values(SLASHDO_REVIEWER_INCLUDES));
/**
* Reviewer slugs that drive slashdo's shared local-agent (spawnable CLI) loop.
*
* PortOS-only CLI reviewers (`opencode`, `kilo`, `kimi`) are members too: slashdo has no
* slug for them, but the include they'd need is the same generic spawn-a-CLI
* review procedure, and pruning it would leave PortOS's own inlined CLI Reviewer
* Procedure with nothing to point at. `lmstudio`/`mtplx` sit in
* LOCAL_MODEL_REVIEWERS for the same reason.
*
* Kept here rather than imported from reviewerConfig.js, whose importer
* cosValidation.js imports THIS module — an import back would be a cycle.
* Exported so reviewerConfig.test.js can pin it against `REVIEWER_CLI_BINARIES`
* (whose keys are the same roster); a reviewer added to one and not the other
* is a drift the test catches.
*/
export const LOCAL_AGENT_REVIEWERS = new Set(['claude', 'codex', 'antigravity', 'grok', 'cursor', 'pi', 'opencode', 'kilo', 'kimi']);
/** Reviewer slugs that drive slashdo's local-model (Ollama-style) loop. */
const LOCAL_MODEL_REVIEWERS = new Set(['ollama', 'lmstudio', 'mtplx']);
/**
* slashdo's own `--review-with` reviewer vocabulary, mapped to the PortOS slug
* `unreachableReviewerIncludes` is keyed by. slashdo spells antigravity `agy`
* and accepts `gemini`/`antigravity` as aliases for it; `cursor-agent` is an
* alias for `cursor`. PortOS stores the long names.
*
* Kept local rather than imported from `reviewerConfig.js` for the same reason
* `LOCAL_AGENT_REVIEWERS` is: `cosValidation.js` (which re-exports that module)
* imports THIS one, so the arrow can only point one way.
*
* Deliberately NOT the full `REVIEWER_VALUES` roster — a `PORTOS_ONLY_REVIEWERS`
* slug (`lmstudio`/`mtplx`/`kilo`/`kimi`) has no slashdo counterpart and
* aborts the command, so seeing one in an explicit flag means the argument was
* hand-written against a grammar we don't own. That falls through to the
* unresolvable branch, which prunes nothing.
*
* slashdo's `cmd[<invocation>]` escape hatch is likewise absent, and deliberately:
* an arbitrary shell command maps to no PortOS reviewer, so it resolves as
* unreadable and the run keeps every reviewer include. `splitReviewerEntries` is
* already bracket-aware, so a comma inside the invocation does not split the
* entry — the flag reaches slashdo verbatim, which is the whole contract here.
*/
const SLASHDO_REVIEWER_SLUGS = Object.freeze({
copilot: 'copilot',
codex: 'codex',
claude: 'claude',
grok: 'grok',
cursor: 'cursor',
pi: 'pi',
'cursor-agent': 'cursor',
agy: 'antigravity',
gemini: 'antigravity',
antigravity: 'antigravity',
opencode: 'opencode',
zen: 'opencode',
'opencode-zen': 'opencode',
ollama: 'ollama',
});
/** Reviewer slugs slashdo rejects a `[<model>]` bracket on. */
const BRACKET_FREE_SLASHDO_REVIEWERS = new Set(['copilot']);
const REVIEW_WITH_FLAG = '--review-with';
/** slashdo's explicit "no external reviewer this run" tombstone. */
const REVIEW_WITH_NONE = 'none';
/**
* Shell constructs whose expansion we cannot see. A value carrying one is not a
* reviewer list we can resolve — the agent's shell decides what it becomes.
*/
const UNEXPANDABLE_VALUE_RE = /[$`\\]/;
/** GitHub login charset plus the optional `[bot]` App suffix, per slashdo. */
const REVIEWER_LOGIN_RE = /^[A-Za-z0-9][A-Za-z0-9-]*(?:\[bot\])?$/;
const ENTRY_MAX_RE = /^max=\d+$/;
const ENTRY_EFFORT_RE = /^effort=(?:low|medium|high|xhigh|max)$/;
/** The sentinel for "an explicit flag is there, but we can't read it safely". */
const UNRESOLVED_REVIEW_WITH = Object.freeze({ explicit: true, unresolved: true, reviewers: Object.freeze([]), usernames: Object.freeze([]) });
/**
* Split a free-form argument string into argv-style tokens, honoring single and
* double quotes so a bracketed model id with spaces (`agy[Gemini 3.5 Flash]`)
* survives as one token.
* @param {string} args
* @returns {string[]|null} null when a quote is left open (nothing safe to read)
*/
function tokenizeSlashdoArgs(args) {
const tokens = [];
let current = '';
let started = false;
let quote = null;
for (const ch of args) {
if (quote) {
if (ch === quote) quote = null;
else current += ch;
continue;
}
if (ch === '"' || ch === "'") { quote = ch; started = true; continue; }
if (/\s/.test(ch)) {
if (started) { tokens.push(current); current = ''; started = false; }
continue;
}
current += ch;
started = true;
}
if (quote) return null;
if (started) tokens.push(current);
return tokens;
}
/**
* Split a `--review-with` value on the commas BETWEEN entries — never on one
* inside a `[<model>]` bracket, whose value is free-form.
* @param {string} value
* @returns {string[]|null} null when a bracket is left open
*/
function splitReviewerEntries(value) {
const entries = [];
let current = '';
let depth = 0;
for (const ch of value) {
if (ch === '[') depth += 1;
else if (ch === ']') { depth -= 1; if (depth < 0) return null; }
if (ch === ',' && depth === 0) { entries.push(current); current = ''; continue; }
current += ch;
}
if (depth !== 0) return null;
entries.push(current);
return entries;
}
/**
* Strip slashdo's per-entry `~` suffixes (`~opt`, `~max=<n>`, `~effort=<level>`)
* off an entry and return the bare slug/login. Suffixes are matched only OUTSIDE
* the outermost brackets, because a model id may itself contain a `~`.
*
* The suffix VALUES are deliberately discarded: they ride the explicit argument
* verbatim into the invocation, so PortOS never re-emits them. This only has to
* decide whether the entry is one slashdo would accept.
*
* @param {string} entry
* @returns {string|null} the suffix-free token, or null when a suffix is one
* slashdo would reject (unknown, repeated, or malformed)
*/
function stripEntrySuffixes(entry) {
const open = entry.indexOf('[');
const close = entry.lastIndexOf(']');
if (open !== -1 && close < open) return null;
const tilde = entry.indexOf('~', close === -1 ? 0 : close + 1);
if (tilde === -1) return entry;
const seen = new Set();
for (const suffix of entry.slice(tilde + 1).split('~')) {
const kind = suffix === 'opt' ? 'opt'
: ENTRY_MAX_RE.test(suffix) ? 'max'
: ENTRY_EFFORT_RE.test(suffix) ? 'effort' : null;
if (!kind || seen.has(kind)) return null;
seen.add(kind);
}
return entry.slice(0, tilde);
}
/**
* Resolve one suffix-free `--review-with` entry to the PortOS reviewer slug (or
* `@login`) it names.
* @param {string} token
* @returns {{reviewer: string}|{username: string}|null} null when slashdo itself
* would reject the entry, or when it names something PortOS can't map
*/
function resolveReviewerEntry(token) {
if (!token) return null;
if (token.startsWith('@')) {
const login = token.slice(1);
// slashdo rejects `@login[…]`; `[bot]` is part of the login, not a model.
return REVIEWER_LOGIN_RE.test(login) ? { username: login } : null;
}
const open = token.indexOf('[');
if (open !== -1 && !token.endsWith(']')) return null;
const slug = (open === -1 ? token : token.slice(0, open)).toLowerCase();
const reviewer = SLASHDO_REVIEWER_SLUGS[slug];
if (!reviewer) return null;
if (open !== -1 && BRACKET_FREE_SLASHDO_REVIEWERS.has(reviewer)) return null;
return { reviewer };
}
/**
* The reviewer contract an EXPLICIT `--review-with` in a task's `slashdoArgs`
* declares (#6261).
*
* slashdo's own precedence puts a typed flag above every saved or inherited
* default (`lib/review-config-defaults.md`), and PortOS passes `slashdoArgs`
* through verbatim — so when that flag is present it, not `resolveReviewerConfig`,
* is what the run will actually use. Pruning the body or pinning a `--review-with`
* from task metadata instead is how a prompt ends up requesting one reviewer,
* omitting its loop, and instructing the agent to use another.
*
* Three outcomes, and the caller must treat them differently:
* - `null` — no explicit flag; the metadata/defaults contract governs as before.
* - `{ unresolved: true }` — a flag is there but this parser can't safely read it
* (an open quote or bracket, a shell expansion, a slug or suffix outside
* slashdo's grammar, conflicting repeats). Preserve the arguments and prune and
* pin NOTHING: a grammar we don't fully own is exactly the case where guessing
* drops the loop the run needs.
* - `{ none: true }` or a resolved `{ reviewers, usernames }` — the explicit
* selection, already mapped to PortOS slugs.
*
* Suffix values (`~opt` / `~max=<n>` / `~effort=<level>`) and `[<model>]` brackets
* are validated but not returned: they travel in the verbatim argument, so
* re-emitting them would state the same pin twice.
*
* @param {unknown} args - the task's raw `metadata.slashdoArgs`
* @returns {{explicit: true, unresolved?: true, none?: true, reviewers: string[],
* usernames: string[]}|null}
*/
export function parseExplicitReviewWith(args) {
if (typeof args !== 'string' || !args.includes(REVIEW_WITH_FLAG)) return null;
const tokens = tokenizeSlashdoArgs(args);
if (!tokens) return UNRESOLVED_REVIEW_WITH;
const values = [];
for (let i = 0; i < tokens.length; i += 1) {
const token = tokens[i];
if (token === REVIEW_WITH_FLAG) {
const next = tokens[i + 1];
// A missing value, or the next flag where the value should be.
if (next === undefined || next.startsWith('-')) return UNRESOLVED_REVIEW_WITH;
values.push(next);
i += 1;
} else if (token.startsWith(`${REVIEW_WITH_FLAG}=`)) {
values.push(token.slice(REVIEW_WITH_FLAG.length + 1));
}
// Anything else starting with the same prefix (`--review-with-foo`) is a
// different flag — not ours to read.
}
if (!values.length) return null;
// Repeats are outside slashdo's documented grammar unless they agree.
if (new Set(values).size > 1) return UNRESOLVED_REVIEW_WITH;
const value = values[0];
if (!value || UNEXPANDABLE_VALUE_RE.test(value)) return UNRESOLVED_REVIEW_WITH;
if (value.toLowerCase() === REVIEW_WITH_NONE) {
return { explicit: true, none: true, reviewers: [], usernames: [] };
}
const entries = splitReviewerEntries(value);
if (!entries) return UNRESOLVED_REVIEW_WITH;
const reviewers = [];
const usernames = [];
for (const entry of entries) {
const bare = stripEntrySuffixes(entry.trim());
const resolved = bare === null ? null : resolveReviewerEntry(bare);
if (!resolved) return UNRESOLVED_REVIEW_WITH;
if (resolved.username) {
if (!usernames.some(u => u.toLowerCase() === resolved.username.toLowerCase())) usernames.push(resolved.username);
} else if (!reviewers.includes(resolved.reviewer)) reviewers.push(resolved.reviewer);
}
return { explicit: true, none: false, reviewers, usernames };
}
/**
* Which reviewer-variant includes a run can never reach, given its resolved
* reviewers — the `skipIncludes` set for `loadSlashdoFile` (#3110).
*
* **Defaults to pruning NOTHING** whenever the reviewer set isn't a resolved,
* recognized list: no array, an empty array, or a list naming a slug this
* mapping doesn't know. An over-pruned prompt that drops the loop the agent
* actually needs is far worse than a fat one, so every uncertain case keeps
* everything.
*
* @param {Object} [opts]
* @param {string[]|null} [opts.reviewers] - resolved keyed reviewer slugs
* @param {string[]} [opts.usernames] - resolved `@login` reviewers
* @returns {string[]} include names safe to omit (possibly empty)
*/
export function unreachableReviewerIncludes({ reviewers = null, usernames = [] } = {}) {
if (!Array.isArray(reviewers)) return [];
const users = Array.isArray(usernames) ? usernames.filter(Boolean) : [];
if (!reviewers.length && !users.length) return [];
const keep = new Set();
for (const slug of reviewers) {
if (slug === 'copilot') keep.add(SLASHDO_REVIEWER_INCLUDES.copilot);
else if (LOCAL_AGENT_REVIEWERS.has(slug)) keep.add(SLASHDO_REVIEWER_INCLUDES.localAgent);
else if (LOCAL_MODEL_REVIEWERS.has(slug)) keep.add(SLASHDO_REVIEWER_INCLUDES.localModel);
// An unrecognized slug means this mapping is behind the reviewer enum —
// keep everything rather than guess which loop it needs.
else return [];
}
if (users.length) keep.add(SLASHDO_REVIEWER_INCLUDES.username);
// Always kept: slashdo's commands dispatch EVERY non-empty reviewer list
// through the wrapper, single-entry lists included (see SLASHDO_REVIEWER_INCLUDES).
keep.add(SLASHDO_REVIEWER_INCLUDES.multi);
return SLASHDO_REVIEWER_INCLUDE_NAMES.filter(name => !keep.has(name));
}
/**
* The three invocation shapes slashdo's installer produces. `slash-namespaced`
* and `slash-flat` are typed as a slash command by the host CLI; `skill` is an
* Agent Skill the model selects by name/description (no prefix, nothing to type).
*/
export const SLASHDO_INVOCATION_STYLES = Object.freeze({
SLASH_NAMESPACED: 'slash-namespaced',
SLASH_FLAT: 'slash-flat',
SKILL: 'skill',
});
/** Bare slashdo command names are file-path segments — keep them inert. */
const COMMAND_NAME_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
/**
* True when `name` is a well-formed bare slashdo command (`plan-task`, `pr-better`).
* Rejects anything that could escape `commands/do/` — the value reaches
* `loadSlashdoFile`, which joins it into a path.
* @param {unknown} name
* @returns {boolean}
*/
export function isValidSlashdoCommand(name) {
return typeof name === 'string' && COMMAND_NAME_RE.test(name);
}
/**
* The flat/skill name slashdo's installer gives a command in `flat` and
* `directory` environments: `do/plan-task` → `do-plan-task`. Mirrors
* `getSkillName` in `lib/slashdo/src/transformer.js`.
* @param {string} command - bare command name (`plan-task`)
* @returns {string}
*/
export function slashdoSkillName(command) {
return `${SLASHDO_NAMESPACE}-${command}`;
}
/**
* Which invocation shape a provider gets — the single home for the
* provider→slashdo-shape decision (`agentPromptBuilder.js`'s
* `canTypeSlashCommands` capability flag, and the completion `mode` it feeds,
* derive from this rather than re-deriving it).
*
* Detection reuses the shared provider predicates, so a path-configured or
* renamed binary is recognised. An unidentified provider falls through to
* `skill`; guessing `/do:<cmd>` for an unknown host would hand it a line of
* prose it can't run, while `skill` always works because the caller inlines the
* procedure.
*
* `leanMode` (small local models behind `claude --bare`) also resolves to
* `skill`: the lean session skips project command discovery, so `/do:<cmd>`
* would resolve to nothing.
*
* **Unknown-command posture (`assumeClaudeWhenUnknown`).** A provider with no
* launch command is genuinely ambiguous, and the two kinds of caller want
* opposite answers:
* - **Rendering an invocation for a task** (default, `false`): stay strict, like
* `isClaudeProvider`. Printing `/do:next` for a host that turns out not to be
* Claude hands the agent an uninvokable line; `skill` + the inlined body works
* everywhere, so "unknown" must not read as Claude.
* - **Deciding whether a spawned agent may TYPE `/do:pr`** (`true`): the answer
* must match the command the spawners will ACTUALLY launch, which for a blank
* `provider.command` is `inferTuiCommand(provider.id)` — the same fallback
* `agentTuiSpawning.js` and `buildCliSpawnConfig` both apply. So this posture
* resolves the command the spawner would pick rather than guessing: a custom
* provider id with no command launches `claude` and IS slashdo-capable, while
* `codex-tui` with no command launches `codex` and is not.
* Only the blank-command case is affected — a provider that names its command
* resolves the same under either posture.
*
* @param {Object} [opts]
* @param {string|null} [opts.providerId]
* @param {string|null} [opts.providerCommand]
* @param {boolean} [opts.leanMode]
* @param {boolean} [opts.assumeClaudeWhenUnknown=false] - when the provider names
* no command, resolve the one the spawners would infer from its id instead of
* falling through to `skill`.
* @returns {string} one of SLASHDO_INVOCATION_STYLES
*/
export function resolveSlashdoStyle({
providerId = null,
providerCommand = null,
leanMode = false,
assumeClaudeWhenUnknown = false,
} = {}) {
// A blank command is only resolved for the spawner posture; the strict default
// deliberately leaves it blank so `isClaudeProvider` won't read it as Claude.
const command = (assumeClaudeWhenUnknown && !providerCommand)
? inferTuiCommand(providerId)
: providerCommand;
const provider = { id: providerId, command };
if (isOpencodeProvider(provider)) return SLASHDO_INVOCATION_STYLES.SLASH_FLAT;
if (leanMode) return SLASHDO_INVOCATION_STYLES.SKILL;
if (isClaudeProvider(provider)) return SLASHDO_INVOCATION_STYLES.SLASH_NAMESPACED;
// Codex / Grok / Antigravity install Agent Skills, not slash commands — as
// does anything we can't positively identify.
return SLASHDO_INVOCATION_STYLES.SKILL;
}
/**
* True when a session can be handed a typed Claude Code slash command — both the
* slashdo ones (`/do:pr`, `/do:push`) and Claude's own built-ins (`/simplify`).
* `SLASH_NAMESPACED` is exactly the Claude-Code-with-project-commands case, so
* one predicate answers both: OpenCode gets `SLASH_FLAT` (no `/do:pr`, no
* `/simplify`), codex/grok/antigravity get `SKILL`, and a lean `--bare` session
* gets `SKILL` because it skips command discovery entirely.
*
* This is the single home for the completion-workflow gates in
* `agentPromptBuilder.js` (formerly three inline provider-id allowlists, and
* later a trio of per-shape capability flags the completion sections
* re-derived; both collapsed to this predicate plus the resolved completion
* `mode` — see #6873). It uses the `assumeClaudeWhenUnknown` posture because
* those gates describe a session the spawners are about to launch, and every
* spawner resolves a blank command to `claude`.
*
* `assumeClaudeWhenUnknown` defaults to `true` here (unlike `resolveSlashdoStyle`)
* because the callers are describing a CLI/TUI session about to be spawned. An
* HTTP-API provider is never spawned as a local CLI, so the API path passes
* `false` — a blank provider there is not a latent `claude`.
*
* @param {Object} [opts] - same shape as `resolveSlashdoStyle`
* @returns {boolean}
*/
export function canTypeSlashCommands({
providerId = null,
providerCommand = null,
leanMode = false,
assumeClaudeWhenUnknown = true,
} = {}) {
return resolveSlashdoStyle({ providerId, providerCommand, leanMode, assumeClaudeWhenUnknown })
=== SLASHDO_INVOCATION_STYLES.SLASH_NAMESPACED;
}
/**
* Provider types spawned as a local coding harness — a real shell, real file
* tools, and a PATH that has `git` / `gh` / the reviewer CLIs on it. An HTTP
* `api` provider has none of that, so it can never drive its own PR.
*
* Built from `PROVIDER_TYPES` rather than string literals: a typo'd literal here
* silently returns `false` and PortOS starts double-driving the PR.
*/
const HARNESS_PROVIDER_TYPES = new Set([PROVIDER_TYPES.CLI, PROVIDER_TYPES.TUI]);
/**
* True when a spawned session can drive the WHOLE change-request lifecycle
* itself — commit, push, open the PR, run the configured review loop, merge
* (#3733).
*
* This is a strictly weaker question than `canTypeSlashCommands`, and
* conflating the two is what stranded every agy / grok / codex run in a
* two-agent handoff. Those hosts can't TYPE `/do:pr` (slashdo installs there as
* Agent Skills, not slash commands), so they used to be told "commit and stop"
* — PortOS then opened the PR after the run and queued a separate `sys-rl-*`
* follow-up agent just to run the review loop. But not typing a slash command
* says nothing about running `gh pr create`: these are full coding harnesses,
* and the follow-up agent they hand off TO is routinely one of them driving the
* exact same inlined slashdo procedure. So the split bought nothing and cost a
* whole extra agent, a cold context, and a queue hop per task.
*
* `leanMode` is the one local harness excluded: a small Ollama-backed model
* behind `claude --bare` fumbles multi-step flows, and a half-run merge
* procedure is worse than a clean handoff.
*
* This is the HOST half of the question only. Whether a given run's prompt
* actually handed it the PR depends on the task shape too, and that combined
* answer is stamped on the agent record as `metadata.prOpenedBy` — see
* `promptOpensOwnPr` in `services/promptSections/completion.js`, which is the
* predicate the prompt itself is rendered from, and `resolvePrOpenedBy` below,
* which reads the stamp back at cleanup time.
*
* @param {Object} [opts]
* @param {string|null} [opts.providerType] - `'tui' | 'cli' | 'api'`
* @param {boolean} [opts.leanMode]
* @returns {boolean}
*/
export function agentOwnsPrWorkflow({ providerType = null, leanMode = false } = {}) {
if (leanMode) return false;
return HARNESS_PROVIDER_TYPES.has(providerType);
}
/**
* WHO opens a run's pull request, per the prompt that run was actually given.
* Stamped on the agent record at spawn time as `metadata.prOpenedBy` and read
* back by cleanup; `promptOpensOwnPr` (services/promptSections/completion.js)
* is the single producer.
*
* Three values rather than a boolean because the two agent-owned cases behave
* differently downstream and a boolean kept collapsing them:
* - `agent-slashdo` — the completion section handed it `/do:pr`, which pushes,
* opens, reviews and merges the PR in one command.
* - `agent-inline` — the completion section handed it the plain `git`/`gh`
* steps plus the inline Review Loop / **Merge Gate** section. Only this value
* owes the #5876 merge-gate check, because only this prompt has that section.
* - `portos` — the prompt told the agent NOT to open a PR; the
* post-completion cleanup opens it.
*/
export const PR_OPENED_BY = Object.freeze({
AGENT_SLASHDO: 'agent-slashdo',
AGENT_INLINE: 'agent-inline',
PORTOS: 'portos',
});
const PR_OPENED_BY_VALUES = new Set(Object.values(PR_OPENED_BY));
/**
* The stamp for a COMPLETED agent, read off its record — accepting every shape
* a record can carry, because other installs upgrade on their own schedule and
* their older records keep arriving here.
*
* 1. `metadata.prOpenedBy` (this version) is authoritative: cleanup must act on
* what the prompt actually said, not on a fresh derivation that could
* disagree with it. An unrecognized value — a record from a NEWER install —
* is not trusted as an agent; it falls through to the legacy rules below.
* 2. The #3733 boolean `metadata.ownsPrWorkflow`, when the record has one,
* still answers exactly as it did: `true` → `agent-inline` (a slashdo-free
* harness told to run `gh pr create` itself), `false` → `portos`.
* 3. Otherwise `portos`, or `agent-slashdo` for a slashdo-capable host — the
* pre-#3733 fallback, unchanged, since those runs were prompted by the old
* builder whose gate was exactly `canTypeSlashCommands`.
*
* **The #6869 fix is deliberately NOT retro-applied to rule 2**, even though
* that boolean is the one this issue retires. It answered "did the prompt
* render the INLINE PR section", so `false` is ambiguous on a slashdo-capable
* host between the defect (a `/do:pr` run PortOS then re-created a PR for) and
* a correct exclusion (a read-only / no-code-output / discard-worktree /
* leave-open run PortOS really does own). Overriding it to `agent-slashdo`
* would fix the first and break the second — and only the task, which this
* leaf deliberately does not see, tells them apart. Every legacy record
* therefore resolves exactly as it did before this change; only records
* stamped by `promptOpensOwnPr` (rule 1) carry the corrected answer, and an
* in-flight legacy run is over within one upgrade window.
*
* @param {Object} opts
* @param {string|undefined} opts.persistedPrOpenedBy - `metadata.prOpenedBy`
* @param {boolean|undefined} [opts.persistedOwnsPrWorkflow] - the legacy
* `metadata.ownsPrWorkflow` boolean (#3733)
* @param {string|null} [opts.providerId]
* @param {string|null} [opts.providerCommand]
* @param {boolean} [opts.leanMode]
* @returns {string} a `PR_OPENED_BY` value
*/
export function resolvePrOpenedBy({
persistedPrOpenedBy,
persistedOwnsPrWorkflow,
providerId = null,
providerCommand = null,
leanMode = false,
}) {
if (PR_OPENED_BY_VALUES.has(persistedPrOpenedBy)) return persistedPrOpenedBy;
if (typeof persistedOwnsPrWorkflow === 'boolean') {
return persistedOwnsPrWorkflow ? PR_OPENED_BY.AGENT_INLINE : PR_OPENED_BY.PORTOS;
}
return canTypeSlashCommands({ providerId, providerCommand, leanMode })
? PR_OPENED_BY.AGENT_SLASHDO
: PR_OPENED_BY.PORTOS;
}
/**
* The PR answers a spawned run needs, from ONE reading of the task, the
* persisted prompt verdict and the provider descriptor. Both in-process spawners
* call this once — the TUI `finish()` path up front, because its merge-gate contract check (#5876)
* reads the ownership answer before the run completes; the direct-CLI `close` handler
* at exit — and hand the result to `runSpawnerCompletionCleanup`, so the
* ownership question and the cleanup that acts on it can never read different
* answers (#3733).
*
* `agentOpensOwnPr` (did the prompt hand this run its own push → PR → merge?)
* and `prClaimExpected` (does finalize verify a PR claim for it?) are
* deliberately two predicates: a harness that owns the workflow but cannot TYPE
* `/do:pr` is backstopped by cleanup, which re-checks the forge and opens the PR
* itself when the agent skipped it — failing it at finalize for a PR that is
* about to exist would turn a recovered hand-off into a false needs-attention
* (#3358). `prClaimExpected` therefore stays the raw slash-command capability,
* matching the runner path's own derivation in `agentLifecycle.js`; it asks
* "will a PR already be there when finalize looks?", not "who was told to open
* one".
*
* @param {Object} opts
* @param {Object} opts.task
* @param {string|undefined} opts.persistedPrOpenedBy - `metadata.prOpenedBy`
* @param {boolean|undefined} [opts.persistedOwnsPrWorkflow] - the legacy
* `metadata.ownsPrWorkflow` boolean (#3733)
* @param {string|null} [opts.providerId]
* @param {string|null} [opts.providerCommand]
* @param {boolean} [opts.leanMode]
* @returns {{ taskOpenPR: boolean, prOpenedBy: string, agentOpensOwnPr: boolean, prClaimExpected: boolean }}
*/
export function resolvePrOwnership({
task,
persistedPrOpenedBy,
persistedOwnsPrWorkflow,
providerId = null,
providerCommand = null,
leanMode = false,
}) {
const taskOpenPR = isTruthyMeta(task?.metadata?.openPR);
const prOpenedBy = resolvePrOpenedBy({
persistedPrOpenedBy, persistedOwnsPrWorkflow, providerId, providerCommand, leanMode,
});
return {
taskOpenPR,
prOpenedBy,
agentOpensOwnPr: taskOpenPR && prOpenedBy !== PR_OPENED_BY.PORTOS,
prClaimExpected: taskOpenPR && canTypeSlashCommands({ providerId, providerCommand, leanMode }),
};
}
/**
* Resolve the concrete invocation for a slashdo-backed task.
*
* @param {Object} opts
* @param {string} opts.command - bare command name (`plan-task`)
* @param {string} [opts.args] - free-form arguments (the task description)
* @param {string|null} [opts.providerId]
* @param {string|null} [opts.providerCommand] - the provider's launch command
* @param {boolean} [opts.leanMode]
* @returns {{ command: string, skillName: string, style: string, args: string,
* invocation: string }|null} null when `command` is missing or not a
* well-formed slashdo command name.
*/
export function resolveSlashdoInvocation({
command,
args = '',
providerId = null,
providerCommand = null,
leanMode = false,
} = {}) {
if (!isValidSlashdoCommand(command)) return null;
const style = resolveSlashdoStyle({ providerId, providerCommand, leanMode });
const skillName = slashdoSkillName(command);
const trimmedArgs = typeof args === 'string' ? args.trim() : '';
const suffix = trimmedArgs ? ` ${trimmedArgs}` : '';
const invocation = style === SLASHDO_INVOCATION_STYLES.SLASH_NAMESPACED
? `/${SLASHDO_NAMESPACE}:${command}${suffix}`
: style === SLASHDO_INVOCATION_STYLES.SLASH_FLAT
? `/${skillName}${suffix}`
: `Use the \`${skillName}\` skill${trimmedArgs ? ` on: ${trimmedArgs}` : ''}`;
return { command, skillName, style, args: trimmedArgs, invocation };
}
/**
* The "it's on disk, go read it" line for a procedure body too large to paste
* (#3110). Shared so every pointer an agent meets reads the same — a second
* hand-typed copy is how one caller ends up omitting the read-it-in-sections
* instruction that makes a 40KB file usable.
*
* @param {string} bodyPath - absolute path to the resolved copy
* @param {string} body - the body itself, for its size
* @returns {string}
*/
export function oversizedBodyPointer(bodyPath, body) {
return `The procedure entrypoint is on disk at \`${bodyPath}\` (${Math.round(body.length / 1000)}KB). READ THAT FILE before you start. Follow its phase order and required reads; read long procedures in sections as needed.`;
}
/**
* Render the prompt section for a resolved slashdo invocation. Pure — the
* caller loads `body` (via `loadSlashdoFile`) and passes it in, so this module
* stays side-effect free.
*
* The procedure accompanies every invocation style: managed apps need no global
* slashdo install or PortOS project-command symlinks.
*
* A staged body always renders as a pointer, including a short entrypoint with
* deferred references. Supporting files resolve relative to that entrypoint.
* `bodyPath` is only passed for hosts with file tools; API providers inline an
* eager, self-contained body.
*
* **`reviewWith` is mandatory whenever the body was pruned.** A pruned body has
* only the reviewer loop(s) the caller pruned FOR; if the run then resolved some
* other reviewer from slashdo's own saved defaults, that loop would be missing
* and the agent would improvise it. Emitting the pin makes the body and the run
* agree. Callers that prune nothing pass nothing.
*
* @param {ReturnType<typeof resolveSlashdoInvocation>} resolved
* @param {string|null} [body] - the command's markdown
* @param {Object} [opts]
* @param {string|null} [opts.bodyPath=null] - absolute path to a resolved copy of
* `body`. Pass only when the host has file tools.
* @param {string} [opts.reviewWith=''] - reviewer CSV to pin (`codex,copilot`).
* Required when `body` had reviewer variants pruned out of it AND the invocation
* does not already carry its own `--review-with` (see `explicitReviewWith`).
* @param {boolean} [opts.explicitReviewWith=false] - the invocation's own arguments
* carry an explicit `--review-with`, and `body` was pruned to match it (#6261).
* Mutually exclusive with `reviewWith`: restating the value PortOS already passes
* verbatim would emit every `~opt` / `~max=` / `~effort=` suffix twice.
* @param {string} [opts.reviewerEffortNote=''] - the per-reviewer reasoning-effort
* instruction (`buildReviewerEffortNote`). Non-empty only when `reviewWith` is
* NOT emitted: a pinned CSV carries each effort as slashdo's `~effort=<level>`
* suffix, so the prose would just have the agent pass the flag twice. Unpinned,
* the workflow resolves reviewers itself and this is the pin's only route to the
* CLI it spawns.
* @param {boolean} [opts.includeTaskContext=false] - keep the task-context bridge
* even when the invocation has explicit flags instead of a free-text target
* @returns {string} markdown section, or '' when `resolved` is null
*/
export function buildSlashdoSection(resolved, body = null, {
bodyPath = null,
reviewWith = '',
reviewerEffortNote = '',
includeTaskContext = false,
explicitReviewWith = false,
} = {}) {
if (!resolved) return '';
// Without explicit args the workflow operates on the task described above —
// say so rather than re-printing the whole description inside the invocation.
const target = resolved.args && !includeTaskContext ? '' : ' Apply it to the task described above.';
const lines = ['### Slashdo Workflow'];
if (resolved.style === SLASHDO_INVOCATION_STYLES.SKILL) {
lines.push(
`This task runs the bundled slashdo **${resolved.skillName}** workflow. ${resolved.invocation}.${target}`,
'Your CLI exposes slashdo as Agent Skills — selected by name, with no slash-command form to type.'
);
} else {
lines.push(
`This task runs the bundled slashdo **${resolved.skillName}** workflow.${target} If your CLI has slashdo installed you can invoke it directly:`,
'',
'```',
resolved.invocation,
'```'
);
}
if (explicitReviewWith) {
// The invocation above already carries the flag verbatim, so the pin points AT
// it rather than repeating it: slashdo's own precedence puts an explicit flag
// above every saved default, and restating the value would emit each
// per-reviewer suffix a second time.
lines.push(
'',
'The `--review-with` value in the invocation above is authoritative for this run: the procedure you were given carries ONLY the reviewer loops that value can reach (the rest were omitted as unreachable). Do not substitute a different reviewer from a saved slashdo default.'
);
} else if (reviewWith) {
lines.push(
'',
`Run this workflow with \`--review-with ${reviewWith}\` — the procedure you were given carries ONLY those reviewers' loops (the others were omitted as unreachable). Do not substitute a different reviewer from a saved slashdo default.`
);
}
if (reviewerEffortNote) {
lines.push('', reviewerEffortNote);
}
if (body && bodyPath) {
lines.push('', oversizedBodyPointer(bodyPath, body),
'Resolve each supporting-file path relative to the file containing that reference. Read each required reference only when its phase or condition applies; do not preload the bundle.');
} else if (body) {
lines.push(
'',
'The full procedure is inlined below — follow it exactly rather than improvising:',
'',
body.trim()
);
}
return lines.join('\n');
}