This commit is contained in:
309
packages/agent/src/skill-write-service.ts
Normal file
309
packages/agent/src/skill-write-service.ts
Normal file
@@ -0,0 +1,309 @@
|
||||
/**
|
||||
* 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 { InstallAuditStore } from '@waggle/core';
|
||||
|
||||
/** 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?: InstallAuditStore;
|
||||
/** 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 };
|
||||
}
|
||||
Reference in New Issue
Block a user