nsaspy/zara

Fork 0

EPIC — Samsung Galaxy system-assistant, native application integrations, and SmartThings #194

New issue

Open

opened 2026-08-24 06:22:11 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-24 06:22:11 +00:00

(Migrated from github.com)

Parent: #152
Integrates with: #150, #151, #159, #132, #133, #134, #170-#179

Goal

Turn the native Android Zara client into a practical Samsung Galaxy system-assistant / Bixby replacement with a modern native chat UI, system-level assistant integration, Prolog-controlled commands and device providers, Samsung/Android application interoperability, and server-side SmartThings support.

This epic extends #152. It does not create a second Android runtime, protocol, semantic vocabulary, LLM stack or memory system.

The final output is a built Android APK proven on real Samsung hardware.

Required end state

The Android Zara application provides two surfaces over the same runtime/configuration:

a modern full-screen Zara chat/task/calendar application;
an Android system-assistant/background voice surface.

Both use:

the same authenticated Zara identity;
the same ZARA/1 connection;
the same portable Prolog semantic/configuration model;
the same typed capability registry;
the same conversations and principal;
the same programmable-command definitions.

System assistant

Zara must correctly implement the public Android assistant contracts and be eligible for the user-selected Assistant role.

Required:

RoleManager.ROLE_ASSISTANT;
VoiceInteractionService;
VoiceInteractionSessionService;
lightweight always-running assistant process;
appropriate manifest/service metadata;
user-driven default-assistant onboarding;
Samsung Digital-assistant setup guidance;
Side-button digital-assistant integration where supported;
assistant invocation while ordinary Zara UI is closed;
explicit degraded state when Zara does not hold the role.

Zara must never claim to silently change the user's default assistant.

Modern Android UI

Use a native Kotlin/Jetpack Compose/Material 3 architecture selected and version-pinned by research.

Required first-class surfaces:

Chat;
Voice;
Tasks;
Calendar;
SmartThings/devices;
Integrations;
Settings;
assistant-role status;
server connection/reconnect;
diagnostics.

UI must render real typed runtime states rather than inventing a parallel state machine.

Shared Prolog configuration

The assistant service and chat UI must share one versioned Prolog semantic/configuration authority.

The Prolog model controls:

verbs;
aliases;
intents;
slots;
app aliases;
provider preferences;
capability selection;
local/server placement;
command composition;
confirmation policy;
YouTube provider preference;
calendar provider preference;
named Termux actions;
user-authored commands.

New verbs, aliases and compositions of existing capability primitives must be loadable without rebuilding the APK.

Adding a genuinely new Android primitive may require a Kotlin adapter once; subsequent semantic mappings remain Prolog-controlled.

No arbitrary remote shell, Java reflection, dynamic class invocation, raw Intent deserialization or unrestricted Prolog goal execution.

Android application integration

Add a typed open_app capability.

Support launching applications by human-readable/Prolog-configured aliases while respecting modern package-visibility restrictions.

Handle:

installed;
unavailable;
ambiguous;
permission/visibility-limited;
launch failure.

Do not make package IDs part of the portable semantic intent.

Browser/web integration

Support:

open_uri;
open_browser;
server-side web_search;
open selected result on initiating device.

Use the default Android browser unless a Prolog provider preference overrides it.

YouTube integration

Support:

stock YouTube;
configurable Vanced/ReVanced package variants;
URI opening;
video URLs;
searches;
provider preference and fallback.

Do not hardcode one ReVanced package identifier as permanent truth.

Example resolution:

configured ReVanced -> stock YouTube -> browser

ChatGPT app integration

Support opening the official ChatGPT Android application.

Provide an optional ask_chatgpt(Text) device capability only through Android mechanisms actually accepted by the installed ChatGPT version.

Feature-detect standard handoff/share support.

If prompt handoff is unsupported, launch the app and return a typed unsupported-handoff result.

Do not automate/scrape ChatGPT through AccessibilityService as a hidden workaround.

Zara's own server model providers remain the programmatic way to obtain an LLM answer.

Timer/alarm integration

Use Android's public AlarmClock intent contracts.

Required:

set timer;
optional timer label;
show timers where supported;
set alarm;
show alarms where supported.

Prefer standard intents so Samsung Clock or another compatible user-selected app can handle the request.

No undocumented Samsung Clock API dependency.

Calendar

Implement both:

Device calendar

