Skip to content

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

13.5 KB
Raw Blame
/**
 * Forge-issue capability for the persistent mind.
 *
 * Queueing work through `cos.create-task` needs a coding agent on this machine.
 * Plenty of installs have none — but almost every install can still reach a
 * GitHub or GitLab tracker, and an issue filed there is durable, reviewable, and
 * claimable later by `/do:next`, a human, or a peer machine that DOES have an
 * agent. So this capability is the preferred queueing lane whenever the mind is
 * not itself going to dispatch the work.
 *
 * The grant is re-checked after inference (like every other typed action), and
 * the target app is re-validated against the mind's managed-app allowlist and
 * its resolved work tracker through `persistentMindManagedApps` — the same
 * roster the task grant reads, so the tracker the mind writes to is the tracker
 * a claim would read from.
 */

import { loadState } from './cosState.js';
import { fileForgeIssue, listAppIssues, probeForgeReachability, scrubForgeIssueText } from './appIssues.js';
import { readPersistentMindManagedApps } from './persistentMindManagedApps.js';
import { normalizePersistentMindCapabilities } from '../lib/persistentMindCapabilities.js';
import { normalizePersistentMindProfile } from '../lib/persistentMindProfile.js';
import {
  DISPATCH_EFFORT_LEVELS, DISPATCH_MODEL_TIERS,
  dispatchLabelSpec, forgeIssueLabels, resolvePlannerId,
} from '../lib/dispatchLabels.js';
import { forgeCliForTracker } from '../lib/workTracker.js';
import { boundedByJsonChars } from '../lib/objects.js';
import {
  PERSISTENT_MIND_ISSUE_EXTRA_LABEL_SPECS,
  PERSISTENT_MIND_ISSUE_CATEGORY_LABELS,
  PERSISTENT_MIND_ISSUE_LABEL,
  PERSISTENT_MIND_ISSUE_LIMITS,
  normalizeIssueTitleKey,
} from '../lib/persistentMindIssues.js';

const MAX_CATALOG_PROMPT_CHARS = 2_000;

const labelSpec = (name, cli) => dispatchLabelSpec(name, { cli })
  || (PERSISTENT_MIND_ISSUE_EXTRA_LABEL_SPECS[name]
    ? { name, ...PERSISTENT_MIND_ISSUE_EXTRA_LABEL_SPECS[name] }
    : null);

/**
 * The apps this mind may file against: granted by the managed-app allowlist AND
 * resolving to a forge. A `plan`/`jira` app is omitted rather than
 * listed-and-refused — the mind should not spend a call discovering that.
 */
export async function readPersistentMindIssueCatalog({ allowedAppIds } = {}) {
  const apps = await readPersistentMindManagedApps({ allowedAppIds });
  return {
    apps: apps
      .filter((app) => app.forge && app.granted)
      .map(({ id, name, forge, fullName }) => ({ id, name, forge, fullName })),
  };
}

export function buildPersistentMindIssueCapabilityPrompt({ enabled, catalog = { apps: [] } } = {}) {
  if (!enabled) {
    return `# Issue tracker capability
Issue filing access is OFF. Do not call issues.list or issues.file, and never claim an issue was filed.`;
  }
  const apps = boundedByJsonChars(catalog.apps, MAX_CATALOG_PROMPT_CHARS);
  if (apps.length === 0) {
    return `# Issue tracker capability
Issue filing access is ON, but no authorized managed app currently resolves to a GitHub or GitLab tracker, so there is nothing you can file against this wake. Say so rather than claiming work was queued.`;
  }
  return `# Issue tracker capability
Issue filing access is ON. Filing an issue is the PREFERRED way to queue concrete work: an issue is durable, a human can read and re-scope it, and a coding agent can claim it later even on a machine that has none attached right now. Prefer it over describing work only in conversation, and use it instead of a CoS task whenever you are not the one dispatching the work.

Read before you write. Call issues.list for the target app first and skip anything already tracked; duplicates are refused on an exact title match, but a near-duplicate still wastes the backlog. Only a result with complete: true and zero matches shows nothing matching among OPEN issues; a truncated result (see truncationReasons) or a null totalOpen proves nothing, and closed issues are never listed.

File with issues.file. Write the body so someone can pick it up cold: what is wrong or missing, where in the repo, why it matters now, and the chosen fix. Do not file speculative or future-only refactors.

A filed issue is world-readable. Write the title and body in your own prose and never paste in a secret, an absolute filesystem path, a hostname, network address, personal name, contact detail, or the contents of a private record — refer to a file by its repo-relative path instead. Home-directory prefixes and credential-shaped strings are stripped before filing, but that scrub cannot recognize a private record, so keeping one out is on you.

Both dispatch axes are required and independent — never derive one from the other, and do not stamp medium on both by reflex:
- model: ${DISPATCH_MODEL_TIERS.join(', ')} — the CAPABILITY the work needs, from mechanical (a rename, a config change, a well-specified single-file edit) through routine multi-file work and genuinely hard reasoning (concurrency, schema/compatibility design, redesign) to exceptional frontier reasoning.
- effort: ${DISPATCH_EFFORT_LEVELS.join(', ')} — the REASONING BUDGET per step, independent of the model. A mechanical sweep across many call sites is the lowest model tier at the highest effort; a two-line change hinging on one idea is a high model tier at low effort.

Optional category labels: ${Object.keys(PERSISTENT_MIND_ISSUE_CATEGORY_LABELS).join(', ')}. Every issue you file is additionally marked '${PERSISTENT_MIND_ISSUE_LABEL}' and attributed to the model that planned it.

Authorized apps (ids are authoritative; do not invent ids):
${JSON.stringify(apps)}`;
}

