@xn-intenton-z2a/agentic-lib 7.1.65 → 7.1.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.1.65",
+  "version": "7.1.67",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

package/src/actions/agentic-step/index.js

@@ -151,6 +151,7 @@ async function run() {
         promptBudget: result.promptBudget,
         closingNotes,
         transformationCost,
+        narrative: result.narrative,
       });
     }
 

package/src/actions/agentic-step/logging.js

@@ -34,6 +34,7 @@ import * as core from "@actions/core";
  * @param {Array} [options.promptBudget] - Prompt budget entries { section, size, files, notes }
  * @param {string} [options.closingNotes] - Auto-generated limit concern notes
  * @param {number} [options.transformationCost] - Transformation cost for this entry (0 or 1)
+ * @param {string} [options.narrative] - LLM-generated narrative description of the change
  */
 export function logActivity({
   filepath,
@@ -57,6 +58,7 @@ export function logActivity({
   promptBudget,
   closingNotes,
   transformationCost,
+  narrative,
 }) {
   const dir = dirname(filepath);
   if (!existsSync(dir)) {
@@ -110,6 +112,10 @@ export function logActivity({
     parts.push("", "### Closing Notes");
     parts.push(closingNotes);
   }
+  if (narrative) {
+    parts.push("", "### Narrative");
+    parts.push(narrative);
+  }
   if (details) {
     parts.push("");
     parts.push(details);

package/src/actions/agentic-step/tasks/fix-code.js

@@ -98,7 +98,7 @@ async function resolveConflicts({ config, pr, prNumber, instructions, model, wri
   ].join("\n");
 
   const t = config.tuning || {};
-  const { tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+  const { tokensUsed, inputTokens, outputTokens, cost, content: resultContent } = await runCopilotTask({
     model,
     systemMessage: `You are resolving git merge conflicts on PR #${prNumber}. Write resolved versions of each conflicted file, removing all conflict markers. Preserve the PR's feature intent while incorporating main's updates.`,
     prompt,
@@ -116,6 +116,7 @@ async function resolveConflicts({ config, pr, prNumber, instructions, model, wri
     cost,
     model,
     details: `Resolved ${conflicts.length} conflicted file(s) on PR #${prNumber}`,
+    narrative: (resultContent || "").substring(0, 2000),
   };
 }
 
@@ -186,7 +187,7 @@ export async function fixCode(context) {
   ].join("\n");
 
   const t = config.tuning || {};
-  const { tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+  const { tokensUsed, inputTokens, outputTokens, cost, content: resultContent } = await runCopilotTask({
     model,
     systemMessage: `You are an autonomous coding agent fixing failing tests on PR #${prNumber}. Make minimal, targeted changes to fix the test failures.`,
     prompt,
@@ -204,5 +205,6 @@ export async function fixCode(context) {
     cost,
     model,
     details: `Applied fix for ${failedChecks.length} failing check(s) on PR #${prNumber}`,
+    narrative: (resultContent || "").substring(0, 2000),
   };
 }

package/src/actions/agentic-step/tasks/resolve-issue.js

@@ -99,5 +99,6 @@ export async function resolveIssue(context) {
     model,
     commitUrl: null,
     details: `Generated code for issue #${issueNumber}: ${resultContent.substring(0, 200)}`,
+    narrative: (resultContent || "").substring(0, 2000),
   };
 }

package/src/actions/agentic-step/tasks/transform.js

@@ -183,6 +183,7 @@ export async function transform(context) {
     cost,
     model,
     details: resultContent.substring(0, 500),
+    narrative: (resultContent || "").substring(0, 2000),
     promptBudget,
     contextNotes: `Transformed with ${sourceFiles.length} source files (mtime-sorted, cleaned), ${features.length} features, ${openIssues.length} issues (${rawIssues.length - openIssues.length} stale filtered).`,
   };

package/src/seeds/missions/c64-emulator.md

@@ -1,110 +1,164 @@
 # Mission
 
-A JavaScript Commodore 64 emulator capable of running the classic game "The Lords of Midnight" (1984, Mike Singleton).
+A JavaScript Commodore 64 emulator that runs in the browser, capable of playing the classic game "The Lords of Midnight" (1984, Mike Singleton).
+
+## Browser Presentation
+
+The emulator runs entirely in the browser as a single-page application:
+
+- **Canvas rendering** — VIC-II output drawn to an HTML `<canvas>` element at native 320x200, scaled with CSS `image-rendering: pixelated`.
+- **Web Audio API** — SID output fed to an `AudioWorklet` (or `ScriptProcessorNode` fallback) for real-time sound.
+- **Keyboard input** — browser `keydown`/`keyup` events mapped to the C64 keyboard matrix.
+- **ROM loading** — user provides KERNAL, BASIC, and character ROM files via file input or drag-and-drop. ROMs are NOT bundled (they are copyrighted).
+- **PRG loading** — user loads `.prg` game files via file input or drag-and-drop.
+- **Responsive layout** — centred emulator screen with C64-style colour scheme, status bar showing cycle count and FPS.
+
+Website files under `public/`:
+
+| File | Purpose |
+|------|---------|
+| `public/index.html` | Main page — canvas, file inputs, controls |
+| `public/style.css` | C64-themed styling (dark blue background, light blue text) |
+| `public/emulator.js` | Browser entry point — imports core lib, wires up canvas/audio/input |
 
 ## Architecture
 
-The emulator is structured as layered components, each independently testable:
+The core emulator is structured as independently testable modules under `src/lib/`:
+
+| File | Module | Purpose |
+|------|--------|---------|
+| `src/lib/main.js` | Entry point | Re-exports all public API functions from submodules |
+| `src/lib/cpu.js` | MOS 6510 CPU | 6502 variant with I/O port at $00/$01 |
+| `src/lib/opcodes.js` | Opcode table | Data-driven array of 256 entries (mnemonic, addressing mode, cycles, handler) |
+| `src/lib/memory.js` | Memory subsystem | 64KB RAM, ROM banking, I/O area routing |
+| `src/lib/vic.js` | VIC-II video | Text/bitmap modes, sprites, raster interrupts, framebuffer |
+| `src/lib/sid.js` | SID sound | 3-voice synthesiser, ADSR envelopes, PCM output |
+| `src/lib/cia.js` | CIA timers | Timer interrupts, keyboard matrix scanning, joystick |
+| `src/lib/input.js` | Input mapping | Browser key event codes to C64 8x8 keyboard matrix |
+| `src/lib/loader.js` | PRG loader | Parse `.prg` header and load data into memory |
+| `src/lib/c64.js` | Machine | Wires all subsystems together, provides `createC64()` and `runFrame()` |
+
+This multi-file structure allows the agent to iterate on each subsystem independently without hitting context limits. Each module has a corresponding test file under `tests/`.
 
-1. **MOS 6510 CPU** — the core processor (6502 variant with I/O port at $00/$01)
-2. **Memory subsystem** — 64KB RAM, ROM banking (BASIC, KERNAL, character ROM), I/O area ($D000–$DFFF)
-3. **VIC-II video** — text mode (40x25), bitmap mode, sprites, raster interrupt timing
-4. **SID sound** — 3-voice synthesiser with ADSR envelopes (basic waveform generation)
-5. **CIA timers** — two CIA chips for keyboard scanning, timer interrupts, and joystick input
-6. **Input** — keyboard matrix and joystick mapped to browser events
-7. **PRG/TAP loader** — load `.prg` files (and optionally `.tap` tape images) into memory
+## Research Phase
 
-## Core Functions
+During web-search and document-gathering workflow phases, the agent should look up:
 
-Export all from `src/lib/main.js`:
+- **6502/6510 opcode reference** — complete instruction set with addressing modes, cycle counts, and flag effects. Key resource: "6502 Instruction Set" tables listing all 151 official opcode variants.
+- **VIC-II register map** — all registers at $D000–$D03F, their bit layouts, and behaviour (C64 Programmer's Reference Guide).
+- **SID register map** — registers at $D400–$D41C, waveform generation, ADSR timing.
+- **CIA register map** — CIA1 ($DC00–$DC0F) and CIA2 ($DD00–$DD0F), keyboard matrix wiring, timer modes.
+- **C64 keyboard matrix** — the 8x8 matrix mapping (which row/column pair for each physical key).
+- **C64 colour palette** — the 16 VIC-II colours as RGB values.
+- **Lords of Midnight technical details** — memory layout, which C64 features the game uses, loading address.
+- **Existing open-source C64 emulators in JavaScript** — study approaches (e.g. virtual6502, SAE, c64js) for implementation patterns and known pitfalls.
 
-- `createC64(opts?)` — create an emulator instance with default ROMs and 64KB RAM. Returns an object with `cpu`, `memory`, `vic`, `sid`, `cia1`, `cia2` subsystems.
-- `loadPRG(c64, data)` — load a `.prg` file (Uint8Array) into memory at the address specified in its two-byte header.
-- `step(c64)` — execute one CPU instruction, advance cycle count, and update timers. Returns the new state.
-- `runFrame(c64)` — execute instructions for one video frame (~19656 cycles PAL). Trigger raster interrupts at the appropriate scanlines. Returns the framebuffer.
-- `getFramebuffer(c64)` — return the current screen as a Uint8Array RGBA pixel buffer (320x200 or 384x272 with borders).
+The opcode table in particular should be assembled from reference data during the research phase and stored as `src/lib/opcodes.js` — a data-driven 256-entry array — rather than hand-coded instruction by instruction. This avoids the agent losing track of which opcodes are implemented and reduces the chance of transcription errors.
+
+## Core API
+
+Export from `src/lib/main.js` (re-exporting from submodules):
+
+- `createC64(opts?)` — create an emulator instance with 64KB RAM and subsystem objects (`cpu`, `memory`, `vic`, `sid`, `cia1`, `cia2`).
+- `loadROMs(c64, { kernal, basic, chargen })` — load ROM images (Uint8Arrays). Must be called before running.
+- `loadPRG(c64, data)` — load a `.prg` file (Uint8Array) into memory at the address from its two-byte header.
+- `step(c64)` — execute one CPU instruction, advance cycle count, update timers. Returns the updated state.
+- `runFrame(c64)` — execute one PAL video frame (~19656 cycles). Fire raster interrupts. Returns the RGBA framebuffer.
+- `getFramebuffer(c64)` — return the current screen as a Uint8Array RGBA pixel buffer (320x200).
 - `pressKey(c64, key)` / `releaseKey(c64, key)` — simulate keyboard input via CIA1 keyboard matrix.
 - `joystickInput(c64, port, directions)` — set joystick state (up/down/left/right/fire) on port 1 or 2.
-- `reset(c64)` — perform a hardware reset (set CPU to reset vector, clear state).
+- `reset(c64)` — hardware reset (CPU to reset vector, clear subsystem state).
 
-## CPU Requirements
+## CPU (src/lib/cpu.js, src/lib/opcodes.js)
 
 - All official 6502 opcodes (56 instructions, 151 opcode variants) with correct cycle counts.
-- Decimal mode (BCD arithmetic) support.
+- Decimal mode (BCD arithmetic).
 - IRQ and NMI interrupt handling with correct stack behaviour.
-- The 6510 I/O port at $00/$01 for ROM/RAM bank switching.
-- Undocumented/illegal opcodes are NOT required (may be implemented as NOP).
+- 6510 I/O port at $00/$01 for ROM/RAM bank switching.
+- Undocumented/illegal opcodes: implement as NOP (not required for Lords of Midnight).
+- The opcode table (`opcodes.js`) is a data-driven array of 256 entries to keep the code manageable and verifiable against reference data gathered during the research phase.
 
-## Memory Map
+## Memory (src/lib/memory.js)
 
 - $0000–$00FF: Zero page
 - $0100–$01FF: Stack
 - $0200–$9FFF: Free RAM (programs load here)
 - $A000–$BFFF: BASIC ROM (banked, RAM underneath)
 - $C000–$CFFF: Free RAM
-- $D000–$D3FF: VIC-II registers
-- $D400–$D7FF: SID registers
+- $D000–$D3FF: VIC-II registers (routed to VIC-II module)
+- $D400–$D7FF: SID registers (routed to SID module)
 - $D800–$DBFF: Colour RAM (nibbles)
-- $DC00–$DCFF: CIA1 (keyboard, joystick, timer)
-- $DD00–$DDFF: CIA2 (serial, timer, VIC bank)
+- $DC00–$DCFF: CIA1 registers (routed to CIA module)
+- $DD00–$DDFF: CIA2 registers (routed to CIA module)
 - $E000–$FFFF: KERNAL ROM (banked, RAM underneath)
 
-## Video (VIC-II)
+## Video — VIC-II (src/lib/vic.js)
 
-- Standard text mode (mode 0) — 40x25 characters, 16 colours, character ROM.
+- Standard text mode (40x25 characters, 16 colours, character ROM).
 - Multicolour text mode.
 - Standard bitmap mode (320x200) and multicolour bitmap mode (160x200).
 - Hardware sprites (8 sprites, 24x21 pixels, multicolour optional).
 - Raster interrupt — trigger IRQ at a programmable scanline.
-- Border colour and background colour registers.
-- Correct raster timing is essential — Lords of Midnight uses raster effects.
+- Border and background colour registers.
+- Correct raster timing — Lords of Midnight uses raster effects.
 
-## Sound (SID — basic)
+## Sound — SID (src/lib/sid.js)
 
-- 3 oscillator voices with waveform selection (triangle, sawtooth, pulse, noise).
+- 3 oscillator voices: triangle, sawtooth, pulse, noise waveforms.
 - ADSR envelope per voice.
 - Frequency and pulse-width registers.
-- Audio output as PCM sample buffer suitable for Web Audio API playback.
+- Audio output as PCM sample buffer (44100 Hz, mono) for Web Audio API.
 - Full filter emulation is NOT required (passthrough acceptable).
 
-## Input
+## Input (src/lib/input.js, src/lib/cia.js)
 
-- CIA1 keyboard matrix scan — map browser `KeyboardEvent` codes to the C64 8x8 keyboard matrix.
-- Joystick via CIA1 ($DC01 port 1) and CIA1 ($DC00 port 2) — Lords of Midnight uses keyboard, but joystick support enables other games.
+- CIA1 keyboard matrix — map browser `KeyboardEvent.code` values to the C64 8x8 keyboard matrix.
+- Joystick via CIA1 port registers — Lords of Midnight uses keyboard, but joystick support enables other games.
 
 ## Lords of Midnight Compatibility
 
-The target game exercises these specific features:
+The target game exercises:
 - Custom character sets (redefined at $3000 or similar)
 - Full keyboard input (directional + action keys)
 - Raster interrupts for split-screen effects
 - IRQ-driven game loop timing via CIA timer
 - PRG loading at the correct start address
 
+## Test Strategy
+
+Testing a full emulator requires care to avoid the verification gap (passing unit tests but failing on real software):
+
+- **CPU tests**: verify each addressing mode and instruction against known-good results. Use the research-phase opcode reference to generate expected values. Test interrupt handling (IRQ vector jump, flag push, RTI return).
+- **Memory tests**: test bank switching ($01 register), I/O area routing, ROM overlay behaviour.
+- **VIC-II tests**: set known register states, render one frame, verify specific pixels in the framebuffer.
+- **Input tests**: simulate key press sequences, verify CIA1 port reads return correct matrix values.
+- **Stub ROMs**: tests use minimal ROMs — just enough to set the reset vector ($FFFC/$FFFD) and RTI from the IRQ vector. The agent should create these as hex-encoded Uint8Arrays in the test fixtures.
+- **Integration test**: a small test PRG (hex-encoded in the test file) that writes "HELLO" to screen RAM ($0400) and halts. Run it, verify the framebuffer contains the correct character glyphs.
+- **Smoke test for the browser UI**: verify `public/index.html` loads without errors and the canvas element is present (can use a headless browser or DOM parser).
+
 ## Requirements
 
-- No external dependencies for the core emulator (Web Audio API and Canvas API are browser-provided).
-- KERNAL and BASIC ROMs must NOT be bundled (they are copyrighted). Provide a `loadROMs(c64, { kernal, basic, chargen })` function. Tests should use minimal stub ROMs.
-- Comprehensive unit tests for each subsystem:
-  - CPU: test each addressing mode and instruction, verify cycle counts, test interrupt handling.
-  - Memory: test bank switching, I/O area mapping.
-  - VIC-II: test mode switching, framebuffer output for known register states.
-  - Input: test keyboard matrix encoding/decoding.
-- Integration test: load a small test PRG that writes to screen memory and verify framebuffer output.
-- README with architecture overview, usage example, and instructions for obtaining legal ROM dumps.
+- No external runtime dependencies — pure JavaScript using only browser-provided APIs (Canvas, Web Audio, File API).
+- ROMs must NOT be bundled. The `loadROMs()` function and browser drag-and-drop accept user-supplied ROM files.
+- Multi-file structure as specified in the Architecture section.
+- The `public/` website is self-contained and can be served with any static file server.
+- README with architecture overview, browser usage instructions, and guidance on obtaining legal ROM dumps.
 
 ## Acceptance Criteria
 
 - [ ] CPU executes all 151 official opcodes with correct results and cycle counts
 - [ ] CPU handles IRQ and NMI interrupts correctly (push PC+flags, jump to vector)
 - [ ] Memory bank switching works ($01 register controls ROM/RAM visibility)
-- [ ] VIC-II text mode renders 40x25 character display to framebuffer
+- [ ] VIC-II text mode renders 40x25 character display to RGBA framebuffer
 - [ ] VIC-II raster interrupt fires at the programmed scanline
 - [ ] SID produces audible waveform output for at least triangle and pulse waves
 - [ ] CIA1 keyboard matrix correctly maps key presses to the scanned row/column
 - [ ] `loadPRG()` places data at the correct address from the PRG header
-- [ ] `runFrame()` executes approximately the right number of cycles per frame (PAL timing)
+- [ ] `runFrame()` executes the correct number of cycles per PAL frame (~19656)
 - [ ] A test PRG that writes "HELLO" to screen RAM ($0400) produces correct framebuffer output
 - [ ] `reset()` returns the emulator to a known initial state
+- [ ] Browser UI renders emulator output to canvas at 50 FPS (PAL rate)
+- [ ] Browser UI plays SID audio via Web Audio API
+- [ ] Browser UI accepts ROM and PRG files via drag-and-drop or file input
 - [ ] All unit tests pass
-- [ ] README documents architecture and ROM loading
+- [ ] README documents architecture, browser usage, and how to obtain legal ROM dumps

package/src/seeds/zero-package.json

@@ -16,7 +16,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.1.65"
+    "@xn-intenton-z2a/agentic-lib": "^7.1.67"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",