Integrate through supported Android Calendar APIs/intents.

Capabilities:

query events;
create;
edit;
delete;
show/open.

Must interoperate with normal Android calendar providers, including Samsung Calendar where it uses the standard provider.

Zara calendar

Expose Zara's own principal-scoped server calendar for multi-client use.

The semantic layer chooses or clarifies:

device calendar;
Zara calendar;
configured default.

Tasks

Expose the existing Zara task/todo system through the Android client.

Required UI/actions:

create;
list;
complete;
update;
remove;
reminders;
upcoming;
overdue.

Do not make an Android-only second task database unless a researched offline cache/sync design requires one.

SmartThings

Implement SmartThings as a server-side Zara service provider.

Use current official production mechanisms:

API Access App;
OAuth 2.0;
scoped permissions;
REST API;
token refresh;
signed webhook verification;
subscriptions/event handling;
cleanup/revocation.

Secrets and refresh credentials remain server-side.

Android may host account-linking UX but does not become the SmartThings credential authority.

Capabilities should cover supported forms of:

location discovery;
device discovery;
device state;
commands;
scenes/routines;
event updates.

Device aliases and semantic commands may be represented in principal-scoped Prolog configuration.

Termux

Integrate through Termux's supported RUN_COMMAND interface and permission model.

Default security model is named local actions, not arbitrary server shell.

Example conceptual command:

termux_named_action(notes_sync)

The named action resolves through validated local Prolog configuration to a reviewed executable and argument schema.

Support command results where current Termux provides them.

Unknown/unapproved raw commands fail closed.

Voice

Reuse the #132/#175 architecture.

Android owns mic/playback/audio focus.

Server owns canonical voice processing.

Support:

system-assistant activation;
explicit voice activation;
partial/final transcript;
streaming response;
phrase/audio streaming;
barge-in;
immediate local stop;
server cancellation;
Bluetooth/headset route changes;
background/foreground lifecycle;
reconnect.

Wake-word behavior must follow the architecture research rather than assuming an unrestricted permanent microphone service.

Extensibility contract

Any new semantic function expressible from registered capability primitives must be definable in Prolog.

Example:

"work mode"
    -> open_app(termux)
    -> open_app(browser)
    -> device_action(...)

User-authored commands must compile into the same typed semantic/capability model from #151.

No second macro interpreter.

Security invariants

authenticated principal remains server authority;
client capability advertisement grants availability, not privilege;
device actions bind to an authenticated device/session;
SmartThings secrets stay server-side;
no arbitrary remote shell;
no arbitrary Android Intent;
no dynamic Java/Kotlin invocation;
no raw executable command plane;
no unvalidated URI;
bounded app/capability metadata;
package inventory remains private;
cancellation/replay/idempotency defined for side effects;
logs redact secrets, clipboard data and private audio/text according to policy.

Dependency order

Do not bypass the existing #152 foundation.

Suggested child slices:

Research / design gate — current Android assistant-role, Samsung, app visibility, timer/calendar, Termux, SmartThings and integration-policy research.
System-assistant role — ROLE_ASSISTANT, VoiceInteractionService/SessionService and Samsung onboarding.
Modern Compose application shell — chat/voice/task/calendar/integration navigation and shared state.
Shared Prolog Android configuration authority — app aliases, verbs, capability/provider policy and hot reload.
Generic app/browser/media adapters — open app, URI, browser, YouTube/Vanced/ReVanced, ChatGPT handoff.
Timer/alarm/calendar adapters — Android standard providers plus Zara calendar bridge.
Termux named-action adapter — permission, typed execution and result path.
SmartThings server provider — OAuth, devices, commands, events/webhooks and Prolog semantics.
Samsung assistant integration/voice lifecycle hardening — background invocation, reconnect, audio lifecycle.
Cross-component extensibility gate — add new verbs/commands in Prolog without APK rebuild.
Adversarial Android/Samsung integration gate — lifecycle, permissions, app absence, replay, malformed input, network loss.
Real Samsung release gate + exact APK — actual default-assistant/Side-button, voice, timer, apps, YouTube variants, calendars, tasks, Termux and SmartThings.

Child dependencies must also preserve the existing #150/#151/#152/#159/#132/#133 constraints.

TDD / RAGE

Every implementation child uses repository Auto-RAGE:

