# termux/ README

Last updated: 2026-02-28

This folder contains the Termux bootstrap/update scripts, EUC upload flow, legacy timer tooling, and the new agent control plane.

## Current folder structure

```text
termux/
├── README.md
├── pullpullscripts.sh
├── pullscripts.sh
├── euc_upload.sh
├── timer.sh
├── timer.py
├── timerr.py
├── timer_copy.py
├── timer.php
├── timer.json
├── error_log
└── agent/
    ├── agent.sh
    ├── agent_api.php
    ├── agent_admin.php
    ├── agent_admin_api.php
    ├── agent_start.sh
    ├── agent_stop.sh
    ├── agent_status.sh
    ├── agent_restart.sh
    ├── agent_admin.sh
    └── agent_data/
        ├── token.txt
        └── .htaccess
```

## How the phone bootstrap works

### 1) `pullpullscripts.sh`
- Purpose: recovery/bootstrap updater
- Action: fetches latest `pullscripts.sh` from `getfrom.net` into `~/.shortcuts/`

### 2) `pullscripts.sh`
- Purpose: rebuild widget launchers and agent script layout
- Action:
  - Rebuilds root launchers in `~/.shortcuts/`
  - Rebuilds agent launchers/scripts under `~/.shortcuts/agents/`
  - Creates root proxy launchers so widgets can still run agent actions easily

## Runtime layout on phone

- Widget picker root: `~/.shortcuts/`
- Agent script area: `~/.shortcuts/agents/`
- Agent runtime state/logs: `~/.termux-agent/`
  - token file (`token`)
  - PID/log files created by agent scripts

## Agent subsystem (`termux/agent/`)

## Remote command flow (how assistant-triggered execution works)

This is the end-to-end path used when the assistant executes a phone action through the web agent:

1. Assistant/server enqueues a command via `agent_admin_api.php?action=enqueue_admin` (or `agent_api.php?action=enqueue`) with:
   - `kind` (typically `shell` for raw command execution)
   - `command` (e.g. `termux-sms-send -n 17733675072 "good morning, lubbie"`)
   - `target` (specific device like `SM-A566U1-2307`, or `any`)
2. Command is appended to `termux/agent/agent_data/commands.json` with `status=queued`.
3. Phone-side `agent.sh` polls `agent_api.php?action=pull` every ~10s.
4. Server marks command `sent` and returns it to the polling device.
5. Phone executes command by `kind` dispatch (`shell` => `timeout 120 bash -lc "<command>"`).
6. Phone posts ack to `agent_api.php?action=ack` with exit code + truncated output.
7. Server writes final state (`done`/`failed`) and logs event history.

Quick verification path:
- `agent_admin_api.php?action=status&password=...` shows devices, recent commands, and recent events.
- Successful command should show `status: done`, `ack_device`, and `exit_code: 0`.

## Agent command dispatch (Step 5, explicit)

When a command is pulled, `agent.sh` dispatches by `kind`:

- `pull_scripts` → runs `bash ~/.shortcuts/pullscripts.sh`
- `upload_euc` → runs `bash ~/.shortcuts/euc_upload.sh`
- `sms_sync` → runs `termux-sms-list` and uploads a one-way snapshot to server storage
- `sms_digest` → returns recent inbox snapshot in command ack output
- `sms_permissions` → checks READ_SMS + READ_PHONE_STATE support and returns diagnostics
- `termux-camera-info` → runs `termux-camera-info` (optional extra args allowed via `command`)
- `termux-job-scheduler` → runs `termux-job-scheduler` (optional extra args allowed via `command`)
- `termux-media-player` → runs `termux-media-player` (optional extra args allowed via `command`)
- `termux-microphone-record` → runs `termux-microphone-record` (optional extra args allowed via `command`)
- `termux-notification` → runs `termux-notification` (optional extra args allowed via `command`)
- `termux-notification-channel` → runs `termux-notification-channel` (optional extra args allowed via `command`)
- `termux-notification-list` → runs `termux-notification-list` (optional extra args allowed via `command`)
- `termux-notification-remove` → runs `termux-notification-remove` (optional extra args allowed via `command`)
- `termux-speech-to-text` → runs `termux-speech-to-text` (optional extra args allowed via `command`)
- `termux-tts-engines` → runs `termux-tts-engines` (optional extra args allowed via `command`)
- `termux-tts-speak` → runs `termux-tts-speak` (optional extra args allowed via `command`)
- `shell` → runs `timeout 120 bash -lc "<command>"`
- `sync_downloads` → currently placeholder/stub (not implemented yet)

