manigent 1.3.1__py3-none-any.whl

manigent/system_skills/update-skill-config/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: update-skill-config
+description: >
+  Add, modify, or remove an entry in a per-agent skill config file
+  (the JSON files under `{agent_dir}/skill-hub/configs/<name>.json`,
+  carrying API keys, sync windows, source/rule definitions, etc.).
+  Use whenever you (an agent) need to mutate your own skill config,
+  OR — when you are the user's assistant — when you need to do so on
+  behalf of another agent the user owns. **Do not edit those files
+  directly with Edit/Write/Bash** — go through this skill so the
+  server's per-agent config mirror stays in sync with the runner's
+  file; a direct edit silently drifts and can be clobbered by the
+  next AGENT_SETTINGS_CHANGE broadcast.
+---
+
+# Update Skill Config
+
+Update the runtime config for a configurable skill. Common cases: API
+keys, sync windows, ETL source/rule definitions.
+
+There are two callsites for this skill:
+
+- **Agent-self** — you (a worker/coordinator) were asked to modify
+  your own `skill-hub/configs/<name>.json`. Use `self` as the agent
+  argument and rely on the runner-injected env (`MANIGENT_AGENT_ID`
+  / `MANIGENT_AGENT_TOKEN` / `MANIGENT_SERVER_URL`).
+- **Assistant-on-another-agent** — you are `{username}-assistant` and
+  the user asked you to configure a skill on one of their other
+  agents. Use the agent's name and `$MANIGENT_ASSISTANT_TOKEN`.
+
+## Steps (agent-self)
+
+1. **Fetch the current config and starter template** so you know the
+   shape:
+   ```bash
+   curl -s -H "Authorization: Bearer $MANIGENT_AGENT_TOKEN" \
+        "$MANIGENT_SERVER_URL/agents/$MANIGENT_AGENT_ID/skills/<skill_name>/config" \
+        | jq .
+   ```
+   The response carries `config` (current), `starter_config` (template
+   with `${VAR}` placeholders for secrets), and `starter_config_text`
+   (the JSONC source with comments).
+
+2. **Build the full new config**. The PUT replaces the entry whole —
+   carry over the existing keys and apply your delta on top. Do not
+   invent values for missing secrets; ask the user.
+
+3. **Write the config JSON** to a scratch file in cwd:
+   ```bash
+   tmpfile=$(mktemp).json
+   cat > "$tmpfile" <<'JSON'
+   { "...": "..." }
+   JSON
+   ```
+
+4. **Apply via the CLI**:
+   ```bash
+   manigent skill set-config self <skill_name> "$tmpfile"
+   ```
+   The CLI picks up your agent token from the env, PUTs to the server,
+   which persists the entry to `card.local_settings.skill_configs` and
+   broadcasts `AGENT_SETTINGS_CHANGE` — the runner's
+   `_apply_local_settings` writes through to
+   `{agent_dir}/skill-hub/configs/<skill_name>.json` immediately.
+
+5. **Clean up the scratch file** and confirm.
+
+## Steps (assistant-on-another-agent)
+
+Same flow, but resolve `<agent>` to a name/id and use
+`$MANIGENT_ASSISTANT_TOKEN` instead of `$MANIGENT_AGENT_TOKEN`:
+
+```bash
+curl -s -H "Authorization: Bearer $MANIGENT_ASSISTANT_TOKEN" \
+     "$MANIGENT_SERVER_URL/agents/<agent_id>/skills/<skill_name>/config" \
+     | jq .
+# ... build $tmpfile ...
+manigent skill set-config <agent> <skill_name> "$tmpfile"
+```
+
+## Error handling
+
+- "skill not installed on agent" → run `/manigent:install-skill` first.
+- "invalid JSON" → show the user what you wrote and fix.
+- "'self' requires MANIGENT_AGENT_ID..." → the env vars aren't set;
+  you're probably not in an agent subprocess. Pass an explicit agent
+  name instead.