exact start SHA;
research;
architecture/design;
adversarial review;
autonomous decision gate;
failing test first;
RED evidence;
implementation;
GREEN;
meaningful edge/failure/security tests;
complete repository/Nix/Android gate;
exact-head GitHub Actions;
merge only exact-head green and mergeable;
append-only RAGE evidence.

No Prolog-RLM dependency.

Mandatory real Samsung acceptance

The final candidate must be installed on an actual Samsung Galaxy device.

Human verification must prove:

Zara can be selected as Digital assistant;
assistant can be invoked through the supported system path;
Side-button assistant integration works when configured;
assistant works with chat UI closed;
real voice conversation;
barge-in;
timer created through compatible Clock handler;
arbitrary configured app launch;
stock YouTube;
Vanced/ReVanced configured provider;
default browser;
ChatGPT launch/handoff behavior;
device calendar;
Zara calendar;
Zara tasks;
Termux named command and result;
SmartThings device command;
new Prolog-defined verb/command without rebuilding APK;
restart persistence;
offline/reconnect behavior;
revocation;
exact APK/head identity.

Automation must not claim PASS for hardware scenarios the human did not perform.

Completion rule

This epic is complete only when Zara is a built native Android app that can operate as the selected assistant on real Samsung hardware, maintain a modern chat/voice/task/calendar experience, securely connect to zara-server, use SmartThings server-side, control reviewed Android capabilities, integrate with Termux and media/apps, and extend its semantic behavior through Prolog without requiring APK changes for every new command.

