{"_id":"@agent-ctrl/client","name":"@agent-ctrl/client","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.4":{"name":"@agent-ctrl/client","version":"0.1.4","description":"TypeScript client for the agent-ctrl daemon.","license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/k4cper-g/agent-ctrl.git","directory":"packages/client"},"homepage":"https://github.com/k4cper-g/agent-ctrl/tree/main/packages/client#readme","bugs":{"url":"https://github.com/k4cper-g/agent-ctrl/issues"},"keywords":["agent","automation","accessibility","uia","windows","ax","macos","darwin"],"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","test":"vitest run"},"engines":{"node":">=20"},"devDependencies":{"@types/node":"^22.10.0","typescript":"^5.6.3","vitest":"^4.1.10"},"gitHead":"7cc6b3d6d25ae6064aa1cf56d32df3af6e24a212","_id":"@agent-ctrl/client@0.1.4","_nodeVersion":"24.18.1","_npmVersion":"11.16.0","dist":{"integrity":"sha512-kJMRCqN3Asu5v3L/fkaNawjS9sShNe7C3R2dRYwndzKFvgWfJ5mPIHQ1JIeNzgpe4sBEXc3YiF5Ud+CqSWhVng==","shasum":"9db6ddbcae2fb9563a81c94fec3e131e20ae7bb7","tarball":"https://registry.npmjs.org/@agent-ctrl/client/-/client-0.1.4.tgz","fileCount":14,"unpackedSize":58521,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDoIIWw5wrwWso5hi4y91p46Y1hILuiFVuZYw2C5JrpGwIhAJ3qpYptWAk0IiCHmqvpCsiutee05Q9IsNdVPLRFfLOK"}]},"_npmUser":{"name":"k4cper-g","email":"k4cpergadomski@gmail.com"},"directories":{},"maintainers":[{"name":"k4cper-g","email":"k4cpergadomski@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/client_0.1.4_1785627722695_0.31117782792407933"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-01T23:42:02.525Z","0.1.4":"2026-08-01T23:42:02.846Z","modified":"2026-08-01T23:42:03.125Z"},"maintainers":[{"name":"k4cper-g","email":"k4cpergadomski@gmail.com"}],"description":"TypeScript client for the agent-ctrl daemon.","homepage":"https://github.com/k4cper-g/agent-ctrl/tree/main/packages/client#readme","keywords":["agent","automation","accessibility","uia","windows","ax","macos","darwin"],"repository":{"type":"git","url":"git+https://github.com/k4cper-g/agent-ctrl.git","directory":"packages/client"},"bugs":{"url":"https://github.com/k4cper-g/agent-ctrl/issues"},"license":"Apache-2.0","readme":"# @agent-ctrl/client\n\nTypeScript client for the [agent-ctrl](../..) daemon.\n\nSpawns the Rust `agent-ctrl daemon` as a subprocess and talks JSON-RPC to it\nover stdio. Provides a typed API over the wire protocol so you can write\nagent code in TypeScript while the OS automation runs in native Rust.\n\n## Install (workspace)\n\n```bash\nnpm install\nnpm run build --workspace=@agent-ctrl/client\n```\n\n## Usage\n\n```typescript\nimport { AgentCtrl } from \"@agent-ctrl/client\";\n\nconst ctrl = new AgentCtrl();\ntry {\n  const session = await ctrl.openSession(\"mock\");\n  const snap = await ctrl.snapshot(session);\n  console.log(`captured ${Object.keys(snap.refs.entries).length} refs`);\n\n  // Click the first button\n  const [firstRef] = Object.keys(snap.refs.entries);\n  if (firstRef) {\n    await ctrl.act(session, { kind: \"click\", ref_id: firstRef });\n    await ctrl.waitFor(session, {\n      predicate: { kind: \"stable\", idle_ms: 250 },\n      timeout_ms: 5_000,\n      poll_ms: 250,\n    });\n  }\n\n  const name = firstRef ? await ctrl.get(session, \"name\", firstRef) : null;\n  console.log(name?.value);\n\n  await ctrl.closeSession(session);\n} finally {\n  await ctrl.close();\n}\n```\n\n## Configuration\n\n```typescript\nnew AgentCtrl({\n  // Full spawn command. Defaults to [\"agent-ctrl\", \"daemon\"].\n  command: [\"cargo\", \"run\", \"-q\", \"-p\", \"agent-ctrl-cli\", \"--\", \"daemon\"],\n  // What to do with daemon stderr: \"inherit\" (default) or \"ignore\".\n  stderr: \"ignore\",\n  // Working directory for the daemon process.\n  cwd: process.cwd(),\n  // Default per-request deadline. waitFor extends this to its daemon timeout.\n  requestTimeoutMs: 30_000,\n});\n```\n\n## Status\n\n`v0.1` - paired with the daemon's mock surface for protocol validation and\nboth the Windows UIA surface and the macOS Accessibility (AX) surface for\nreal native-app automation. Linux AT-SPI supports snapshots, queries,\ninspection, and window listing; actions are not implemented yet. Android and\niOS are not implemented yet.\nThe client itself is platform-agnostic - it spawns whatever `agent-ctrl`\nbinary is on PATH and talks to it over stdio JSON-RPC.\n\n## Real UIA Tests (Windows)\n\nThe default test suite uses the mock surface. The opt-in Windows UIA test uses\nthe deterministic `agent-ctrl-uia-fixture`, not a built-in Windows app:\n\n```powershell\ncargo build -p agent-ctrl-cli -p agent-ctrl-uia-fixture\n$env:RUN_UIA_TESTS = \"1\"\nnpm run test --workspace=@agent-ctrl/client\n```\n\n## Real AX Tests (macOS)\n\nThe macOS counterpart uses `agent-ctrl-ax-fixture` (a Cocoa app) and\nruns through the Rust integration test rather than the npm suite,\nbecause it needs Accessibility + Screen Recording grants on the\n`agent-ctrl` binary running it:\n\n```bash\ncargo build -p agent-ctrl-cli -p agent-ctrl-ax-fixture\nRUN_AX_TESTS=1 cargo test -p agent-ctrl-cli --test macos_ax_fixture\n```\n\nThe TypeScript surface itself is identical on Windows and macOS - same\nmethods, same JSON shapes. See [`docs/macos-ax-reliability.md`](../../docs/macos-ax-reliability.md)\nfor production notes specific to macOS (TCC permissions, sheets, IME).\n\n## API Notes\n\nThe client uses stdio daemon transport, so TCP session auth tokens are not\nneeded. The shell CLI uses TCP session files and sends the per-session token\nautomatically.\n\nMain methods: `openSession`, `openSessionInfo`, `snapshot`, `act`, `find`, `get`, `is`,\n`waitFor`, `listWindows`, `batch`, `closeSession`, and `close`.\n\n`openSessionInfo` returns the negotiated protocol version, surface, and\ncapabilities. Both open methods reject a daemon with an incompatible protocol\nversion. Every request has a bounded client-side deadline, and `close` remains\nbounded even when a child fails during spawn or ignores graceful shutdown.\n\nAction types are shared across surfaces and include check-state actions,\nclipboard operations, raw mouse events, screenshot targets, drag, scroll,\nselect, switch-app, and highlight requests. See\n[`src/types.ts`](src/types.ts) for the exact wire shapes.\n\nSnapshot `ref_id` values have two namespaces. `ref_N` identifies an actionable\nelement and may be passed to `act`. `scope_N` identifies a structural container\nand may be passed to `find` as `within_ref`, or to `get` and `is`; the daemon\nrejects actions that target it. Explicit structural role queries return scope\nrefs, while an unfiltered `find` returns actionable refs only.\n\nThe TypeScript wire types in [`src/types.ts`](src/types.ts) are hand-maintained.\nRust contract tests verify protocol version plus every surface and action label\nso closed-union drift fails CI.\n","readmeFilename":"README.md","_rev":"1-a6e20227576f4ba7faaee74bbcdf0df0"}