/**
 * Re-check the live grant and resolve the forge for one request. Returns
 * `{ error }` for every refusal so the caller renders one bounded message.
 */
const resolveTarget = async (appId) => {
  const root = await loadState();
  const capabilities = normalizePersistentMindCapabilities(root.config?.persistentMindCapabilities);
  if (!capabilities.fileIssues) return { error: 'Persistent mind issue access is disabled' };
  const app = (await readPersistentMindManagedApps()).find((candidate) => candidate.id === appId);
  if (!app) return { error: `App '${appId}' has no configured repository` };
  if (!app.granted) {
    return { error: `Managed app '${appId}' is not authorized for Persistent Mind work; update Persistent Mind Tools permissions` };
  }
  if (!app.forge) {
    return { error: `App '${appId}' has no GitHub or GitLab issue list; check its work tracker and git remote` };
  }
  return { app, root };
};

// Headroom under the adapter's 4,000-char tool-result ceiling (see
// persistentMindAdapter.boundedToolResult), so the structured rows survive intact.
const LIST_RESULT_BUDGET_CHARS = 3_500;
const LIST_TITLE_CHARS = 120;
// Progressively leaner row shapes; previews go first, then optional detail.
const LIST_ROW_DETAIL_LEVELS = [
  { preview: PERSISTENT_MIND_ISSUE_LIMITS.bodyPreviewChars, detail: true },
  { preview: 200, detail: true },
  { preview: 0, detail: true },
  { preview: 0, detail: false },
];

const projectIssueRow = (issue, { preview, detail }) => ({
  number: issue.number,
  title: String(issue.title || '').slice(0, LIST_TITLE_CHARS),
  url: issue.url,
  ...(detail ? { labels: issue.labels.map((label) => label.name), assignees: issue.assignees, updatedAt: issue.updatedAt } : {}),
  ...(preview ? { bodyPreview: String(issue.body || '').slice(0, preview) } : {}),
});

/** Fit rows under the budget: shrink detail first, then drop trailing rows (never to zero). */
const fitIssueRows = (matches, envelope) => {
  const size = (rows) => JSON.stringify({ ...envelope, issues: rows }).length;
  for (const level of LIST_ROW_DETAIL_LEVELS) {
    const rows = matches.map((issue) => projectIssueRow(issue, level));
    if (size(rows) <= LIST_RESULT_BUDGET_CHARS) return rows;
  }
  const lean = matches.map((issue) => projectIssueRow(issue, LIST_ROW_DETAIL_LEVELS.at(-1)));
  while (lean.length > 1 && size(lean) > LIST_RESULT_BUDGET_CHARS) lean.pop();
  return lean;
};

/**
 * Open issues on the app's tracker, projected down to what a prompt can use.
 *
 * Completeness is reported explicitly so a conclusive negative is never inferred
 * from a partial read: `complete` is true only when the whole open backlog was
 * enumerated, every body that was searched was whole, and no matching row was
 * omitted. `totalOpen` is the exact open count, or null when the forge page was
 * capped (`fetchedCount` is then only the page size).
 */
