TOKSO BOT

TOKSO BOT 0.2.0 provides a Windows device-fleet foundation and a framework-independent durable workflow engine. The engine can validate, persist, and resume safe local workflows; it does not perform Android or social-platform actions.

Operator quick start

Use Windows with Python 3.12 or newer. Install Android SDK Platform Tools if you use the existing device dashboard, then install and launch from PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
adb devices -l
python -m toksobot

USB debugging authorization and ADB Wi-Fi pairing remain manual operator responsibilities. Never place credentials, tokens, device identity, or private data in workflow files, variables, errors, events, fixtures, documentation, or screenshots.

Workflow engine developer example

This example is local and side-effect free. It persists a workflow catalog and creates a run; an application can register its own typed async action handlers and call WorkflowRunner.resume().

from pathlib import Path

from toksobot.workflows.models import EndNode, WorkflowDefinition
from toksobot.workflows.sqlite_repository import SQLiteWorkflowRepository

repository = SQLiteWorkflowRepository(Path("local-workflows.db"))
definition = WorkflowDefinition(
    workflow_id="safe-example",
    name="Safe example",
    version=1,
    entry_node="end",
    nodes={"end": EndNode(id="end")},
)
repository.save_definition(definition)
run = repository.create_run("example-run", "safe-example", 1, "end", {})

Templates use current template schema 2; legacy schema 1 remains readable. The editable template business version (WorkflowDefinition.version) is independent from that serialization schema and from SQLite database schema 1. Editing a used template means saving a new business version; a run stays pinned to the version with which it was created.

The engine supports action, condition, bounded loop, and end nodes; immutable JSON values; durable claims, bounded retries/deadlines, revision compare-and-swap, statuses, checkpoints, and ordered events. User keys beginning with the reserved _engine prefix are forbidden because that namespace holds claims, retries, and loop frames. Safe value paths split on an unescaped dot; the path escape grammar uses \. for a literal dot and \\ for a literal backslash. Persisted event/error data is categorical and must contain no secrets or raw plugin exceptions.

Developer checks

python -m pip install -e ".[dev]"
$env:QT_QPA_PLATFORM='offscreen'
python -m pytest -v
python -m ruff check .
python -m mypy src
git diff --check
python -m pip wheel . --no-deps --wheel-dir dist

Read the architecture, project status, and work log before extending the engine.

Current limitations

There is no visual builder, no recorder, no Android actions, no Google Flow actions, no TikTok actions, and no multi-device scheduler. There is also no platform-specific live workflow, product catalog, asset pipeline, OCR, screen stream, or security-challenge bypass. CAPTCHA, OTP, MFA, and account verification require legitimate manual operator intervention.