ops

Operator console for the Snappy agent system.

Ported from kernel snappy-ops in Phase 0.5. See state/lib/ops/api.ts for the full API surface.

Steps

• systemStatus() - see state/lib/ops/api.ts
• inboxSummary() - see state/lib/ops/api.ts
• runChains() - see state/lib/ops/api.ts
• lastChainRun() - see state/lib/ops/api.ts
• run() - see state/lib/ops/api.ts
• recentActions() - see state/lib/ops/api.ts
• trace() - see state/lib/ops/api.ts
• story() - see state/lib/ops/api.ts
• replayRun() - see state/lib/ops/api.ts
• dryRecipe() - see state/lib/ops/api.ts
• drySkill() - see state/lib/ops/api.ts
• settleDelta() - see state/lib/ops/api.ts
• listSettled() - see state/lib/ops/api.ts
• addReminder() - see state/lib/ops/api.ts
• listReminders() - see state/lib/ops/api.ts
• markReminderDone() - see state/lib/ops/api.ts
• shareArtifact() - see state/lib/ops/api.ts
• listRecipes() - see state/lib/ops/api.ts

Eval

Actor: the exported functions in state/lib/ops/api.ts. Auditor: none wired yet - eval is manual (Robert review). File a state/log/pending-eval.ndjson row on each run.

Score convention:

Gotchas

via the Phase 0.5 driver. Only these rewrites were applied: already in state/lib/)

1. realpathSync(process.argv[1]) CLI guard wrapped in try/catch

• See the kernel SKILL.md for the original long-form guidance if you need it

(read-only reference at the kernel path above).

Graduation

This skill is prose. Graduate by defining a deterministic auditor and flipping eval: auto.

Rubric

criteria:
  - name: api_functions_exist
    kind: deterministic
    check: "The file 'state/lib/ops/api.ts' exists and exports all functions listed in SKILL.md under 'Steps'."
  - name: logs_pending_eval
    kind: deterministic
    check: "A new entry for this skill execution was appended to 'state/log/pending-eval.ndjson'."
  - name: function_calls_match_api
    kind: judge
    check: "The skill's output indicates that its console actions correctly invoked the corresponding functions within 'state/lib/ops/api.ts'."

ops - loader

Per-turn rules for the ops skill. Full reference: state/skills/ops/SKILL.md. Do not skip these.

Critical Rules

• This is the operator console - broad dispatch surface (chains, recipes, reminders, artifacts). Use the most specific function rather than run() blindly.
• Dry-run paths exist (dryRecipe(), drySkill()) - use them before any run() that has side effects. Scope-only is the program.md default.
• Phase 0.5 mechanical port from snappy-ops; the kernel had vendored staged-action, registry, loops, and recipes/ subdirs (see state/lib/ops/api.ts). Reach into the vendored dir when an op isn't on the top-level api.ts surface.
• replayRun() reads from chain.ndjson - confirm a run_id exists before passing it; replay of a missing run is a silent no-op

Commands

| ui dashboard | state/skills/ops/resources/ui.openui | |invoke: import from state/lib/ops/api.ts - systemStatus, inboxSummary, runChains, lastChainRun, run, recentActions, trace, story, replayRun, dryRecipe, drySkill, settleDelta, listSettled, addReminder, listReminders, markReminderDone, shareArtifact, listRecipes |eval log: state/log/pending-eval.ndjson (manual review until shape gate added)

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/ops/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• The vendored state/lib/ops/ is a directory with sub-modules - imports that look up state/lib/ops.ts (file) will fail; use state/lib/ops/api.ts (dir/file)
• Skill frontmatter says eval: shape but no auditor wired - log to pending-eval.ndjson
• staged-action is a key concept here - staged actions are scope-only by default and require explicit apply to fire

Self-Test

An agent reading this should correctly:

1. [ ] Reach for dryRecipe() / drySkill() before invoking run() with side effects?
2. [ ] Import from state/lib/ops/api.ts (vendored dir) not a non-existent state/lib/ops.ts?
3. [ ] Confirm a run_id exists in chain.ndjson before calling replayRun()?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] ops: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] ops: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.