Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Central path resolution for OpenCompany's on-disk state.
Single source of truth for every directory the app reads or writes.
The default root lives at ``~/.opencompany/`` — the user's home directory,
cross-platform via :meth:`pathlib.Path.home` (``$HOME`` on POSIX,
``%USERPROFILE%`` on Windows). Override with ``DATA_DIR`` env var.
Why home-rooted (not project-local): claude's auth, the WhatsApp
session DB, the credentials store, and per-workflow workspaces all
survive ``rm -rf`` of the repo. Multiple OpenCompany checkouts on the
same machine share state instead of each carrying its own copy. The
``~/.opencompany/`` convention matches Stripe's ``~/.config/stripe/``,
ngrok's ``~/.ngrok2/``, and claude code's own ``~/.claude/``.
Generic subtree layout under ``<DATA_DIR>/`` (= ``~/.opencompany/`` by
default). The module exports only generic helpers — plugin-specific
subpaths (``<DATA_DIR>/claude/``, ``<DATA_DIR>/packages/stripe/bin/``,
etc.) are composed at the plugin's call site, NOT hardcoded here.
That keeps this module from growing one helper per package:
- :func:`data_path` ``<DATA_DIR>/<subpath>`` — universal state-path
primitive every plugin composes against
- :func:`packages_dir` ``<DATA_DIR>/packages/`` — downloaded-binary root
- :func:`package_dir` ``<DATA_DIR>/packages/<name>/`` — per-service install
slot (callers compose further, e.g.
``package_dir("claude") / "npm"``)
- :func:`daemons_dir` ``<DATA_DIR>/daemons/`` — supervised daemon cwds
- :func:`workspaces_dir` ``<DATA_DIR>/workspaces/`` — per-workflow scratch
- :func:`workspace_dir` ``<DATA_DIR>/workspaces/<workflow_id>/``
- :func:`example_workflows_dir` git-tracked seed JSONs at
``<repo>/.opencompany/workflows/`` (NOT under DATA_DIR)
Reference layout once typical plugins compose against the helpers
above (Wave 14):
- ``<DATA_DIR>/claude/`` Claude Code auth state (CLAUDE_CONFIG_DIR)
- ``<DATA_DIR>/packages/`` Single shared OpenCompany install
root. Holds one ``package.json`` + ``bun.lock`` + ``node_modules/``
covering every OpenCompany-managed npm-registry package
(``@anthropic-ai/claude-code``, ``edgymeow``, ``agent-browser``,
``cf``, ``vercel``). Each plugin's ``_install.py`` calls
``core.js_runtime.add_package`` (``bun add --cwd <packages_dir>``)
to extend the tree idempotently — bun manages the dep graph and
runs the bin shims on its own runtime; no Node or npm.
- ``<DATA_DIR>/packages/stripe/`` Stripe CLI binary (non-npm)
- ``<DATA_DIR>/packages/temporal/`` Temporal CLI binary (non-npm,
pooch-managed)
- ``<DATA_DIR>/workspaces/<slug>/`` per-workflow scratch
- ``<DATA_DIR>/daemons/`` supervised daemon cwds (shared root)
- ``<DATA_DIR>/whatsapp/`` persistent WhatsApp session DB
- ``<DATA_DIR>/credentials.db`` Fernet-encrypted secrets
- ``<DATA_DIR>/workflow.db`` SQLite app DB
- ``<DATA_DIR>/temporal.db`` Temporal server SQLite
Legacy MachinaOS builds split binaries under
:func:`platformdirs.user_cache_path` (``~/.cache/MachinaOs/`` etc.)
and Temporal under its own ``pooch.os_cache("machinaos-temporal")``
namespace — operators reported both as "not local". Daemon cwds
also used to live under ``workspaces/_<namespace>/`` and polluted
per-workflow scratch with framework state. Consolidating everything
under ``<DATA_DIR>/`` means a single ``mv ~/.opencompany /backup``
carries the entire OpenCompany footprint.
Out of scope: globally-installed binaries (Himalaya — system
package manager) and the dev workspace's own `package.json` deps
(none of the runtime packages remain there after the WhatsApp
migration).
Shipped example workflows live at ``<repo>/.opencompany/workflows/`` —
git-tracked seed JSONs auto-imported on first launch by
``services.example_loader``. During migration, the legacy
``<repo>/.machina/workflows/`` directory is used only when the canonical
directory is absent. The location is independent of ``DATA_DIR``.
Importable as ``from core.paths import data_path, package_dir,
workspace_dir, …`` so consumers never have to recompute the root
themselves (the old ``Path(__file__).resolve().parents[N] / "data"
/ ...`` idiom was duplicated across 4+ files and brittle to file
moves).
DATA_DIR resolution rules (see :func:`opencompany_root`):
- Starts with ``~`` → ``Path.expanduser()`` (user home).
- Absolute path → used verbatim.
- Relative path → resolved under the repo root (back-compat for
callers who set ``DATA_DIR=data`` to keep the pre-cutover layout).
Migration of pre-cutover ``<repo>/data/`` trees is the operator's
responsibility — set ``DATA_DIR`` to the legacy path (e.g.
``DATA_DIR=data``) to keep using the old layout, or move the
contents manually:
mv server/data/claude-machina ~/.opencompany/claude
mv server/data/workspaces ~/.opencompany/workspaces
mv server/data/workflow.db ~/.opencompany/workflow.db
mv server/data/credentials.db ~/.opencompany/credentials.db
"""
from __future__ import annotations
import re
from pathlib import Path
from core.approot import app_root, example_workflows_root
from core.logging import get_logger
logger = get_logger(__name__)
_UNSAFE_COMPONENT = re.compile(r"[^A-Za-z0-9._-]")
def safe_path_component(value: str, fallback: str = "item") -> str:
"""Sanitize a wire identifier (node id, process name) into one safe
path component.
Canvas node ids can be colon-namespaced (``2:processManager:4``) and
``ntpath.join`` / ``PureWindowsPath.__truediv__`` parse a leading
``2:`` as a DRIVE, silently discarding the base path — so raw ids
must never be joined into a path. Dot-only results (``..``) collapse
to ``fallback`` so traversal cannot survive sanitization.
"""
cleaned = _UNSAFE_COMPONENT.sub("_", str(value or ""))
return cleaned if cleaned.strip(".") else fallback
# The app tree root is resolved by ``core.approot`` (``OPENCOMPANY_APP_ROOT``
# override for relocated bundles) — never climbed from ``__file__`` here.
_CANONICAL_STATE_DIR = ".opencompany"
_LEGACY_STATE_DIR = ".machina"
def _has_runtime_state(root: Path) -> bool:
"""Return whether ``root`` contains state beyond shipped workflows.
``.opencompany/workflows`` is checked into the repository, so neither an
empty canonical directory nor a seed-only directory proves that a user
migrated runtime state. Any other entry makes that root authoritative.
"""
if not root.exists():
return False
if not root.is_dir():
return True
try:
return any(entry.name != "workflows" for entry in root.iterdir())
except OSError:
# If the directory cannot be inspected, keep it authoritative rather
# than redirecting state based on an uncertain observation.
return True
def project_root() -> Path:
"""Absolute path of the OpenCompany application tree root.
The git checkout root in development, the npm package root for a
global install, or the bundle's ``app-root/`` for the desktop app
(``OPENCOMPANY_APP_ROOT``). See :mod:`core.approot`.
"""
return app_root()
def _resolve_data_path(base: str, subpath: str = "") -> Path:
"""Canonical state-path resolution primitive. Always returns absolute.
Shared by :func:`data_path` (public entry point) and
``Settings._resolve_under_data`` (the Pydantic-side mirror used by
state-path properties like ``credentials_db_resolved``). One
implementation so the two never drift.
Rules:
- ``Path.expanduser()`` on ``base`` — no-op when no ``~`` present.
- Absolute resolved ``base`` → used verbatim.
- Relative ``base`` → resolved under :func:`project_root` (so
dev mode's ``DATA_DIR=.opencompany`` lands at ``<repo>/.opencompany/``
regardless of the subprocess's cwd).
- Empty ``subpath`` → returns the resolved base.
- Absolute ``subpath`` → returned verbatim.
- Relative ``subpath`` → joined onto the resolved base.
"""
b = Path(base).expanduser()
if not b.is_absolute():
b = project_root() / b
# Rebranded installs use .opencompany. If an upgraded checkout has not
# moved its state yet, keep using the existing .machina sibling rather
# than silently starting with empty databases and credentials.
if b.name == _CANONICAL_STATE_DIR and not _has_runtime_state(b):
legacy = b.with_name(_LEGACY_STATE_DIR)
if _has_runtime_state(legacy):
b = legacy
if not subpath:
return b.resolve()
p = Path(subpath)
return p.resolve() if p.is_absolute() else (b / p).resolve()
def data_path(subpath: str | Path = "") -> Path:
"""Absolute path of ``<DATA_DIR>/<subpath>``.
Single entry point for every state location OpenCompany reads or
writes. Reads ``Settings.data_dir`` (env var ``DATA_DIR``) — so
the dev / daemon split (``.env.dev`` vs ``.env.template``) moves
every state path together. Pass an empty ``subpath`` to get the
DATA_DIR root.
Settings is instantiated lazily — Pydantic caches the result.
Resolution rules: see :func:`_resolve_data_path`.
"""
from core.config import Settings
return _resolve_data_path(Settings().data_dir, str(subpath))
def opencompany_root() -> Path:
"""Absolute path of the configured DATA_DIR (= ``data_path()``)."""
return data_path()
def machina_root() -> Path:
"""Deprecated compatibility alias for :func:`opencompany_root`."""
return opencompany_root()
def packages_dir() -> Path:
"""Root for binaries OpenCompany downloads on first use.
Resolves to ``<DATA_DIR>/packages/`` — under the same operator-
visible tree as auth state, workspaces, and daemon cwds. One
``mv ~/.opencompany`` carries every OpenCompany-managed file together,
and one glance at ``~/.opencompany/`` shows the operator everything
the app owns.
Pre-fix this used :func:`platformdirs.user_cache_path` so binaries
landed at ``~/.cache/MachinaOs/`` (Linux) / ``~/Library/Caches/
MachinaOs/`` (macOS) / ``%LOCALAPPDATA%\\MachinaOs\\Cache\\``
(Windows). Operators reported it as "not local" — the split
between binaries (OS cache) and state (DATA_DIR) was confusing
and the OS-cache rationale (company clean keeps auth, cache
wipe drops binaries) didn't matter in practice since both wipe
operations are operator-driven anyway.
See :func:`package_dir` for the per-service accessor.
"""
return data_path("packages")
def package_dir(name: str) -> Path:
"""Per-service install folder under :func:`packages_dir`.
Canonical layout — each plugin's installer (``ensure_stripe_cli``,
``ensure_temporal_binaries``, ``agent_browser_binary_path``, …)
drops its tree here. Examples::
package_dir("stripe") -> ~/.opencompany/packages/stripe/
package_dir("browser") -> ~/.opencompany/packages/browser/
Caller is responsible for ``mkdir(parents=True, exist_ok=True)``
so this helper stays side-effect-free and safe to call during
import-time path resolution.
"""
return packages_dir() / name
def daemons_dir() -> Path:
"""Root for supervised event-source daemons (``stripe listen``, etc.).
Resolves to ``<DATA_DIR>/daemons/`` — sibling of
:func:`workspaces_dir`. Daemons are framework-owned, long-lived
processes whose cwd is just a place to drop log / state files;
workspaces are per-workflow scratch owned by workflow nodes
(one subdir per ``Workflow.slug``). Conflating the two clutters
workspaces with framework state, which is what
``DaemonEventSource.workdir()`` used to do before this helper
existed.
"""
return data_path("daemons")
def workspaces_dir() -> Path:
"""Root for per-workflow workspaces.
Routes through ``data_path(Settings().workspace_base_dir)`` (env
var ``WORKSPACE_BASE_DIR``) so the path stays in lockstep with
every other state location — no hardcoded ``"workspaces"`` literal
that drifts when the env var changes.
"""
from core.config import Settings
return data_path(Settings().workspace_base_dir)
def workspace_dir(workflow_slug: str) -> Path:
"""Per-workflow workspace at ``<opencompany_root>/workspaces/<slug>/``.
Keyed by ``Workflow.slug``, NOT by ``Workflow.id`` — the parameter was
named ``workflow_id`` until it was noticed that every real caller
passes a slug (see ``WorkflowService._get_workspace_dir``, which is
what actually creates these directories, and the rename path in
``workflow_storage/handlers.py`` which moves them when the slug
changes). Passing an id here yields a directory that does not exist.
The workflow executor injects this into the execution context as
``ctx.raw["workspace_dir"]`` and the cli_agent service splices it
into each claude task's ``--add-dir`` so claude can read upstream
node outputs (``fileDownloader``, ``documentParser``, code
executors) + materialise its connected skills under
``<workspace_dir>/.claude/skills/``.
"""
return workspaces_dir() / workflow_slug
def example_workflows_dir() -> Path:
"""Shipped example workflow JSONs, auto-imported on first launch.
Canonically fixed at ``<repo>/.opencompany/workflows/`` — these are
git-tracked seed JSONs that ship with the repo. An existing legacy
``<repo>/.machina/workflows/`` directory is used when the canonical
directory has not been created yet. Neither path is under
:func:`opencompany_root`.
"""
canonical = example_workflows_root() / "workflows"
legacy = project_root() / _LEGACY_STATE_DIR / "workflows"
return canonical if canonical.exists() or not legacy.exists() else legacy
__all__ = [
"safe_path_component",
"project_root",
"opencompany_root",
"machina_root",
"data_path",
"packages_dir",
"package_dir",
"daemons_dir",
"workspaces_dir",
"workspace_dir",
"example_workflows_dir",
]