procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/_lib/README.md

@@ -0,0 +1,119 @@
+# tools/_lib
+
+Shared helpers for every tool. Import these — don't duplicate logic.
+
+## creds.py — the OS credential store (Windows / macOS / Linux)
+
+```python
+from tools._lib import creds
+
+token = creds.get("ryver", "api-token")              # raises KeyError if missing
+maybe = creds.get_optional("ryver", "api-token")     # None if missing
+creds.has("ryver", "api-token")                      # bool
+```
+
+Storing is done through `scripts/set-credential.py`, not from inside tool code.
+
+`creds.py` is a thin facade; the store itself is a pluggable backend in
+`creds_backends.py`, selected once by `AAT_CREDS_BACKEND`. **Leave it unset** and each
+OS gets its own native store, with the same `agents-and-tools:<tool>:<secret>` identity
+everywhere:
+
+| platform | store | writable |
+|---|---|---|
+| Windows | Credential Manager | yes |
+| macOS | login Keychain | yes |
+| Linux (desktop) | GNOME Keyring / KWallet over D-Bus | yes |
+
+A **headless** machine has no OS keyring at all — no session bus, so there is nothing
+to talk to. That is not a bug to work around with a fallback that silently reads as
+empty; pick a backend explicitly:
+
+- `AAT_CREDS_BACKEND=encrypted-file` — one passphrase-encrypted file
+  (`AAT_SECRETS_FILE`, default `~/.config/agents-and-tools/secrets.enc`; passphrase in
+  `AAT_SECRETS_PASSPHRASE`). Read/write, so `set-credential.py` works. This is the
+  right choice for a server or a stateful container.
+- `AAT_CREDS_BACKEND=file` / `env` — read-only views of secrets a host or cluster
+  already manages (mounted k8s Secret, or one JSON blob).
+- `bridge` / `procesio` — read-only HTTP resolvers (host bridge, platform store).
+
+The distinction that matters: the four **owned** stores (windows / macos / linux /
+encrypted-file) are read/write; the four **borrowed** ones are read-only, so a
+container can never pretend to own the secret store it is reading from.
+
+A wrong passphrase on `encrypted-file` **raises** rather than returning an empty store.
+Reading as empty would be reported upstream as "credential missing", and the caller
+would helpfully store the secret again under the wrong key.
+
+## io.py — JSON I/O contract
+
+```python
+from tools._lib.io import emit, fail, log
+
+log("starting")                                       # stderr
+emit({"result": "ok"})                                # stdout JSON + exit 0
+fail("invalid_input", "name is required", {"arg": "name"})  # stdout error + exit 1
+```
+
+`emit` and `fail` both call `sys.exit` — they never return.
+
+## manifest.py — tool.yaml loading
+
+Used by `registry.py`. Tool authors don't usually touch this directly.
+
+## google_auth.py — shared Google OAuth (multi-account)
+
+All Google tools (calendar, contacts, mail, drive, sheets, docs, slides) share
+**one OAuth client** (`agents-and-tools:google:oauth-client`) and authenticate
+with **per-account refresh tokens**:
+
+| account | token secret |
+|---------|--------------|
+| `default` | `agents-and-tools:google:oauth-token` (backward compatible) |
+| `<label>` | `agents-and-tools:google:oauth-token@<label>` |
+
+`agents-and-tools:google:oauth-accounts` is a JSON index of known labels,
+maintained automatically by login/logout.
+
+**Selecting the active account** (highest priority first):
+1. `google_auth.set_account("<label>")` — called from the `--account` CLI flag
+2. `GOOGLE_ACCOUNT` env var
+3. `default`
+
+A `--account <label>` flag is parsed globally in `google_contacts/main.py`
+(stripped before argparse) so it applies to **every** action — auth *and* data.
+To add the flag to the other Google tools, copy the `_pop_account` helper +
+`set_account` call from `google_contacts/main.py`. Even without the flag, the
+other tools already honor the `GOOGLE_ACCOUNT` env var and the shared backend.
+
+One Google Cloud OAuth client can authorize many Google accounts. If the
+consent screen is in **Testing** mode, each extra account's email must be added
+as a **Test user** in Google Cloud Console before its `auth-login` will succeed.
+
+
+## contacts.py — published contact details in text or HTML
+
+Pure functions shared by the tools that read what a person publishes about
+themselves (`youtube extract-contacts`, `web page-contacts`, the `creator-scout`
+agent): `find_emails` (including `name [at] domain [dot] com`), `find_urls`,
+`classify_url` (linkedin / x / youtube / instagram / ... / link_in_bio / website),
+`affiliate_info` (PartnerStack and Impact tracking hosts, Rewardful `via`,
+FirstPromoter `fpr`, generic `ref` / `pc` / `aff` parameters), `extract`, `merge`,
+`collect` (several labelled texts, keeping where each find came from) and
+`extract_html` (mailto links, anchors, visible text, plus profile links embedded
+as JSON by link-in-bio services). Only what is literally on the page counts: no
+guessed addresses, no redirect resolution.
+
+## webserialize/ — serializing brokers for web-profile tools
+
+One broker process per tool owns its browser session/profile and executes
+commands strictly one at a time; parallel chat sessions queue instead of
+racing the profile (SingletonLock -> session invalidation). Registry of
+brokers/ports/owned sessions: `webserialize/registry.py` (whatsapp-personal
+47611, ryver-web 47612, fgo-web 47613, mirro 47614). Each tool routes its
+browser actions in `main.dispatch` and exposes `service-status/-start/-stop`;
+`--direct` / `<PREFIX>_DIRECT=1` is the in-process backup. The generic `web`
+tool routes run/get-text/screenshot on OWNED sessions through the owning
+broker (`web-steps` op) and stops the broker before save/delete-session.
+Reference integration + full design rationale: tools/whatsapp-personal
+(WHATSAPP-NOTES.md) and webserialize/server.py docstrings.