export async function listPersistentMindIssues(args) {
  const { app, error } = await resolveTarget(args.appId);
  if (error) return { ok: false, error };
  const result = await listAppIssues(app);
  if (result.transient) {
    return { ok: false, error: `Could not read the ${app.forge} issue list (${result.reason}); ${result.remedy || 'retry once the forge CLI is reachable'}` };
  }
  const search = args.search ? args.search.toLowerCase() : null;
  const limit = args.limit || PERSISTENT_MIND_ISSUE_LIMITS.defaultListLimit;
  const matches = result.issues
    .filter((issue) => !args.label || issue.labels.some((label) => label.name === args.label))
    .filter((issue) => !search || `${issue.title}\n${issue.body}`.toLowerCase().includes(search));
  const limited = matches.slice(0, limit);

  const fetchedCount = result.issues.length;
  const sourceCapped = Boolean(result.enumeration?.capped);
  const envelope = {
    ok: true,
    appId: args.appId,
    forge: app.forge,
    repository: result.fullName,
    totalOpen: sourceCapped ? null : fetchedCount,
    fetchedCount,
    matchedCount: matches.length,
    returnedCount: limited.length,
    complete: true,
    truncated: false,
    truncationReasons: ['source-limit', 'body-clipped', 'row-limit', 'response-budget'],
  };
  const issues = fitIssueRows(limited, envelope);

  const reasons = [];
  if (sourceCapped) reasons.push('source-limit');
  if (search && result.enumeration?.bodiesClipped) reasons.push('body-clipped');
  if (matches.length > limited.length) reasons.push('row-limit');
  if (limited.length > issues.length) reasons.push('response-budget');
  return {
    ...envelope,
    issues,
    returnedCount: issues.length,
    complete: reasons.length === 0,
    truncated: reasons.length > 0,
    truncationReasons: reasons,
  };
}

/** File one issue on the app's tracker. */
export async function filePersistentMindIssue(args) {
  const { app, root, error } = await resolveTarget(args.appId);
  if (error) return { ok: false, error };
  const cli = forgeCliForTracker(app.forge);

  // The reachability probe runs before anything is created: on an unreachable
  // forge this is one failing call instead of a whole label fan-out that each
  // has to time out first. Kept ahead of the duplicate read below rather than
  // folded into `fileForgeIssue`'s own probe — an unreachable forge should
  // short-circuit before that read runs at all, not after.
  const probe = await probeForgeReachability({ cli, hostname: app.apiHost, label: 'mind-issue-file' });
  if (!probe.ok) return { ok: false, error: probe.error };

  // Duplicate guard. A failed read must NOT read as "nothing is tracked" — that
  // is exactly how a transient `gh` blip files the same issue twice — so an
  // unreadable tracker refuses the file rather than proceeding blind.
  const existing = await listAppIssues(app);
  if (existing.transient) {
    return { ok: false, error: `Could not read the existing ${app.forge} issues to check for duplicates (${existing.reason}); nothing was filed` };
  }
  // Scrubbed BEFORE the duplicate check, not just before the create: the title
  // that dedupes has to be the title that gets filed, or an issue whose only
  // leaked path was in its title would re-file itself on every wake. Used only
  // for the dedup key here — `fileForgeIssue` below gets the RAW args and
  // scrubs its own copy, so the text is scrubbed exactly once rather than
  // twice for the same request.
  const title = scrubForgeIssueText(args.title);
  const _body = scrubForgeIssueText(args.body);

  // An all-punctuation title normalizes to the empty string, which would match
  // every other such title — only a title with real content can dedupe.
  const titleKey = normalizeIssueTitleKey(title);
  const duplicate = titleKey
    && existing.issues.find((issue) => normalizeIssueTitleKey(issue.title) === titleKey);
  if (duplicate) {
    return {
      ok: true, duplicate: true, number: duplicate.number, url: duplicate.url,
      summary: `Issue #${duplicate.number} already tracks this work; nothing new was filed`,
    };
  }

  const profile = normalizePersistentMindProfile(root.config?.persistentMindProfile);
  const labels = [
    PERSISTENT_MIND_ISSUE_LABEL,
    ...forgeIssueLabels({
      cli,
      model: args.model,
      effort: args.effort,
      // The planner axis records who WROTE the plan — this mind's own model —
      // and is independent of the model:/effort: dispatch hints above.
      planner: resolvePlannerId({ providerId: profile.providerId, model: profile.model }),
    }),
    ...(args.labels || []),
  ].filter((name, index, all) => all.indexOf(name) === index);

  const created = await fileForgeIssue({
    cli, title: args.title, body: args.body, repoPath: app.repoPath,
    repo: cli === 'glab' ? null : app.repoSpec,
    labels: labels.map((name) => labelSpec(name, cli)).filter(Boolean),
  });
  if (!created.ok) return created;
  return {
    ok: true,
    duplicate: false,
    appId: args.appId,
    forge: app.forge,
    repository: app.fullName,
    number: created.number,
    url: created.url,
    labels,
    summary: `Filed ${created.number ? `#${created.number}` : 'an issue'} on ${app.fullName || app.forge}`,
  };
}