manigent/system_skills/update-skill-config/manifest.json

@@ -0,0 +1,6 @@
+{
+  "audiences": ["assistant", "worker", "coordinator"],
+  "surfaces": ["agent_runtime"],
+  "version": "1.0.0",
+  "description": "Update a skill's per-agent runtime config (assistant on any owned peer; worker/coordinator on self)."
+}

manigent/utils/agent_processes.py

@@ -0,0 +1,276 @@
+# SPDX-License-Identifier: MIT
+"""
+manigent/utils/agent_processes.py
+
+Agent discovery and process liveness on ONE machine — the single copy of the
+logic that answers "which agents are set up here, and which of them are
+actually running right now".
+
+Extracted from ``cli_lifecycle.py`` because it now has two consumers that must
+never disagree:
+
+- ``manigent/cli_lifecycle.py`` — the ``manigent start / stop / status``
+  commands a human runs in a terminal.
+- ``manigent_daemon/`` — the connection daemon shipped as the separate
+  ``manigent-daemon`` distribution, which reports the same facts to the
+  server so the web UI can show them.
+
+The daemon is a DIFFERENT distribution and cannot import ``manigent`` (that
+is the whole point — it must install in seconds and start even when the
+runner's heavy dependency stack is broken). ``scripts/build-daemon-package.sh``
+therefore copies this file verbatim into the daemon wheel as
+``manigent_daemon/agent_processes.py``, and ``manigent_daemon/discovery.py``
+imports whichever copy exists. Two consequences, both load-bearing:
+
+1. **Stdlib only.** No ``manigent.*`` import, no third-party import, not even
+   ``typer``. Anything added here that is not in the standard library breaks
+   the daemon's "tiny dependencies" guarantee. Reporting is the caller's job:
+   the functions here return values and never print.
+2. **Public names only.** ``discovery.py`` re-exports with ``import *``, which
+   skips underscore-prefixed names. A helper that needs to be visible to the
+   daemon must not start with ``_``.
+
+``cli_lifecycle`` keeps its historical ``_``-prefixed aliases (``_pid_is_alive``
+and friends) so existing imports and tests continue to resolve.
+"""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+IS_WINDOWS = sys.platform == "win32"
+
+# How long a graceful stop is given before escalating to a force kill. Kept
+# here rather than at the call sites so a terminal `manigent stop` and a
+# remote stop driven from the web behave identically.
+STOP_GRACE_SECONDS = 5.0
+_STOP_POLL_SECONDS = 0.25
+
+
+def popen_detached_kwargs() -> dict:
+    """Popen kwargs that detach the child so it outlives the parent shell.
+
+    Windows needs DETACHED_PROCESS (no inherited console) plus
+    CREATE_NEW_PROCESS_GROUP (so we can later deliver CTRL_BREAK_EVENT).
+    POSIX just needs start_new_session=True.
+    """
+    if IS_WINDOWS:
+        flags = (
+            getattr(subprocess, "DETACHED_PROCESS", 0)
+            | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+        )
+        return {"creationflags": flags}
+    return {"start_new_session": True}
+
+
+def pid_is_alive(pid: int) -> bool:
+    """Check whether a PID refers to a live process, without signaling it.
+
+    On Windows, ``os.kill(pid, 0)`` actually terminates the target — so we
+    must use a non-signaling query (tasklist) instead.
+    """
+    if IS_WINDOWS:
+        result = subprocess.run(
+            ["tasklist", "/FI", f"PID eq {pid}", "/NH", "/FO", "CSV"],
+            stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+            text=True, check=False,
+        )
+        return f'"{pid}"' in (result.stdout or "")
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ProcessLookupError):
+        return False
+
+
+def signal_terminate(pid: int) -> None:
+    """Send a graceful termination request. Silently no-ops if the target is gone.
+
+    POSIX: SIGTERM. Windows: CTRL_BREAK_EVENT to the process group (works
+    because agents are spawned with CREATE_NEW_PROCESS_GROUP).
+    """
+    try:
+        if IS_WINDOWS:
+            os.kill(pid, getattr(signal, "CTRL_BREAK_EVENT", 15))
+        else:
+            os.kill(pid, signal.SIGTERM)
+    except (OSError, ProcessLookupError):
+        pass
+
+
+def signal_kill(pid: int) -> None:
+    """Force-kill a process. Silently no-ops on failure.
+
+    POSIX: SIGKILL. Windows: ``taskkill /F`` — reliable even when graceful
+    signaling didn't land.
+    """
+    try:
+        if IS_WINDOWS:
+            subprocess.run(
+                ["taskkill", "/F", "/PID", str(pid)],
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                check=False,
+            )
+        else:
+            os.kill(pid, signal.SIGKILL)
+    except OSError:
+        pass
+
+
+def read_pid(pid_file: Path) -> int | None:
+    """The live PID recorded in ``pid_file``, or None.
+
+    None covers all three "not running" shapes with one answer: no pidfile, an
+    unreadable/garbage pidfile, and a pidfile naming a process that has since
+    died (the stale-pidfile case). Callers that need to tell the last one apart
+    check ``pid_file.exists()`` themselves.
+    """
+    if not pid_file.exists():
+        return None
+    try:
+        pid = int(pid_file.read_text().strip())
+        return pid if pid_is_alive(pid) else None
+    except (ValueError, OSError):
+        return None
+
+
+def stop_pid(pid_file: Path) -> int | None:
+    """Stop the process named by ``pid_file``. Returns the PID it stopped, else None.
+
+    Graceful first (SIGTERM / CTRL_BREAK_EVENT), then a force kill after a
+    :data:`STOP_GRACE_SECONDS` grace period (SIGKILL / taskkill /F). The
+    pidfile is removed either way, including when it was already stale — that
+    cleanup is why a caller should prefer this over signalling by hand.
+
+    Returns None when there was nothing to stop, so a caller can distinguish
+    "stopped it" from "it wasn't running" without a second probe. Never prints:
+    the terminal CLI and the remote daemon word the outcome differently.
+    """
+    if not pid_file.exists():
+        return None
+    try:
+        pid = int(pid_file.read_text().strip())
+    except (ValueError, OSError):
+        pid_file.unlink(missing_ok=True)
+        return None
+
+    if not pid_is_alive(pid):
+        pid_file.unlink(missing_ok=True)
+        return None
+
+    signal_terminate(pid)
+    for _ in range(int(STOP_GRACE_SECONDS / _STOP_POLL_SECONDS)):
+        time.sleep(_STOP_POLL_SECONDS)
+        if not pid_is_alive(pid):
+            break
+    else:
+        signal_kill(pid)
+
+    pid_file.unlink(missing_ok=True)
+    return pid
+
+
+def agents_dir(data_dir: Path) -> Path:
+    """``{data_dir}/agents`` — where every locally registered agent lives."""
+    return Path(data_dir).expanduser() / "agents"
+
+
+def prefixed_name(username: str, agent_name: str) -> str:
+    """``budget-analyst`` -> ``alice-budget-analyst`` (idempotent)."""
+    prefix = f"{username}-"
+    return agent_name if agent_name.startswith(prefix) else f"{prefix}{agent_name}"
+
+
+def find_agent_dir(agents_root: Path, prefixed: str) -> Path | None:
+    """Find an agent's directory matching ``{prefixed}-{id}/``.
+
+    Requires ``credential.json`` so a half-registered directory is invisible,
+    the same rule :func:`list_owned_agent_short_names` applies.
+    """
+    if not agents_root.exists():
+        return None
+    for d in agents_root.iterdir():
+        if d.is_dir() and d.name.startswith(f"{prefixed}-"):
+            if (d / "credential.json").exists():
+                return d
+    return None
+
+
+def list_owned_agent_short_names(agents_root: Path, username: str) -> list[str]:
+    """Return owned agents' short names by globbing the filesystem.
+
+    Pattern: ``{agents_root}/{username}-{short}-{id}/`` with ``credential.json``
+    present. Skips ``DELETED-*`` (renamed by self-destruct) and any dir
+    without a ``credential.json`` (half-registered). The trailing ``-{id}``
+    is stripped off the right.
+
+    Deliberately a filesystem glob rather than a read of ``settings.json``:
+    the directory is what a process can actually be started from, so an agent
+    that exists on disk is reported even if some config file forgot it.
+    """
+    if not agents_root.exists():
+        return []
+    prefix = f"{username}-"
+    names: list[str] = []
+    for entry in sorted(agents_root.iterdir()):
+        if not entry.is_dir() or entry.name.startswith("DELETED-"):
+            continue
+        if not entry.name.startswith(prefix):
+            continue
+        if not (entry / "credential.json").exists():
+            continue
+        rest = entry.name[len(prefix):]
+        short = rest.rsplit("-", 1)[0] if "-" in rest else rest
+        if short:
+            names.append(short)
+    return names
+
+
+def agent_pid_file(agent_dir: Path) -> Path:
+    """The pidfile ``manigent start`` writes for one agent."""
+    return Path(agent_dir) / "agent.pid"
+
+
+def scan_agents(agents_root: Path, username: str) -> list[dict]:
+    """One dict per locally registered agent, with its OBSERVED run state.
+
+    ``[{"short_name", "name", "dir", "pid", "state"}, …]`` sorted by
+    ``short_name``, where ``state`` is one of:
+
+    - ``"running"``   — the pidfile names a live process.
+    - ``"crashed"``   — a pidfile exists but the process is gone. The machine
+      started this agent and it exited without being asked to; the web UI
+      shows it as "Stopped on its own" so the user can tell it apart from a
+      stop they performed.
+    - ``"stopped"``   — no pidfile. Never started, or stopped cleanly.
+
+    Observed, never remembered: the state is read off the filesystem on every
+    call, so an agent that died without saying goodbye reads as ``crashed``
+    within one scan rather than lingering as "running" until something notices.
+    """
+    rows: list[dict] = []
+    for short in list_owned_agent_short_names(agents_root, username):
+        full = prefixed_name(username, short)
+        agent_dir = find_agent_dir(agents_root, full)
+        if agent_dir is None:
+            continue
+        pid_file = agent_pid_file(agent_dir)
+        pid = read_pid(pid_file)
+        if pid is not None:
+            state = "running"
+        elif pid_file.exists():
+            state = "crashed"
+        else:
+            state = "stopped"
+        rows.append({
+            "short_name": short,
+            "name": full,
+            "dir": str(agent_dir),
+            "pid": pid,
+            "state": state,
+        })
+    return rows