procesio_cli/tools/_lib/accounting.py

@@ -0,0 +1,120 @@
+"""Per-work-unit accounting hooks (spec P0.0-05).
+
+On the PROCESIO platform, each span of *active* agent processing is a **work-unit**
+that must feed the licensing meter: acquire an execution-environment (EE) slot on the
+shared Redis semaphore (Thread licenses) and emit a ``TrackAction``-shaped consume
+event with the measured ``ExecutionTime`` and ``Multiplicator`` (Time licenses). See
+``todo/on-hold/procesio-aat-module/03-execution-licensing-and-tracing.md``.
+
+Locally there is nothing to bill, so this module is a **no-op by default** - but the
+*emit seam* exists now, wrapped around every AAT execution, so the platform injects a
+real sink (one that speaks the semaphore + TrackAction protocols) without touching a
+single call site. Build the hook, not the feature.
+
+Design rules:
+  - **Zero overhead when unused.** Default sink swallows events; no output, no import
+    of anything heavy. Local Claude Code is unaffected.
+  - **Active processing only.** A work-unit span covers PROCESSING; a WAITING span is
+    simply not opened (the caller opens a fresh span on resume), so idle bills nothing.
+  - **Exceptions still close the span** - ``consume`` is emitted on the ``finally`` so a
+    failed action is still accounted for its partial time, matching PROCESIO's
+    per-action TrackAction-on-finish semantics.
+  - **No PROCESIO dependency.** The sink is an interface; timing uses a monotonic clock.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+from contextlib import contextmanager
+from typing import Callable
+
+# A sink is: (event: dict) -> None. Default = no-op.
+_sink: Callable[[dict], None] | None = None
+
+
+def _debug_sink(event: dict) -> None:
+    """Optional visibility for local debugging: one JSON line per event to stderr when
+    AAT_ACCOUNTING_DEBUG is truthy. Never on by default."""
+    import json
+    sys.stderr.write("[accounting] " + json.dumps(event, ensure_ascii=False) + "\n")
+    sys.stderr.flush()
+
+
+def set_sink(sink: Callable[[dict], None] | None) -> None:
+    """Install the accounting sink (the platform injects one that acquires/releases the
+    EE semaphore and publishes TrackAction). ``None`` restores the default no-op."""
+    global _sink
+    _sink = sink
+
+
+def _resolve_sink() -> Callable[[dict], None] | None:
+    if _sink is not None:
+        return _sink
+    if os.environ.get("AAT_ACCOUNTING_DEBUG", "").strip().lower() in ("1", "true", "yes", "on"):
+        return _debug_sink
+    return None
+
+
+def emit(event: dict) -> None:
+    """Send one accounting event to the configured sink (no-op if none). Never raises -
+    accounting must never break an agent run."""
+    sink = _resolve_sink()
+    if sink is None:
+        return
+    try:
+        sink(dict(event))
+    except Exception:  # noqa: BLE001 - accounting is best-effort, never fatal
+        pass
+
+
+def _ctx() -> dict:
+    """Active (workspace, user) from the server-established env (item P0.0-01)."""
+    return {
+        "ws": os.environ.get("AAT_WORKSPACE_ID") or None,
+        "user": os.environ.get("AAT_USER_ID") or None,
+    }
+
+
+@contextmanager
+def work_unit(kind: str, *, ws: str | None = None, user: str | None = None,
+              run_id: str | None = None, multiplicator: float = 1.0):
+    """Mark a span of ACTIVE agent processing.
+
+    On enter: emit ``acquire`` (the platform acquires an EE slot). On exit (incl. on
+    exception): emit ``consume`` with the measured ``execution_ms`` and the work-unit's
+    ``multiplicator`` (the billing weight; default 1.0). The event shape mirrors
+    PROCESIO's ``TrackActionDto`` so a platform sink maps it 1:1.
+
+    Yields a small mutable dict the caller may annotate (e.g. set ``action`` / ``tool``);
+    those fields ride along on the ``consume`` event.
+
+    Usage::
+
+        with accounting.work_unit("tool", run_id=rid) as wu:
+            wu["tool"] = "ryver"
+            ... do the work ...
+    """
+    c = _ctx()
+    base = {
+        "kind": kind,
+        "ws": ws if ws is not None else c["ws"],
+        "user": user if user is not None else c["user"],
+        "run_id": run_id,
+        "multiplicator": float(multiplicator),
+    }
+    info: dict = {}
+    emit({**base, "event": "acquire", "ts": _clock_iso()})
+    start = time.monotonic()
+    try:
+        yield info
+    finally:
+        execution_ms = int((time.monotonic() - start) * 1000)
+        emit({**base, **info, "event": "consume", "execution_ms": execution_ms,
+              "ts": _clock_iso()})
+
+
+def _clock_iso() -> str:
+    # Wall-clock timestamp for the event. Kept local so the module has no other deps.
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds")