Files
waggle-os/packages/agent/src/skill-write-service.ts
shumeiko.it 2e08f2ae96 refactor(server): move the install audit trail from core to the server (P1.2, UF-040)
Core keeps only shared infrastructure, so InstallAuditStore leaves it and
lives in packages/server/src/local/install-audit.ts. The trail itself stays:
the Audit and Activity tabs, the extend and export routes, and the threat
model entry keep working on the same waggle.db table.

- @waggle/shared gets RecordAuditInput and the narrow InstallAuditRecorder
  (record only), which the agent's skill tools now depend on.
- The server creates the audit table before the one-time legacy copy, which
  no longer constructs it in core.
- UF-040: GET /api/debug/logs called prepare() on the store's private db
  wrapper, which has none, so the support bundle never carried recent
  installs. It now reads them through getRecentSummary().
2026-10-25 21:32:38 +01:00

310 lines
11 KiB
TypeScript

/**
* Shared skill-write service (P5/D4 binding iii).
*
* One module, one audit trail, two callers: the agent tool layer
* (`skill-tools.ts`) and the HTTP route layer (`routes/skills.ts`) both go
* through here so create / update / delete are redacted, provenance-stamped,
* and audited exactly once, the same way, regardless of who initiated.
*
* Per the D4(iii) AMENDED ruling, the agent tool does NOT call HTTP — it calls
* this in-process service directly. Caller-specific side effects (skill-hash
* store, agentState reload) stay in the caller; this service owns the file I/O,
* redaction, provenance, and audit write.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import { redactSkillContent } from './skill-redaction.js';
import type { SkillInitiator } from './skill-frontmatter.js';
import { parseSkillFrontmatter } from './skill-frontmatter.js';
import type { InstallAuditRecorder } from '@waggle/shared';
/** Shared deps for every skill-write op. auditStore/onChange degrade gracefully. */
export interface SkillWriteDeps {
/** Directory holding personal-scope SKILL.md files (~/.waggle/skills). */
skillsDir: string;
/** Audit store — when present, every op records an install_audit row. */
auditStore?: InstallAuditRecorder;
/** Called after a successful write/delete so the caller can hot-reload skills. */
onChange?: () => void;
}
export interface WriteSkillInput {
name: string;
/** Markdown content (raw or pre-generated). Redacted before persisting. */
content: string;
/** Who authored this write — stamped into provenance frontmatter + audit. */
initiator: SkillInitiator;
/** Where the write originated (e.g. 'chat', 'api', 'skill-creator'). */
source: string;
}
export interface DeleteSkillInput {
name: string;
initiator: SkillInitiator;
source: string;
}
export interface SkillWriteResult {
ok: boolean;
/** Absolute path written/deleted (present on success). */
path?: string;
/** True when the target already existed (update vs create). */
existed?: boolean;
/** Secrets/paths stripped before persisting (write ops only). */
redactions?: string[];
/** Set when ok=false. */
error?: string;
}
/** Reject names that could escape skillsDir or collide with shell-hostile chars. */
function invalidName(name: string): boolean {
return !name || !/^[a-zA-Z0-9_-]+$/.test(name);
}
/** Subdir under skillsDir holding pre-overwrite/pre-delete snapshots. */
const BACKUP_DIR = '.backups';
/** Newest N snapshots retained per skill; older are pruned. */
const BACKUP_KEEP = 5;
function backupsDirFor(skillsDir: string): string {
return path.join(skillsDir, BACKUP_DIR);
}
/**
* Monotonic, filesystem-safe, sortable stamp (e.g. 20260710T123456789Z). It
* never repeats within a process — colliding same-millisecond writes are bumped
* forward — so backup filenames stay unique and lexical sort == chronological.
*/
let lastStampMs = 0;
function nextBackupStamp(): string {
let now = Date.now();
if (now <= lastStampMs) now = lastStampMs + 1;
lastStampMs = now;
return new Date(now).toISOString().replace(/[-:.]/g, '');
}
/**
* Skill name a backup filename belongs to. The stamp is the suffix after the
* LAST '-' (and contains no '-' itself), so names with hyphens parse correctly.
*/
function backupSkillName(file: string): string | null {
if (!file.endsWith('.md')) return null;
const base = file.slice(0, -'.md'.length);
const lastDash = base.lastIndexOf('-');
if (lastDash <= 0) return null;
return base.slice(0, lastDash);
}
/** Backup filenames for one skill, newest first (exact-name match, not prefix). */
function backupsForSkill(skillsDir: string, name: string): string[] {
const dir = backupsDirFor(skillsDir);
if (!fs.existsSync(dir)) return [];
return fs
.readdirSync(dir)
.filter((f) => backupSkillName(f) === name)
.sort()
.reverse();
}
/**
* Snapshot the current on-disk skill bytes into .backups before it is
* overwritten or deleted, then prune to the newest BACKUP_KEEP. Best-effort: a
* backup failure must never block the primary write/delete.
*/
function stashBackup(skillsDir: string, name: string): void {
const filePath = path.join(skillsDir, `${name}.md`);
if (!fs.existsSync(filePath)) return;
try {
const dir = backupsDirFor(skillsDir);
if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(path.join(dir, `${name}-${nextBackupStamp()}.md`), fs.readFileSync(filePath));
for (const stale of backupsForSkill(skillsDir, name).slice(BACKUP_KEEP)) {
try { fs.unlinkSync(path.join(dir, stale)); } catch { /* best-effort prune */ }
}
} catch { /* backup is best-effort; never block the primary op */ }
}
/**
* Inject/overwrite `initiator` + `source` inside the content's frontmatter
* WITHOUT round-tripping through serializeFrontmatter (which is lossy — it drops
* unknown keys like custom `permissions:` blocks). Provenance is authoritative:
* any initiator/source the author embedded in the body is replaced, so a write
* can't spoof false provenance.
*/
function stampProvenance(content: string, initiator: SkillInitiator, source: string): string {
const provLines = [`initiator: ${initiator}`, `source: ${source}`];
if (content.startsWith('---')) {
const end = content.indexOf('\n---', 3);
if (end !== -1) {
const block = content.slice(3, end);
const afterDelimiter = end + 4; // '\n---'
const rest = content.slice(afterDelimiter);
// Strip any existing initiator/source lines, keep everything else.
const kept = block
.split('\n')
.filter((l) => {
const key = l.trim().toLowerCase();
return !key.startsWith('initiator:') && !key.startsWith('source:');
});
// Drop leading/trailing blank lines introduced by the filter.
while (kept.length && kept[0].trim() === '') kept.shift();
while (kept.length && kept[kept.length - 1].trim() === '') kept.pop();
const newBlock = [...kept, ...provLines].join('\n');
return `---\n${newBlock}\n---${rest}`;
}
}
// No frontmatter → prepend a minimal provenance block.
return `---\n${provLines.join('\n')}\n---\n\n${content}`;
}
/**
* Create or update a skill. Redacts secrets/paths, stamps provenance
* (sticky — an update preserves the original author rather than relaundering
* it), writes to disk, records an audit row, and fires onChange.
*/
export function writeSkill(deps: SkillWriteDeps, input: WriteSkillInput): SkillWriteResult {
const { skillsDir, auditStore, onChange } = deps;
const { name, content } = input;
if (invalidName(name)) {
return { ok: false, error: 'Invalid skill name (letters, numbers, hyphens, underscores only).' };
}
const filePath = path.join(skillsDir, `${name}.md`);
const existed = fs.existsSync(filePath);
// FILE provenance is sticky: if the skill already exists with an author,
// preserve it so an edit (by user OR agent) can't reclassify who CREATED it.
// The AUDIT row, by contrast, must record who performed THIS write (the actual
// actor) — D4(i) requires agent writes to audit initiator:'agent' even when
// editing a user-authored skill. The two must NOT share a variable.
let fileInitiator = input.initiator;
let fileSource = input.source;
if (existed) {
try {
const prior = parseSkillFrontmatter(fs.readFileSync(filePath, 'utf-8')).frontmatter;
if (prior.initiator) fileInitiator = prior.initiator;
if (prior.source) fileSource = prior.source;
} catch { /* unreadable prior — fall back to the input provenance */ }
}
const { content: safe, redactions } = redactSkillContent(content);
const stamped = stampProvenance(safe, fileInitiator, fileSource);
if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true });
// Snapshot the outgoing bytes before overwrite so the write is undoable.
if (existed) stashBackup(skillsDir, name);
fs.writeFileSync(filePath, stamped, 'utf-8');
try {
auditStore?.record({
capabilityName: name,
capabilityType: 'skill',
source: input.source,
riskLevel: 'low',
trustSource: 'local_user',
approvalClass: 'standard',
action: 'installed',
initiator: input.initiator,
detail: `${existed ? 'Updated' : 'Created'} skill via ${input.source}${redactions.length ? ` (redacted ${redactions.length})` : ''}.`,
});
} catch { /* audit is best-effort */ }
onChange?.();
return { ok: true, path: filePath, existed, redactions };
}
/**
* Delete a skill. Records an 'uninstalled' audit row (the action added in
* P5/D4 DEC-1) and fires onChange. Returns ok=false if the skill is absent.
*/
export function deleteSkill(deps: SkillWriteDeps, input: DeleteSkillInput): SkillWriteResult {
const { skillsDir, auditStore, onChange } = deps;
const { name, initiator, source } = input;
if (invalidName(name)) {
return { ok: false, error: 'Invalid skill name.' };
}
const filePath = path.join(skillsDir, `${name}.md`);
if (!fs.existsSync(filePath)) {
return { ok: false, error: `Skill "${name}" not found.` };
}
// Snapshot before unlink so a delete can be undone.
stashBackup(skillsDir, name);
fs.unlinkSync(filePath);
try {
auditStore?.record({
capabilityName: name,
capabilityType: 'skill',
source,
riskLevel: 'low',
trustSource: 'local_user',
approvalClass: 'standard',
action: 'uninstalled',
initiator,
detail: `Skill deleted via ${source}.`,
});
} catch { /* audit is best-effort */ }
onChange?.();
return { ok: true, path: filePath };
}
export interface UndoSkillInput {
name: string;
/** Who triggered the restore — recorded in the audit row. Defaults to 'agent'. */
initiator?: SkillInitiator;
}
export interface UndoSkillResult {
ok: boolean;
/** Absolute path of the restored skill file (present on success). */
path?: string;
/** Backup filename that was restored (present on success). */
restoredFrom?: string;
/** Set when ok=false. */
error?: string;
}
/**
* Restore a skill's newest backup through the sanctioned writeSkill seam: the
* snapshot bytes are re-written (source 'restored-from-backup'), which also
* snapshots the current bytes as a fresh backup, records an audit row, and
* fires onChange. Returns a clear error when no backup exists.
*/
export function undoSkillWrite(deps: SkillWriteDeps, input: UndoSkillInput): UndoSkillResult {
const { skillsDir } = deps;
const { name } = input;
if (invalidName(name)) {
return { ok: false, error: 'Invalid skill name.' };
}
const newest = backupsForSkill(skillsDir, name)[0];
if (!newest) {
return { ok: false, error: `No backup found for skill "${name}".` };
}
let bytes: string;
try {
bytes = fs.readFileSync(path.join(backupsDirFor(skillsDir), newest), 'utf-8');
} catch (err) {
return { ok: false, error: `Backup unreadable: ${err instanceof Error ? err.message : String(err)}` };
}
const res = writeSkill(deps, {
name,
content: bytes,
initiator: input.initiator ?? 'agent',
source: 'restored-from-backup',
});
if (!res.ok) return { ok: false, error: res.error };
return { ok: true, path: res.path, restoredFrom: newest };
}