Parent: #152 Integrates with: #150, #151, #159, #132, #133, #134, #170-#179 ## Goal Turn the native Android Zara client into a practical Samsung Galaxy system-assistant / Bixby replacement with a modern native chat UI, system-level assistant integration, Prolog-controlled commands and device providers, Samsung/Android application interoperability, and server-side SmartThings support. This epic extends #152. It does not create a second Android runtime, protocol, semantic vocabulary, LLM stack or memory system. The final output is a built Android APK proven on real Samsung hardware. ## Required end state The Android Zara application provides two surfaces over the same runtime/configuration: 1. a modern full-screen Zara chat/task/calendar application; 2. an Android system-assistant/background voice surface. Both use: - the same authenticated Zara identity; - the same `ZARA/1` connection; - the same portable Prolog semantic/configuration model; - the same typed capability registry; - the same conversations and principal; - the same programmable-command definitions. ## System assistant Zara must correctly implement the public Android assistant contracts and be eligible for the user-selected Assistant role. Required: - `RoleManager.ROLE_ASSISTANT`; - `VoiceInteractionService`; - `VoiceInteractionSessionService`; - lightweight always-running assistant process; - appropriate manifest/service metadata; - user-driven default-assistant onboarding; - Samsung Digital-assistant setup guidance; - Side-button digital-assistant integration where supported; - assistant invocation while ordinary Zara UI is closed; - explicit degraded state when Zara does not hold the role. Zara must never claim to silently change the user's default assistant. ## Modern Android UI Use a native Kotlin/Jetpack Compose/Material 3 architecture selected and version-pinned by research. Required first-class surfaces: - Chat; - Voice; - Tasks; - Calendar; - SmartThings/devices; - Integrations; - Settings; - assistant-role status; - server connection/reconnect; - diagnostics. UI must render real typed runtime states rather than inventing a parallel state machine. ## Shared Prolog configuration The assistant service and chat UI must share one versioned Prolog semantic/configuration authority. The Prolog model controls: - verbs; - aliases; - intents; - slots; - app aliases; - provider preferences; - capability selection; - local/server placement; - command composition; - confirmation policy; - YouTube provider preference; - calendar provider preference; - named Termux actions; - user-authored commands. New verbs, aliases and compositions of existing capability primitives must be loadable without rebuilding the APK. Adding a genuinely new Android primitive may require a Kotlin adapter once; subsequent semantic mappings remain Prolog-controlled. No arbitrary remote shell, Java reflection, dynamic class invocation, raw Intent deserialization or unrestricted Prolog goal execution. ## Android application integration Add a typed `open_app` capability. Support launching applications by human-readable/Prolog-configured aliases while respecting modern package-visibility restrictions. Handle: - installed; - unavailable; - ambiguous; - permission/visibility-limited; - launch failure. Do not make package IDs part of the portable semantic intent. ## Browser/web integration Support: - `open_uri`; - `open_browser`; - server-side `web_search`; - open selected result on initiating device. Use the default Android browser unless a Prolog provider preference overrides it. ## YouTube integration Support: - stock YouTube; - configurable Vanced/ReVanced package variants; - URI opening; - video URLs; - searches; - provider preference and fallback. Do not hardcode one ReVanced package identifier as permanent truth. Example resolution: ```text configured ReVanced -> stock YouTube -> browser ``` ## ChatGPT app integration Support opening the official ChatGPT Android application. Provide an optional `ask_chatgpt(Text)` device capability only through Android mechanisms actually accepted by the installed ChatGPT version. Feature-detect standard handoff/share support. If prompt handoff is unsupported, launch the app and return a typed unsupported-handoff result. Do not automate/scrape ChatGPT through AccessibilityService as a hidden workaround. Zara's own server model providers remain the programmatic way to obtain an LLM answer. ## Timer/alarm integration Use Android's public AlarmClock intent contracts. Required: - set timer; - optional timer label; - show timers where supported; - set alarm; - show alarms where supported. Prefer standard intents so Samsung Clock or another compatible user-selected app can handle the request. No undocumented Samsung Clock API dependency. ## Calendar Implement both: ### Device calendar Integrate through supported Android Calendar APIs/intents. Capabilities: - query events; - create; - edit; - delete; - show/open. Must interoperate with normal Android calendar providers, including Samsung Calendar where it uses the standard provider. ### Zara calendar Expose Zara's own principal-scoped server calendar for multi-client use. The semantic layer chooses or clarifies: - device calendar; - Zara calendar; - configured default. ## Tasks Expose the existing Zara task/todo system through the Android client. Required UI/actions: - create; - list; - complete; - update; - remove; - reminders; - upcoming; - overdue. Do not make an Android-only second task database unless a researched offline cache/sync design requires one. ## SmartThings Implement SmartThings as a server-side Zara service provider. Use current official production mechanisms: - API Access App; - OAuth 2.0; - scoped permissions; - REST API; - token refresh; - signed webhook verification; - subscriptions/event handling; - cleanup/revocation. Secrets and refresh credentials remain server-side. Android may host account-linking UX but does not become the SmartThings credential authority. Capabilities should cover supported forms of: - location discovery; - device discovery; - device state; - commands; - scenes/routines; - event updates. Device aliases and semantic commands may be represented in principal-scoped Prolog configuration. ## Termux Integrate through Termux's supported `RUN_COMMAND` interface and permission model. Default security model is named local actions, not arbitrary server shell. Example conceptual command: ```text termux_named_action(notes_sync) ``` The named action resolves through validated local Prolog configuration to a reviewed executable and argument schema. Support command results where current Termux provides them. Unknown/unapproved raw commands fail closed. ## Voice Reuse the #132/#175 architecture. Android owns mic/playback/audio focus. Server owns canonical voice processing. Support: - system-assistant activation; - explicit voice activation; - partial/final transcript; - streaming response; - phrase/audio streaming; - barge-in; - immediate local stop; - server cancellation; - Bluetooth/headset route changes; - background/foreground lifecycle; - reconnect. Wake-word behavior must follow the architecture research rather than assuming an unrestricted permanent microphone service. ## Extensibility contract Any new semantic function expressible from registered capability primitives must be definable in Prolog. Example: ```text "work mode" -> open_app(termux) -> open_app(browser) -> device_action(...) ``` User-authored commands must compile into the same typed semantic/capability model from #151. No second macro interpreter. ## Security invariants - authenticated principal remains server authority; - client capability advertisement grants availability, not privilege; - device actions bind to an authenticated device/session; - SmartThings secrets stay server-side; - no arbitrary remote shell; - no arbitrary Android Intent; - no dynamic Java/Kotlin invocation; - no raw executable command plane; - no unvalidated URI; - bounded app/capability metadata; - package inventory remains private; - cancellation/replay/idempotency defined for side effects; - logs redact secrets, clipboard data and private audio/text according to policy. ## Dependency order Do not bypass the existing #152 foundation. Suggested child slices: 1. Research / design gate — current Android assistant-role, Samsung, app visibility, timer/calendar, Termux, SmartThings and integration-policy research. 2. System-assistant role — `ROLE_ASSISTANT`, VoiceInteractionService/SessionService and Samsung onboarding. 3. Modern Compose application shell — chat/voice/task/calendar/integration navigation and shared state. 4. Shared Prolog Android configuration authority — app aliases, verbs, capability/provider policy and hot reload. 5. Generic app/browser/media adapters — open app, URI, browser, YouTube/Vanced/ReVanced, ChatGPT handoff. 6. Timer/alarm/calendar adapters — Android standard providers plus Zara calendar bridge. 7. Termux named-action adapter — permission, typed execution and result path. 8. SmartThings server provider — OAuth, devices, commands, events/webhooks and Prolog semantics. 9. Samsung assistant integration/voice lifecycle hardening — background invocation, reconnect, audio lifecycle. 10. Cross-component extensibility gate — add new verbs/commands in Prolog without APK rebuild. 11. Adversarial Android/Samsung integration gate — lifecycle, permissions, app absence, replay, malformed input, network loss. 12. Real Samsung release gate + exact APK — actual default-assistant/Side-button, voice, timer, apps, YouTube variants, calendars, tasks, Termux and SmartThings. Child dependencies must also preserve the existing #150/#151/#152/#159/#132/#133 constraints. ## TDD / RAGE Every implementation child uses repository Auto-RAGE: - exact start SHA; - research; - architecture/design; - adversarial review; - autonomous decision gate; - failing test first; - RED evidence; - implementation; - GREEN; - meaningful edge/failure/security tests; - complete repository/Nix/Android gate; - exact-head GitHub Actions; - merge only exact-head green and mergeable; - append-only RAGE evidence. No Prolog-RLM dependency. ## Mandatory real Samsung acceptance The final candidate must be installed on an actual Samsung Galaxy device. Human verification must prove: - Zara can be selected as Digital assistant; - assistant can be invoked through the supported system path; - Side-button assistant integration works when configured; - assistant works with chat UI closed; - real voice conversation; - barge-in; - timer created through compatible Clock handler; - arbitrary configured app launch; - stock YouTube; - Vanced/ReVanced configured provider; - default browser; - ChatGPT launch/handoff behavior; - device calendar; - Zara calendar; - Zara tasks; - Termux named command and result; - SmartThings device command; - new Prolog-defined verb/command without rebuilding APK; - restart persistence; - offline/reconnect behavior; - revocation; - exact APK/head identity. Automation must not claim PASS for hardware scenarios the human did not perform. ## Completion rule This epic is complete only when Zara is a built native Android app that can operate as the selected assistant on real Samsung hardware, maintain a modern chat/voice/task/calendar experience, securely connect to `zara-server`, use SmartThings server-side, control reviewed Android capabilities, integrate with Termux and media/apps, and extend its semantic behavior through Prolog without requiring APK changes for every new command.