Notes:
- Poll interval is 10 seconds by default (`POLL_SECONDS=10`).
- One command is executed at a time, then acked with exit code + output.

### Phone-side scripts
- `agent.sh` — polling worker (pull command, execute, ack)
- `agent_start.sh` — downloads latest `agent.sh` and starts it in background
- `agent_stop.sh` — stops running agent via PID
- `agent_status.sh` — shows running status + recent logs
- `agent_restart.sh` — stop then start (refresh after updates)
- `agent_admin.sh` — opens admin webpage in browser with stored password

### Server-side endpoints/pages
- `agent_api.php` — queue API (`register`, `heartbeat`, `pull`, `ack`, `enqueue`, `list`)
- `agent_admin.php` — password-protected admin UI
- `agent_admin_api.php` — admin status/scripts/preview/enqueue API

- `sms_catchup.php` — one-way HTML dashboard to review conversation follow-up needs (no sending from panel)
- `agent_data/` — command/device/event store + token
  - `.htaccess` denies direct web access

## Admin URL

- `https://getfrom.net/termux/agent/agent_admin.php?password=cksecreteditor`

## URL/path note (important)

Right now, use explicit `index.php` in links where needed.

- Overview page: `https://getfrom.net/termux/index.php`
- Agent admin: `https://getfrom.net/termux/agent/agent_admin.php?password=cksecreteditor`

If directory index handling changes later, `/termux/` may work without the filename, but `index.php` is the safe canonical path for now.

## Other termux tools

- `euc_upload.sh` — uploads EUC CSV data from phone storage (chunked flow + merge call)
- `timer.sh`, `timer.py`, `timerr.py`, `timer_copy.py`, `timer.php`, `timer.json` — legacy/alternate timer scheduler stack still present for compatibility/history

## Notes for future changes

- Keep `~/.shortcuts/` as the widget-visible root (no nested widget folder assumption).
- Keep agent internals under `termux/agent/` in repo and `~/.shortcuts/agents/` on phone.
- If adding new agent scripts, update `pullscripts.sh` so they are distributed automatically.


## Conversation review page

- SMS catch-up dashboard: `https://getfrom.net/termux/agent/sms_catchup.php?password=cksecreteditor`
- This is read-only/one-way for now (review + prioritization only; no sending).


## Termux version note (SMS CLI)

Some Termux builds do not support `--type` for `termux-sms-list`.
This agent uses `--message-limit` (with `-l` fallback) for compatibility.


## F-Droid migration + current setup notes (2026-02-28)

We migrated off Play Store Termux due to missing Termux:API SMS support.

### Why migration was required
- Play Store Termux returned: `Termux:API is not yet available on Google Play ...`
- Result: `termux-sms-list` could not access SMS data via API bridge.

### Installed stack (working)
- Termux (F-Droid/GitHub build)
- Termux:API (matching F-Droid/GitHub build)
- Termux:Widget (optional, for shortcut launchers)

### Bootstrap commands used
```bash
pkg update -y
pkg upgrade -y
pkg install -y termux-api python curl coreutils
termux-setup-storage
```

Then script bootstrap:
```bash
mkdir -p ~/.shortcuts
curl -fsSL https://getfrom.net/termux/pullpullscripts.sh -o ~/.shortcuts/pullpullscripts.sh
chmod +x ~/.shortcuts/pullpullscripts.sh
bash ~/.shortcuts/pullpullscripts.sh
bash ~/.shortcuts/pullscripts.sh
```

Agent token/start:
```bash
mkdir -p ~/.termux-agent
echo '33165ce7d6361011209397a9d616cff3284093ba' > ~/.termux-agent/token
chmod 600 ~/.termux-agent/token
bash ~/.shortcuts/agents/agent_start.sh
bash ~/.shortcuts/agents/agent_status.sh
```

### Verified working
- Agent polling from new device id (SM-A566U1-2307)
- `sms_sync` succeeded with ingest count `268`
- SMS catch-up dashboard populated from one-way sync data

### Remaining permission issue (sending SMS)
SMS send attempts still return:
- `android.permission.READ_PHONE_STATE`
- `android.permission.SEND_SMS`

So reading SMS now works, but sending SMS from remote commands remains blocked until Android grants those permissions.


Admin UI now includes a **Check SMS permissions** button that enqueues `sms_permissions` and shows permission diagnostics in command output.