@ai-agent-forge/plugin-desktop-macos-observe 0.88.3

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAqHA;;;GAGG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9D,KAAK;IACL,UAAU;IACV,OAAO;IACP,SAAS;IACT,iBAAiB;CACiC,CAAC,CAAC;AAErD,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,IAAyB,EAAW,EAAE,CACpF,iCAAoE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAoDtF,mFAAmF;AACnF,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,OAA+B,EAAsB,EAAE,CAAC;IACxG,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QAC5C,IAAI,SAAS,CAAC,SAAS,KAAK,OAAO,CAAC,SAAS;YAAE,OAAO,SAAS,CAAC,WAAW,CAAC;IAC7E,CAAC;IACD,OAAO,SAAS,CAAC;AAAA,CACjB,CAAC","sourcesContent":["import type { PluginResultStatusV1 } from \"@agent-forge/plugin-sdk\";\n\n/**\n * macOS counterpart of the desktop plugin family contract, derived from the\n * Windows package copies (`plugins/desktop-windows-observe/src/types.ts`,\n * itself inlined from agent-forge `src/plugins/desktop/types.ts`, D-075 S3)\n * so this package keeps its dependency closure limited to the plugin SDK and\n * typebox. This file is a deliberate copy shared (not imported) with\n * `plugins/desktop-macos-input/src/types.ts`; keep both copies in sync.\n * Differences from the Windows copies:\n * - The observation `source` union carries `\"macos-ax\"` instead of\n *   `\"windows-uia\"`; `\"mock\"` stays the test-fixture source.\n * - Probe/driver types are `DesktopMacosProbeV1` / `DesktopMacosDriverV1`\n *   with `driver: \"macos-ax\"`, plus a read-only driver subset\n *   (`DesktopMacosReadonlyDriverV1`) so the observe package never carries an\n *   execute surface.\n * - `DesktopTargetRefV1` gains the `coordinates` variant used by the input\n *   package's coordinate click (x/y integer non-negative screen coordinates,\n *   click-only by ruling); the observe package never consumes it.\n * - Replay request/result types stay because the capability factory keeps the\n *   Windows factory contract (optional replay registration when the runtime\n *   exposes a replay method); the shipped macOS facades expose no replay.\n */\n\n/** Stable capability ids owned by the desktop-control plugin family. */\nexport type DesktopCapabilityIdV1 =\n\t| \"desktop-session\"\n\t| \"desktop-uia\"\n\t| \"desktop-input\"\n\t| \"desktop-vision\"\n\t| \"desktop-replay\";\n\nexport type DesktopSessionIsolationV1 = \"mock\" | \"foreground\" | \"vm\";\nexport type DesktopSessionStatusV1 = \"ready\" | \"unavailable\" | \"stopped\";\n\nexport interface DesktopSessionRequestV1 {\n\treadonly version: 1;\n\treadonly isolation: DesktopSessionIsolationV1;\n\treadonly applicationId?: string;\n}\n\nexport interface DesktopSessionV1 {\n\treadonly version: 1;\n\treadonly sessionId: string;\n\treadonly isolation: DesktopSessionIsolationV1;\n\treadonly status: DesktopSessionStatusV1;\n\treadonly applicationId?: string;\n}\n\nexport interface DesktopErrorV1 {\n\treadonly version: 1;\n\treadonly code: string;\n\treadonly message: string;\n\treadonly causeCode?: string;\n}\n\nexport interface DesktopSessionResultV1 {\n\treadonly status: Extract<PluginResultStatusV1, \"succeeded\" | \"unsupported\" | \"failed\">;\n\treadonly session?: DesktopSessionV1;\n\treadonly error?: DesktopErrorV1;\n}\n\nexport interface DesktopWindowIdentityV1 {\n\treadonly version: 1;\n\treadonly windowId: string;\n\treadonly appId: string;\n\treadonly title: string;\n\treadonly bounds: DesktopBoundsV1;\n}\n\nexport interface DesktopControlIdentityV1 {\n\treadonly version: 1;\n\treadonly controlId: string;\n\treadonly windowId: string;\n\treadonly role: string;\n\treadonly name: string;\n\treadonly bounds: DesktopBoundsV1;\n\treadonly enabled: boolean;\n\treadonly value?: string;\n}\n\nexport interface DesktopBoundsV1 {\n\treadonly x: number;\n\treadonly y: number;\n\treadonly width: number;\n\treadonly height: number;\n}\n\nexport interface DesktopObservationV1 {\n\treadonly version: 1;\n\treadonly sessionId: string;\n\treadonly observationId: string;\n\treadonly source: \"mock\" | \"macos-ax\";\n\treadonly windows: readonly DesktopWindowIdentityV1[];\n\treadonly controls: readonly DesktopControlIdentityV1[];\n\treadonly focusedControlId?: string;\n}\n\nexport type DesktopTargetRefV1 =\n\t| { readonly kind: \"window\"; readonly windowId: string }\n\t| { readonly kind: \"control\"; readonly controlId: string; readonly windowId?: string }\n\t/** Screen-coordinate target; input-side click only (x/y integer, non-negative). */\n\t| { readonly kind: \"coordinates\"; readonly x: number; readonly y: number };\n\nexport type DesktopActionKindV1 =\n\t| \"focus\"\n\t| \"click\"\n\t| \"type\"\n\t| \"key\"\n\t| \"scroll\"\n\t| \"submit\"\n\t| \"uac\"\n\t| \"password\"\n\t| \"admin\"\n\t| \"payment\"\n\t| \"external-submit\";\n\n/**\n * Actions that must pause at the host/user boundary before any input is sent.\n * This policy belongs to the desktop plugin, not Agent Core.\n */\nexport const DESKTOP_USER_CONFIRMATION_ACTIONS = Object.freeze([\n\t\"uac\",\n\t\"password\",\n\t\"admin\",\n\t\"payment\",\n\t\"external-submit\",\n] as const satisfies readonly DesktopActionKindV1[]);\n\nexport const requiresDesktopUserConfirmation = (kind: DesktopActionKindV1): boolean =>\n\t(DESKTOP_USER_CONFIRMATION_ACTIONS as readonly DesktopActionKindV1[]).includes(kind);\n\nexport interface DesktopActionV1 {\n\treadonly version: 1;\n\treadonly kind: DesktopActionKindV1;\n\treadonly target?: DesktopTargetRefV1;\n\treadonly text?: string;\n\treadonly key?: string;\n}\n\nexport type DesktopPostconditionV1 =\n\t| { readonly kind: \"window-exists\"; readonly windowId: string }\n\t| { readonly kind: \"control-exists\"; readonly controlId: string }\n\t| { readonly kind: \"focused\"; readonly controlId: string }\n\t| {\n\t\t\treadonly kind: \"property-equals\";\n\t\t\treadonly target: DesktopTargetRefV1;\n\t\t\treadonly property: \"enabled\" | \"value\" | \"name\";\n\t\t\treadonly expected: boolean | string;\n\t  };\n\nexport interface DesktopOperationRequestV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly sessionId: string;\n\treadonly action: DesktopActionV1;\n\treadonly postconditions?: readonly DesktopPostconditionV1[];\n\treadonly reobserveAfterAction?: boolean;\n}\n\nexport interface DesktopVerificationV1 {\n\treadonly status: \"passed\" | \"failed\" | \"unknown\";\n\treadonly checks: readonly string[];\n}\n\nexport interface DesktopOperationResultV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly status: PluginResultStatusV1;\n\treadonly summary: string;\n\treadonly observation?: DesktopObservationV1;\n\treadonly verification?: DesktopVerificationV1;\n\treadonly error?: DesktopErrorV1;\n}\n\nexport interface DesktopReplayRequestV1 {\n\treadonly version: 1;\n\treadonly sessionId: string;\n\treadonly operations: readonly DesktopOperationRequestV1[];\n\treadonly stopOnFailure: boolean;\n}\n\n/** Returns the first operation id that would cross the replay session boundary. */\nexport const findDesktopReplaySessionMismatch = (request: DesktopReplayRequestV1): string | undefined => {\n\tfor (const operation of request.operations) {\n\t\tif (operation.sessionId !== request.sessionId) return operation.operationId;\n\t}\n\treturn undefined;\n};\n\nexport interface DesktopReplayResultV1 {\n\treadonly version: 1;\n\treadonly status: Extract<PluginResultStatusV1, \"succeeded\" | \"failed\" | \"cancelled\" | \"needs_user\">;\n\treadonly results: readonly DesktopOperationResultV1[];\n}\n\nexport interface DesktopAdapterV1 {\n\treadonly adapterId: string;\n\treadonly adapterVersion: string;\n\treadonly capabilities: readonly DesktopCapabilityIdV1[];\n\topenSession(request: DesktopSessionRequestV1): DesktopSessionResultV1;\n\tobserve(sessionId: string): DesktopObservationV1 | DesktopOperationResultV1;\n\treobserve(sessionId: string): DesktopObservationV1 | DesktopOperationResultV1;\n\texecute(request: DesktopOperationRequestV1): DesktopOperationResultV1;\n\tstop(sessionId: string): DesktopSessionV1 | DesktopOperationResultV1;\n\treplay(request: DesktopReplayRequestV1): DesktopReplayResultV1;\n}\n\n/** Result returned by the macOS Accessibility capability probe. */\nexport interface DesktopMacosProbeV1 {\n\treadonly available: boolean;\n\treadonly platform: string;\n\treadonly driver: \"macos-ax\";\n\t/** Capabilities that the host can expose without relying on a higher-risk facade. */\n\treadonly capabilities?: readonly DesktopCapabilityIdV1[];\n\treadonly reason?: string;\n}\n\n/**\n * Read-only macOS host boundary used by the observe package's driver.\n * Implementations may use the Accessibility tree through System Events, an OS\n * broker, or a test driver. The adapter never invents observations when this\n * boundary reports unavailable.\n */\nexport interface DesktopMacosReadonlyDriverV1 {\n\treadonly driverId: string;\n\treadonly driverVersion: string;\n\tprobe(): DesktopMacosProbeV1;\n\topenSession(request: DesktopSessionRequestV1): DesktopSessionResultV1;\n\tobserve(sessionId: string): DesktopObservationV1 | DesktopOperationResultV1;\n\tstop(sessionId: string): DesktopSessionV1 | DesktopOperationResultV1;\n}\n\n/** Full macOS host boundary used by the input package's driver. */\nexport interface DesktopMacosDriverV1 extends DesktopMacosReadonlyDriverV1 {\n\texecute(request: DesktopOperationRequestV1): DesktopOperationResultV1;\n}\n\n/**\n * Production-safe, read-only desktop boundary. It deliberately omits\n * execute/replay so a host cannot accidentally expose input through the\n * observe plugin. The full DesktopAdapter remains a separate test/high-risk\n * contract.\n */\nexport interface DesktopReadonlyAdapterV1 {\n\treadonly adapterId: string;\n\treadonly adapterVersion: string;\n\tprobe(): DesktopMacosProbeV1;\n\topenSession(request: DesktopSessionRequestV1): DesktopSessionResultV1;\n\tobserve(sessionId: string): DesktopObservationV1 | DesktopOperationResultV1;\n\treobserve(sessionId: string): DesktopObservationV1 | DesktopOperationResultV1;\n\tstop(sessionId: string): DesktopSessionV1 | DesktopOperationResultV1;\n}\n\n/**\n * Production host boundary for intentionally bounded desktop input. This is\n * separate from DesktopReadonlyAdapterV1 so observing a desktop never\n * accidentally grants input, and replay is optional: adapters that expose it\n * keep the session-mismatch gate and the needs-user confirmation per action.\n * The shipped macOS input facade deliberately exposes no replay method.\n */\nexport interface DesktopFullControlAdapterV1 extends DesktopReadonlyAdapterV1 {\n\texecute(request: DesktopOperationRequestV1): DesktopOperationResultV1;\n\treplay?(request: DesktopReplayRequestV1): DesktopReplayResultV1;\n}\n"]}

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@ai-agent-forge/plugin-desktop-macos-observe",
+	"version": "0.88.3",
+	"description": "Read-only macOS desktop observation capability plugin for Agent Forge (desktop_probe, desktop_session_open, desktop_observe, desktop_reobserve, desktop_session_stop)",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"MANUAL.md",
+		"agent-forge.json",
+		"plugin.json",
+		"README.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsgo -p tsconfig.build.json",
+		"test": "vitest --run",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"keywords": [
+		"agent-forge",
+		"plugin",
+		"desktop",
+		"macos",
+		"accessibility",
+		"observation"
+	],
+	"author": "Agent Forge contributors",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agent-forge/agent-forge.git",
+		"directory": "plugins/desktop-macos-observe"
+	},
+	"bugs": {
+		"url": "https://github.com/agent-forge/agent-forge/issues"
+	},
+	"homepage": "https://github.com/agent-forge/agent-forge#readme",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"dependencies": {
+		"typebox": "1.3.27",
+		"@ai-agent-forge/plugin-sdk": "^0.88.3"
+	},
+	"devDependencies": {
+		"shx": "0.4.0",
+		"vitest": "4.1.11"
+	}
+}

package/plugin.json

@@ -0,0 +1,25 @@
+{
+	"id": "agent-forge.plugin.desktop-macos-observe",
+	"version": "0.88.3",
+	"apiVersion": "1-draft",
+	"entry": "./dist/entry.js",
+	"hostVersion": ">=0.84.4",
+	"description": "macOS 桌面观察:AX 辅助功能树窗口/元素枚举与读取(bundle id 定位/元素坐标/值),配合 desktop-macos-input 做桌面自动化前定位",
+	"activation": "on-demand",
+	"manual": "./MANUAL.md",
+	"requiredCapabilities": [
+		"tools"
+	],
+	"provides": [
+		{
+			"id": "desktop-session",
+			"version": 1,
+			"kind": "contribution"
+		},
+		{
+			"id": "desktop-uia",
+			"version": 1,
+			"kind": "contribution"
+		}
+	]
+}