v0.3.0 — production-ready SDK surface + action executor - #2
Merged
Conversation
…vability (v0.3.0) This is the first production-ready release. Adds the high-level SDK surface, structured error hierarchy, observability hooks, and session persistence on top of the v0.2 wire-format conversion. API additions - createBrowser() / Browser / Page wrappers — small surface (page.goto, page.snapshot, page.execute) hides Playwright details while keeping .raw escape hatches. - executeAction() covers all 17 ActionTypes with one execute(actionId, value?) entry point. Resolves binding, dispatches Playwright op, validates value types, classifies errors, disposes element handles in finally. - AgentMarkError hierarchy with stable error codes: SnapshotError, ExecutionError (+ ActionNotFoundError, ActionDisabledError, ActionTypeError, ElementNotFoundError, ExecutionTimeoutError), SessionError. Prototype-chain preserved; isAgentMarkError() type guard. - Branded ID types — ActionId, MediaId, RegionId for nominal type safety, zero runtime overhead. - Pluggable Logger interface — noopLogger (default, zero-overhead) and consoleLogger (JSON-lines for dev). Threaded through Browser → Page → executor; emits typed AgentMarkEvent strings. - Session persistence — browser.saveSession(path) / sessionPath option for cookie + storageState round-trips. Atomic write via temp+rename. Versioned file format (session_format: '1'). - Honeypot refusal — actions marked honeypot: true throw ActionDisabledError. Tests (141 total, all passing) - 25 new unit tests for the executor (pre-flight validation, value types, element resolution, observability, error hierarchy, prototype chain). - 5 new unit tests for session persistence (load, version mismatch, missing fields, invalid JSON, missing file). - 11 new benchmark tests with absolute byte budgets per fixture and 5ms speed budgets. Prints compression-ratio summary table on every run (current baseline: 55x overall token savings vs simulated raw HTML). - 10 new real-Chromium integration tests gated on AGENTMARK_INTEGRATION=1. Covers snapshot capture, form fill + submit + redirect (including the password-redaction security feature), disabled-action refusal, navigation invalidation, session round-trip across browser instances, idempotent close, end-to-end logger event flow. Infra - CI now has three jobs: test (Node 20+22 unit), integration (Chromium + AGENTMARK_INTEGRATION=1), macos-smoke (cross-platform regression catch). All gate publish. - examples/basic.ts — snapshot + dump available actions to stdout. - examples/with-claude.ts — caller's-loop demo using @anthropic-ai/sdk tool use; proves library-only positioning by showing the loop lives in the caller, not in AgentMark. - CHANGELOG.md — full v0.3.0 release notes plus retroactive v0.2.0 / v0.1.0. - README rewritten with SDK quick-start as headline; observability and error-handling sections added; lower-level APIs preserved. Production-readiness gates cleared - Type safety: zero any in new code; branded IDs prevent type confusion - Error taxonomy: full hierarchy, stable codes, prototype-chain safe - Observability: every public op emits structured events; default no-op - Atomic writes: sessions never leave partial files - Backwards compatibility: all 90 v0.2 tests still passing - Cross-platform: build clean; CI now Linux + macOS Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 10, 2026
This was referenced May 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
First production-ready release. Builds the high-level SDK surface, structured error hierarchy, observability hooks, and session persistence on top of the v0.2 wire-format conversion.
createBrowser()/Browser/Page— small SDK surface (page.goto,page.snapshot,page.execute) any AI can drive. Library-only — no agent loop, no LLM client, no prompts. Caller (Claude, GPT, AP flow, etc.) brings the loop.executeAction()covers all 17ActionTypes with a singleexecute(actionId, value?)entry point. Validates values, classifies errors, disposes handles infinally.AgentMarkError→SnapshotError,ExecutionError(+ 5 specialized subclasses),SessionError. Stable error codes, prototype-chain safe,isAgentMarkError()type guard.ActionId,MediaId,RegionIdfor nominal type safety with zero runtime cost.Loggerinterface;noopLogger(default) +consoleLogger(JSON-lines). TypedAgentMarkEventevent catalog.browser.saveSession(path)+sessionPathoption, atomic temp+rename writes, versioned file format.ActionDisabledError, never execute.Numbers
strict: true, zeroanyin new code.CI changes
Three jobs now gate
publish:test— Node 20 + 22 unit tests on Linuxintegration— installs Chromium, runsAGENTMARK_INTEGRATION=1against the new SDK surfacemacos-smoke— catches cross-platform regressions in converter / serializer pathsTest plan
npm install && npm run build && npm test— all 131 unit + benchmark tests passAGENTMARK_INTEGRATION=1 npm test(with Chromium installed) — 10 integration tests passtest,integration,macos-smokenpx tsx examples/basic.tsANTHROPIC_API_KEY=… npx tsx examples/with-claude.ts "find the contact email" "https://example.com"convertPage(),serializeSnapshot(),parseSnapshot(),validateSnapshot(),InMemoryActionBindingall still importable and worksrc/index.tsfor naming consistency🤖 Generated with Claude Code