manigent/utils/agent_storage.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: MIT
+"""
+manigent/utils/agent_storage.py
+The agent's two persistent storage folders — one place that decides where
+they live, creates them, and names the env vars that carry them.
+
+- **Local storage** (``local_settings.local_storage_dir``, default
+  ``{AGENT_DIR}/storage``): this agent's own files that outlive any one
+  project — caches, downloads, datasets, working state. Unlike the per-project
+  sandbox, nothing here is scoped to a chat thread.
+- **Shared storage** (``local_settings.shared_storage_dir``, default
+  ``{MANIGENT_DIR}/shared_storage``): one folder every agent on this computer
+  can read and write, for handing files between agents without going through
+  a chatroom. ``{AGENT_DIR}/shared_storage`` is a symlink to it so the folder
+  shows up in the agent's home.
+
+Both are exposed to every LLM invocation as ``$AGENT_LOCAL_STORAGE_DIR`` /
+``$AGENT_SHARED_STORAGE_DIR`` and listed in the prompt's FILES & STATE block.
+Paths in local_settings resolve exactly like ``knowledge_dir``
+(``FileUtil.resolve_local_dir``): absolute and ``~`` verbatim, relative
+against the agent's own home (AGENT_DIR).
+
+Called at agent registration (so a new agent's home already has them), at
+every runner start (so agents registered before this existed — or created
+from the web app — get them too), and on a settings change.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .file_io import FileUtil
+
+logger = logging.getLogger(__name__)
+
+LOCAL_STORAGE_ENV = "AGENT_LOCAL_STORAGE_DIR"
+SHARED_STORAGE_ENV = "AGENT_SHARED_STORAGE_DIR"
+
+LOCAL_STORAGE_KEY = "local_storage_dir"
+SHARED_STORAGE_KEY = "shared_storage_dir"
+
+LOCAL_STORAGE_DIRNAME = "storage"
+SHARED_STORAGE_DIRNAME = "shared_storage"
+
+
+@dataclass(frozen=True)
+class AgentStorage:
+    """Resolved absolute storage folders for one agent."""
+
+    local: Path
+    shared: Path
+
+    def env(self) -> dict[str, str]:
+        """The env vars handed to every LLM subprocess."""
+        return {
+            LOCAL_STORAGE_ENV: str(self.local),
+            SHARED_STORAGE_ENV: str(self.shared),
+        }
+
+
+def manigent_dir_for(agent_dir: Path) -> Path:
+    """The Manigent data dir (``~/.manigent`` by default) an agent lives in.
+
+    Agents live at ``{MANIGENT_DIR}/agents/<name>-<id>/``, so the layout
+    answers it directly; the env/default fallback only covers an agent dir
+    placed somewhere else by hand (``--save``).
+    """
+    if agent_dir.parent.name == "agents":
+        return agent_dir.parent.parent
+    return Path(os.environ.get("MANIGENT_DATA_DIR", str(Path.home() / ".manigent")))
+
+
+def default_shared_storage_dir(manigent_dir: Path) -> Path:
+    return manigent_dir / SHARED_STORAGE_DIRNAME
+
+
+def resolve_storage(agent_dir: Path, local_settings: dict) -> AgentStorage:
+    """Settings → absolute folders. An empty setting means the default."""
+    local = FileUtil.resolve_local_dir(
+        local_settings.get(LOCAL_STORAGE_KEY) or "", agent_dir
+    )
+    shared = FileUtil.resolve_local_dir(
+        local_settings.get(SHARED_STORAGE_KEY) or "", agent_dir
+    )
+    return AgentStorage(
+        local=(local or agent_dir / LOCAL_STORAGE_DIRNAME).absolute(),
+        shared=(shared or default_shared_storage_dir(manigent_dir_for(agent_dir))).absolute(),
+    )
+
+
+def ensure_storage(agent_dir: Path, storage: AgentStorage) -> None:
+    """Create both folders and point ``{agent_dir}/shared_storage`` at the
+    shared one. Idempotent; never raises — a storage folder that can't be
+    created must not stop the runner, the agent just finds it missing.
+
+    The link is only ever created or re-pointed when it is a symlink (or
+    absent). A real folder already sitting at that name is left alone.
+    """
+    for d in (storage.local, storage.shared):
+        try:
+            d.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            logger.warning(f"Could not create storage folder {d}: {e}")
+
+    link = agent_dir / SHARED_STORAGE_DIRNAME
+    if link.absolute() == storage.shared:
+        return  # the shared folder IS the link location; nothing to link
+    try:
+        if link.is_symlink():
+            if Path(os.readlink(link)) == storage.shared:
+                return
+            link.unlink()
+        elif link.exists():
+            logger.warning(
+                f"{link} exists and is not a symlink; leaving it alone "
+                f"(shared storage is {storage.shared})"
+            )
+            return
+        link.symlink_to(storage.shared, target_is_directory=True)
+    except OSError as e:
+        # Windows without symlink privilege lands here. The env var and the
+        # prompt still carry the real path, so the agent can reach it.
+        logger.warning(f"Could not link {link} -> {storage.shared}: {e}")