{"_id":"@aotui/mobile-ai-native","_rev":"4-9b46053a07d5d5a5d34240a322fa7fed","name":"@aotui/mobile-ai-native","dist-tags":{"latest":"0.1.0-alpha.3","alpha":"0.1.0-alpha.2"},"versions":{"0.1.0-alpha.0":{"name":"@aotui/mobile-ai-native","version":"0.1.0-alpha.0","keywords":["agent-native","ios","mobile","llm","tui","state-machine","preact"],"license":"Apache-2.0","_id":"@aotui/mobile-ai-native@0.1.0-alpha.0","maintainers":[{"name":"johnnyzhang.agentina","email":"waynezhang.luck@gmail.com"}],"dist":{"shasum":"171a71ecd17bf19e2985f2fcd7ea8316540634a7","tarball":"https://registry.npmjs.org/@aotui/mobile-ai-native/-/mobile-ai-native-0.1.0-alpha.0.tgz","fileCount":45,"integrity":"sha512-u17gNoP3gauFwZsK63rr31Wm2pkqsCoR4Sy6UBU0N7STioHHw67rUxhJHv8VETlsbrrO7nQY6ih4y1KnRLeJDw==","signatures":[{"sig":"MEUCIQC5+AufZQj+Q8rEnkv3ukZaBWaZXq4W5S/WTYZvfv8NDwIgFw/gf7mAkgFTjuJKPlFtU/gMX3GduAlQc2qLfX5WzcA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35318},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest","build":"pnpm run clean && tsc -p tsconfig.json","clean":"rm -rf dist","test:run":"vitest --run","prepublishOnly":"pnpm build"},"_npmUser":{"name":"johnnyzhang.agentina","email":"waynezhang.luck@gmail.com"},"_npmVersion":"10.9.2","description":"Alpha host-agnostic core for building Agent Native mobile apps with shared GUI/TUI state and snapshot-scoped tool execution.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"zod":"^4.3.6","preact":"^10.28.1","preact-render-to-string":"^6.6.6"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.4","happy-dom":"^20.5.3","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/mobile-ai-native_0.1.0-alpha.0_1774328237362_0.6623293320030563","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.1":{"name":"@aotui/mobile-ai-native","version":"0.1.0-alpha.1","keywords":["agent-native","ios","mobile","llm","tui","state-machine","preact"],"license":"Apache-2.0","_id":"@aotui/mobile-ai-native@0.1.0-alpha.1","maintainers":[{"name":"johnnyzhang.agentina","email":"waynezhang.luck@gmail.com"}],"dist":{"shasum":"4d0347ece346413a4a693cdf32d871f3720ae7da","tarball":"https://registry.npmjs.org/@aotui/mobile-ai-native/-/mobile-ai-native-0.1.0-alpha.1.tgz","fileCount":70,"integrity":"sha512-HvLrGepOESUf7JOg0TsVSuY29yYPEiZrUzq3e/ecNt/GIQmwI+hyMn3mIEkOa9Kkjp9+gLJQroTa27s1cCQiig==","signatures":[{"sig":"MEUCIQCHLIatMXrg19BebX+nRSHOjfyjLsjji7DNXVjE7TfnUgIgWccC4CFglZJTZMLzSpu9AfMnjuFAWaDIC/Qpglr+Ghk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":84824},"main":"dist/index.js","type":"module","_from":"file:/var/folders/hp/stypzkys30gdsjlhc9kfsqhr0000gn/T/tmp.QlcFgmM6Dn/aotui-mobile-ai-native-0.1.0-alpha.1.tgz","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest","build":"pnpm run clean && tsc -p tsconfig.json","clean":"rm -rf dist","test:run":"vitest --run"},"_npmUser":{"name":"johnnyzhang.agentina","email":"waynezhang.luck@gmail.com"},"_resolved":"/var/folders/hp/stypzkys30gdsjlhc9kfsqhr0000gn/T/tmp.QlcFgmM6Dn/aotui-mobile-ai-native-0.1.0-alpha.1.tgz","_integrity":"sha512-HvLrGepOESUf7JOg0TsVSuY29yYPEiZrUzq3e/ecNt/GIQmwI+hyMn3mIEkOa9Kkjp9+gLJQroTa27s1cCQiig==","_npmVersion":"10.9.2","description":"Alpha host-agnostic core for building Agent Native mobile apps with shared GUI/TUI state and snapshot-scoped tool execution.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"zod":"^4.3.6","preact":"^10.28.1","preact-render-to-string":"^6.6.6"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"vitest":"^3.2.4","happy-dom":"^20.5.3","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/mobile-ai-native_0.1.0-alpha.1_1774588596217_0.1652606135091923","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.2":{"name":"@aotui/mobile-ai-native","version":"0.1.0-alpha.2","keywords":["agent-native","ios","mobile","llm","tui","state-machine","preact"],"license":"Apache-2.0","_id":"@aotui/mobile-ai-native@0.1.0-alpha.2","maintainers":[{"name":"johnnyzhang.agentina","email":"waynezhang.luck@gmail.com"}],"dist":{"shasum":"d21ea32cd4a2fc713055275b1dff1b6bd63e6313","tarball":"https://registry.npmjs.org/@aotui/mobile-ai-native/-/mobile-ai-native-0.1.0-alpha.2.tgz","fileCount":70,"integrity":"sha512-TW+FglfzXYtj2rUNaLHFGxtaUMGjX/9NvpD/OmIcFatnSpMvvLV+qELhot3cmg+KxlvYfqx604xilHffks+n5w==","signatures":[{"sig":"MEYCIQC98irVWKNtLEdY4EdBPwcq1XqBOtWb3vAbutdXlnwBVgIhALVNVJdtb8jjTEqMqjYWAcPflCCocWvPpW2Y3IiILnOt","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":85227},"main":"dist/index.js","type":"module","_from":"file:/var/folders/hp/stypzkys30gdsjlhc9kfsqhr0000gn/T/tmp.KCyQt19Dto/aotui-mobile-ai-native-0.1.0-alpha.2.tgz","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest","build":"pnpm run clean && tsc -p tsconfig.json && node ../scripts/fix-relative-import-extensions.mjs ./dist","clean":"rm -rf dist","test:run":"vitest --run"},"_npmUser":{"name":"johnnyzhang.agentina","email":"waynezhang.luck@gmail.com"},"_resolved":"/var/folders/hp/stypzkys30gdsjlhc9kfsqhr0000gn/T/tmp.KCyQt19Dto/aotui-mobile-ai-native-0.1.0-alpha.2.tgz","_integrity":"sha512-TW+FglfzXYtj2rUNaLHFGxtaUMGjX/9NvpD/OmIcFatnSpMvvLV+qELhot3cmg+KxlvYfqx604xilHffks+n5w==","_npmVersion":"10.9.2","description":"Alpha host-agnostic core for building Agent Native mobile apps with shared GUI/TUI state and snapshot-scoped tool execution.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"zod":"^4.3.6","preact":"^10.28.1","preact-render-to-string":"^6.6.6"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"vitest":"^3.2.4","happy-dom":"^20.5.3","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/mobile-ai-native_0.1.0-alpha.2_1774924455578_0.33923252823740624","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.3":{"name":"@aotui/mobile-ai-native","version":"0.1.0-alpha.3","description":"Alpha host-agnostic core for building Agent Native mobile apps with shared GUI/TUI state and snapshot-scoped tool execution.","license":"Apache-2.0","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"dependencies":{"preact":"^10.28.1","preact-render-to-string":"^6.6.6","zod":"^4.3.6"},"devDependencies":{"happy-dom":"^20.5.3","typescript":"^5.9.3","vitest":"^3.2.4"},"keywords":["agent-native","ios","mobile","llm","tui","state-machine","preact"],"publishConfig":{"access":"public"},"scripts":{"clean":"rm -rf dist","build":"pnpm run clean && tsc -p tsconfig.json && node ../scripts/fix-relative-import-extensions.mjs ./dist","test":"vitest","test:run":"vitest --run"},"_id":"@aotui/mobile-ai-native@0.1.0-alpha.3","_integrity":"sha512-rht+tescPxYt414hfxmwfml4ZSQx5xBy6WUsO5w/UFKZDFktpUmgG9z01WKaagTbrdJZqOqIMCTrbV05SbP6zQ==","_resolved":"/private/var/folders/hp/stypzkys30gdsjlhc9kfsqhr0000gn/T/e6eb52d7f44e459078f9447f5bdd5b96/aotui-mobile-ai-native-0.1.0-alpha.3.tgz","_from":"file:aotui-mobile-ai-native-0.1.0-alpha.3.tgz","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-rht+tescPxYt414hfxmwfml4ZSQx5xBy6WUsO5w/UFKZDFktpUmgG9z01WKaagTbrdJZqOqIMCTrbV05SbP6zQ==","shasum":"5dce8a68d74344f1ba029704c94d1c93b79bd3a9","tarball":"https://registry.npmjs.org/@aotui/mobile-ai-native/-/mobile-ai-native-0.1.0-alpha.3.tgz","fileCount":73,"unpackedSize":83953,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFKeW0iUpwwtZb7hcyFnomrAQApTAKhuKkQYq66xMSaIAiEAs0GnzpJiItsNFxMTbnputVKH7QThz6u/NpnGYgAIfMo="}]},"_npmUser":{"name":"johnnyzhang.agentina","email":"waynezhang.luck@gmail.com"},"directories":{},"maintainers":[{"name":"johnnyzhang.agentina","email":"waynezhang.luck@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mobile-ai-native_0.1.0-alpha.3_1775795072957_0.17328743115048195"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-24T04:57:17.266Z","modified":"2026-04-10T04:24:33.287Z","0.1.0-alpha.0":"2026-03-24T04:57:17.502Z","0.1.0-alpha.1":"2026-03-27T05:16:36.349Z","0.1.0-alpha.2":"2026-03-31T02:34:15.716Z","0.1.0-alpha.3":"2026-04-10T04:24:33.156Z"},"license":"Apache-2.0","keywords":["agent-native","ios","mobile","llm","tui","state-machine","preact"],"description":"Alpha host-agnostic core for building Agent Native mobile apps with shared GUI/TUI state and snapshot-scoped tool execution.","maintainers":[{"name":"johnnyzhang.agentina","email":"waynezhang.luck@gmail.com"}],"readme":"# @aotui/mobile-ai-native\n\nThis package is the hardened runtime core for building agent-native mobile apps.\n\nIt is the **core**, not the full React Native host layer.\nReact Native / Expo mounting now lives in [`@aotui/mobile-ai-native-react-native`](../packages/mobile-ai-native-react-native/README.md).\n\nIt provides the state store, action runtime, trace lifecycle, snapshot registry, and tool bridge needed for a real mobile host.\n\nThe current snapshot model is view-based:\n\n`State -> static Root view + state-derived mounted views -> SnapshotBundle -> Tool Call(ref_id + snapshotId) -> Action -> Event/Effect -> State -> GUI/TUI refresh`\n\n## What This Slice Proves\n\n- one shared state system drives both GUI and TUI\n- the root view is static navigation knowledge, not runtime state\n- business views are mounted from current state and represent runtime reality\n- tools are exposed as a stable manifest, with runtime availability tracked separately\n- the framework builds one atomic `SnapshotBundle`\n- snapshot markup is composed from ordered `<View>` fragments\n- tools execute against the exact `snapshotId` the LLM saw\n- `refIndex` stores serializable snapshot payloads, not live object references\n- mutated tool results stale the originating snapshot, even when the result is recoverable\n- trace entries record the action lifecycle: `started`, `updated`, `succeeded`, and `failed`\n\n## SnapshotBundle\n\nThe LLM-facing read model is:\n\n```ts\ntype SnapshotBundle = {\n  snapshotId: string;\n  generatedAt: number;\n  markup: string;\n  views: readonly ViewFragment[];\n  tui: string;\n  refIndex: Record<string, RefIndexEntry>;\n  tools: readonly ToolDefinition[];\n  toolAvailability: Record<string, ToolAvailability>;\n};\n```\n\nCurrent behavior to keep in mind:\n\n- `markup` is the composed xml+markdown snapshot built from ordered `<View>` fragments\n- `views` preserves the ordered fragment list, with the `Root` fragment first\n- `tui` is retained as a compatibility readout and may differ from `markup`, but it should be produced from the same snapshot generation pass\n- `refIndex`, `tools`, and `toolAvailability` are produced and frozen alongside snapshot creation\n\nThe bundle is intended to be atomic:\n\n- `markup`\n- `views`\n- `tui`\n- `refIndex`\n- `tools`\n- `toolAvailability`\n\nToday the runtime hard-validates `markup` against `views`, then freezes the associated `tui`, `refIndex`, `tools`, and `toolAvailability` outputs generated on that same snapshot path.\n\n## RootView And Mounted Views\n\n`RootView` is the conceptual navigation role, and the current runtime emits it as a fragment with `type: \"Root\"`.\n\nIt explains:\n\n- what view types exist\n- how to enter them\n- what each view type is for\n\nIt does not try to narrate runtime state.\n\nMounted business views are the runtime reality.\n\nThey are derived from current state and describe:\n\n- which concrete views are mounted right now\n- what state each mounted view is showing\n- what refs and actions are relevant in that state\n\nThat means the LLM should read the static root first, then read the mounted business views for the live app state.\n\n## Tool Model\n\nTools are defined against a semantic `viewType`, exposure mode, and runtime availability.\n\nThat gives the runtime this rule:\n\n`tools = stable tools + currently exposed dynamic tools`\n\nThen `toolAvailability[name]` tells the model whether a listed tool can execute right now. A tool can remain in the manifest and still fail with `PRECONDITION_NOT_MET` when current state does not satisfy its runtime guard.\n\n## Core Contract\n\nThe LLM does not operate on guessed ids.\nIt sees semantic markers like:\n\n```text\n(Welcome back)[message:messages[0]]\n```\n\nThen it calls a tool with:\n\n```ts\nawait bridge.executeTool(\"openMessage\", { message: \"messages[0]\" }, snapshotId);\n```\n\nFor tools that declare `meta.supportsRefs === true`, the bridge resolves top-level string inputs as either exact `ref_id` values or canonical marker strings from that snapshot's `refIndex`.\nIt does not infer nested field refs or field-level ref metadata.\n\nThe low-level React-family host path inside the core is still present because the adapter composes it, but product code should prefer the dedicated RN adapter package.\n\nThe adapter-facing runtime path is:\n\n- `createReactAppRuntime()` owns the store, action runtime, snapshot registry, trace store, and tool bridge\n- `AppRuntimeProvider` publishes that runtime through context\n- `useRuntimeState(selector)` subscribes to store updates with `useSyncExternalStore`\n- `useRuntimeTrace(selector)` subscribes to the trace store the same way\n- `createReactNativeAppRuntime()` in the adapter package wraps that core runtime and exposes `runtime.ai.getSnapshot()` / `runtime.ai.executeTool(...)` for host-safe tool execution\n\nThat means GUI consumers react to state and trace changes without pulling the whole runtime object into component state.\n\n## Ref APIs\n\n### `useDataRef`\n\nUse for a single object:\n\n```tsx\nconst pinnedRef = useDataRef(\"message\", message, \"messages[0]\");\n<text>{pinnedRef(\"Pinned message\")}</text>;\n```\n\n### `useArrayRef`\n\nUse for an array:\n\n```tsx\nconst [listRef, itemRef] = useArrayRef(\"message\", messages, \"messages\");\n<text>{listRef(\"Inbox messages\")}</text>;\n<item>{itemRef(0, \"Welcome back\")}</item>;\n```\n\n## Current Status\n\nThis package is the core, not the full app shell.\n\nWhat it gives you today:\n\n- shared state core\n- semantic refs with `useDataRef` and `useArrayRef`\n- atomic `SnapshotBundle`\n- static root navigation plus state-derived mounted business views\n- snapshot-scoped tool execution\n- a pure core that can now be mounted by the dedicated RN / Expo adapter\n- structured trace and effect contracts\n\nWhat you still need for a production iOS app:\n\n- real GUI components\n- model orchestration and networking\n- product-level trace UI and persistence\n\n## Current Demo\n\nThe inbox demo exposes:\n\n- `openMessage`\n- `searchMessages`\n\nand proves that GUI and TUI both refresh from the same state after tool execution.\n\n## Runtime Boundaries\n\nKeep the framework and app responsibilities separated:\n\n- framework owns the store, action runtime, snapshot registry, trace runtime, tool bridge, and host adapter\n- business apps own state shape, domain actions, handwritten TUI, and app-specific effect behavior\n- actions can read state, emit events, run effects, and update trace summaries\n- effects can read state, emit events, and report structured success or failure, but they do not write state directly\n- snapshot coherence is enforced for the textual view representation, so `markup`, `views`, and `tui` must agree for the same render tick; `refIndex`, `tools`, and `toolAvailability` are built and frozen alongside that snapshot path but are not yet cross-validated field-by-field\n","readmeFilename":"README.md"}