lost-rob0t commented

2026-08-24 06:25:42 +00:00

(Migrated from github.com)

Created the dependency-ordered implementation queue:

#195 — research/design gate
#196 — Android Assistant role and voice-interaction services
#197 — modern Compose application shell
#198 — shared hot-reloadable Prolog authority
#199 — app/browser/YouTube/ChatGPT adapters
#200 — timer/alarm/device+Zara calendar adapters
#201 — Termux named-action adapter
#202 — server-side SmartThings provider
#203 — Samsung background voice/audio/reconnect hardening
#204 — no-APK-rebuild Prolog extensibility gate
#205 — adversarial Android/Samsung integration gate
#206 — real Samsung acceptance and exact downloadable GitHub Release APK

The final gate requires a non-expiring GitHub Release APK asset, SHA-256/build/signing/source identity, exact-head green CI, and honest human hardware evidence.

Created the dependency-ordered implementation queue: - [ ] #195 — research/design gate - [ ] #196 — Android Assistant role and voice-interaction services - [ ] #197 — modern Compose application shell - [ ] #198 — shared hot-reloadable Prolog authority - [ ] #199 — app/browser/YouTube/ChatGPT adapters - [ ] #200 — timer/alarm/device+Zara calendar adapters - [ ] #201 — Termux named-action adapter - [ ] #202 — server-side SmartThings provider - [ ] #203 — Samsung background voice/audio/reconnect hardening - [ ] #204 — no-APK-rebuild Prolog extensibility gate - [ ] #205 — adversarial Android/Samsung integration gate - [ ] #206 — real Samsung acceptance and exact downloadable GitHub Release APK The final gate requires a non-expiring GitHub Release APK asset, SHA-256/build/signing/source identity, exact-head green CI, and honest human hardware evidence.