runspace 0.2.0__tar.gz

runspace-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,40 @@
+name: Bug report
+description: Something behaves differently from what the docs say
+labels: [bug]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you did, what you expected, and what you got instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: >
+        The smallest script or config that shows the problem. This is the
+        single most useful thing you can include.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Release number or commit SHA.
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.3"
+    validations:
+      required: true
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback or logs
+      render: text

runspace-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/islavutin-oss/runspace/security/advisories/new
+    about: Report privately, not as a public issue.

runspace-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Propose a change to what Runspace does
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: >
+        What are you trying to do that is awkward or impossible today?
+        Describe the situation, not the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you have in mind
+      description: If you have an API or config shape in mind, sketch it.
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you tried instead
+      description: Workarounds you have used, and why they fall short.

runspace-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What this changes
+
+<!-- One paragraph. What is different after this lands? -->
+
+## Why
+
+<!-- The reasoning a reviewer cannot get from the diff. Link the issue if
+     there is one. -->
+
+## Checklist
+
+- [ ] Tests cover the change, and a bug fix has a test that failed before it
+- [ ] `pytest` passes locally
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] Docs updated if behaviour or configuration changed

runspace-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write   # to attach build artifacts to the release
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Attach the artifacts to the release
+        if: github.event_name == 'release'
+        run: gh release upload "$GITHUB_REF_NAME" dist/*
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  # Publishing is a separate job so a build failure never leaves a partial
+  # upload, and so the PyPI credential is scoped to this job alone. It uses
+  # Trusted Publishing (OIDC) — there is no API token stored in the repo.
+  #
+  # Before the first run, configure a pending publisher on PyPI:
+  #   https://pypi.org/manage/account/publishing/
+  #   owner: <the GitHub owner>   repository: runspace
+  #   workflow: release.yml       environment: pypi
+  publish:
+    needs: build
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

runspace-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,129 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # The test job checks out agentino beside this repo. That step needs
+  # agentino to be public, or a token with access to it — until then this
+  # job cannot run on a fork or a fresh clone.
+  AGENTINO_REF: main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - name: ruff check
+        run: ruff check .
+      - name: ruff format --check
+        run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: islavutin-oss/agentino
+          ref: ${{ env.AGENTINO_REF }}
+          path: _agentino
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          # Install through the package's own metadata, not a hand-kept list.
+          # A hand-kept list makes CI green while `pip install runspace` is
+          # broken, which is exactly how two missing core dependencies once
+          # went unnoticed. Every extra except [agentino] is installed from
+          # pyproject; the runtime comes from the checkout beside us because
+          # it is not on PyPI during CI.
+          # The document tools live in agentino's [docgen] extra.
+          pip install "./_agentino[docgen]"
+          pip install -e ".[redis,server,supabase,workspace,documents,scheduler,crawler,dev]"
+          pip install pytest-timeout
+      # testpaths in pyproject covers every test location, so one run is the
+      # whole suite. It used to be two commands and the second was easy to
+      # skip, which let a broken console-script entry point sit unnoticed.
+      - name: pytest
+        env:
+          PYTHONPATH: "src"
+        run: pytest -q
+      - name: sandbox_lint self-test
+        env:
+          PYTHONPATH: "src"
+        run: python -m runspace.protocols.sandbox_lint .
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - name: Build the distribution
+        run: python -m build
+      - name: Check the distribution metadata
+        run: twine check dist/*
+
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Frontend unit tests
+        run: |
+          node --experimental-strip-types workspace/frontend/shared/utils/loosePayload.test.mjs
+          node --experimental-strip-types --test workspace/frontend/shared/utils/describeSchedule.test.mjs
+
+  installable:
+    # Guards the one thing the test suite cannot see: that the built
+    # distribution is usable by someone who runs `pip install runspace`
+    # with nothing else present.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - name: Build the wheel
+        run: python -m build --wheel --outdir dist
+      - name: Install it into an empty environment
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install dist/*.whl
+      - name: Import it with no agent runtime installed
+        run: |
+          cd /tmp
+          /tmp/clean/bin/python -c "
+          import runspace, runspace.contracts, runspace.protocols
+          try:
+              import agentino
+              raise SystemExit('agentino must not be a core dependency')
+          except ImportError:
+              pass
+          from runspace.protocols import get_store, get_vision, get_transport
+          print(type(get_store()).__name__, type(get_vision()).__name__, type(get_transport()).__name__)
+          "

runspace-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+__pycache__/
+*.pyc
+.env
+node_modules/
+.pytest_cache/
+
+# Runtime artifacts
+sessions/
+sessions.jsonl
+usage.jsonl
+.agentino/
+.docs/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+*.so
+*.c
+!setup.c
+agentino_pkg/
+
+# Large repos cloned by agents
+
+# Local scratch / experiments — not part of the shared package.
+_tmp/
+vscode-extension/
+
+# Tooling caches
+.venv/
+.ruff_cache/
+.hypothesis/
+.runspace/

runspace-0.2.0/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims
+to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from 1.0
+onward.
+
+## [Unreleased]
+
+### Added
+
+- A SQLite messaging backend, now the default. Channels, threads, direct
+  messages and read state previously required `SUPABASE_URL` and
+  `SUPABASE_KEY`: without them `MessagingService` was never constructed, every
+  channel route returned 404 and nothing persisted. Since channels are the
+  workspace's main surface, a fresh install looked broken rather than
+  unconfigured. Supabase is still used when it is configured.
+- `InsightCard` reports a payload that parsed but is not an insight, naming
+  the keys it did receive. It previously rendered an empty card, which reads
+  as a layout bug rather than a malformed block.
+
+- Apache-2.0 licence, `NOTICE`, contribution guide, security policy, code of
+  conduct, and issue and pull-request templates.
+- `response_filter` in `workspace.yml`: a dotted path to a callable the
+  application owns. Runspace resolves and calls it without knowing what it
+  checks.
+- `max_turns` as per-app configuration, defaulting to 10.
+- `gpt-5.4-codex` is the default model for the agent runtimes and vision.
+- `WorkspaceRegistry.mount(app)`: exposes every tenant's gateway routes on one
+  application, resolving the tenant per request. A single-tenant host could
+  already do `app.include_router(gateway.router)`; a multi-tenant one had no
+  supported way, so hosts hand-wrote a handful of routes and quietly exposed a
+  fraction of the surface — channels, messages, uploads, pairings and the
+  external-channel routes simply had no route at all. The documentation
+  described this method before it existed.
+- Built-in `gateway_status` and `schedule` settings widgets. Both types were
+  named in `SettingsPage`'s union from the start and neither had an
+  implementation, so a section declaring either rendered "Unknown widget
+  type". An application can still replace either by passing a widget of the
+  same name.
+- `examples/grid`: a complete workspace that runs on a free, keyless public API
+  the moment a model endpoint is configured. A test walks every shipped example
+  and checks the paths its config names exist, its runtime is one the registry
+  dispatches, and its README names the command that starts it.
+- Opening suggestions in `workspace.yml`, carried through `/config`, so a
+  dialog client shows the workspace's own questions rather than generic ones.
+- `py.typed`. Without it a type checker ignores every annotation in the
+  package, so a hundred annotated modules did nothing for a consumer.
+
+### Changed
+
+- **Breaking: one import root.** The packages moved under `src/runspace/`, so
+  everything is imported as `runspace.*`. The distribution previously installed
+  `contracts`, `protocols`, `workspace`, `ingestion`, `helpers` and
+  `runspace_cli` as top-level names, which would collide with a user's own
+  modules. Consumers update with:
+
+      from protocols import get_store        ->  from runspace.protocols import get_store
+      from workspace.backend import ...      ->  from runspace.workspace.backend import ...
+
+  No compatibility shim ships. Aliasing the old names in `sys.modules` made
+  submodule imports execute a second time under a second name, giving two
+  module objects with separate caches — a worse failure than an ImportError.
+
+  `workspace/frontend/` stays at the repository root: it is the `@runspace/ui`
+  npm package, not part of the Python tree.
+- Zero-configuration defaults. `STORE_BACKEND` defaults to `file` (rooted at
+  `./.runspace/store`), `VISION_BACKEND` to `fixture` and `TRANSPORT_BACKEND`
+  to `file`, so a fresh install runs with no environment set. Previously the
+  store defaulted to `supabase` and raised on import without credentials.
+  Deployments relying on the old defaults must set them explicitly.
+- Licence changed from MIT to Apache-2.0. The repository previously declared
+  MIT in metadata with no licence file present.
+- Environment variables are no longer named after particular deployments. The
+  embeddings and vision adapters read `EMBEDDINGS_*`, `AI_BASE_URL`,
+  `AI_API_KEY` and `VISION_API_KEY`.
+- CI runs `ruff`, covers Python 3.10 through 3.13, exercises all six test
+  directories rather than one, builds the distribution with a `twine`
+  metadata check, and runs the frontend parser tests.
+
+### Fixed
+
+- The distribution declared a dependency on `agentino`, which on PyPI is an
+  unrelated project. Neither package is published to PyPI; install is from git. The agent runtime is now the `[agentino]` extra, pulling
+  `agentino-framework` — Runspace routes each turn to whichever runtime an app
+  declares and requires none of them, so it does not belong in the core
+  requirements.
+- `pip install runspace` produced an install that could not be imported:
+  `contracts.scheduling` needs `croniter` and `protocols.config` needs
+  `pydantic-settings`, both of which had been arriving transitively through
+  agentino. Both are now declared. Verified by installing the wheel into an
+  empty virtualenv with no agent runtime present.
+
+- `gateway.py` used `Any` in six annotations without importing it, which
+  raises under `typing.get_type_hints()`.
+- The multi-tenant isolation property tests shared a single store across every
+  hypothesis example. Rows accumulated, so a tenant id generated as `tenant_a`
+  in one example could reappear as `tenant_b` in a later one and read as a
+  leak. Each example now builds its own store.
+- `tests/test_telegram_render.py` imported a package path that never resolved,
+  so the module could not be collected at all.
+- A test fixture repeated the `token` key in one dictionary literal.
+- A test drove its coroutines through `asyncio.get_event_loop()`, which on
+  Python 3.12 only works when an earlier test left a loop on the thread, so it
+  passed or failed depending on collection order.
+- The `[supabase]` extra was documented but never declared, and `[documents]`
+  omitted pymupdf, which the scanned-PDF path imports.
+- The widget-integrity regex covered `chart`, `datatable` and `kpi` but not
+  `insight`, which the frontend also renders. An insight block the model
+  mangled was never spliced back over — the canonical copy was appended at
+  the end instead, so the page showed a parse error above the real card.
+- Seventeen test modules computed a `sys.path` entry from `parents[N]`. The
+  indices were wrong after the move, and one of them put `src/runspace` on the
+  path, making every subpackage importable a second time as a top-level name.
+  Path setup now lives once in the root `conftest.py`.
+- The agent answered twice in a channel. Posting to `/channels/{slug}/messages`
+  dispatches `@mentions`, and the channel UI also streams its own turn, so once
+  the channel routes were reachable every mention produced two model calls and
+  two stored replies. The POST now honours `dispatch=false`.
+- `runspace init` produced a workspace that would not boot. The generated
+  config named `tenants.<id>.plugins.health`, which is not an importable module
+  path when the id contains a hyphen and assumed a working directory the
+  printed instructions do not use. The prompts also raised an unhandled
+  `EOFError` when stdin was not a tty, so the command died half-scaffolded in
+  CI or a Dockerfile.
+- The `sandbox_lint` CI step ran `python -m protocols.sandbox_lint`, a module
+  path the rename removed, so that job could never have passed.
+- The documented development setup produced a checkout whose tests could not
+  collect, and `[dev]` named a package that is not on PyPI, so the obvious
+  correction failed outright.
+- Eight tests silently skipped because they looked for the frontend inside the
+  Python package and named a layer that had been renamed. Two layering rules
+  ran green while checking a directory that no longer existed, so a shared
+  component importing from `team/` passed the rule forbidding exactly that.
+- Twenty file paths named in the documentation pointed at files that are not
+  in the repository, including a package renamed two versions ago.
+- Tests shared one storage root and one adapter registry, so state leaked
+  between them. An autouse fixture now gives each test its own roots and
+  resets the cached adapters.
+
+### Removed
+
+- The `packages/` split distributions. `packages/runspace` claimed the same
+  PyPI name as the repository root with an older version and a subset of the
+  code, so only one of them could ever own that name. Both also produced
+  broken source distributions: their `force-include` pointed at `../../src`,
+  which does not exist inside an extracted sdist, so a source install failed
+  to build a wheel. The root distribution supersedes both.
+
+- Product-specific policy from the shared runtime: hardcoded nudge strings in
+  one natural language, refusal markers, a datatable row cap naming one
+  application's chart tools, and a fixed `max_turns=25` applied to every app.
+- Internal planning documents that tracked a migration through internal
+  phases and named host paths, ticket numbers and unshipped projects.
+- Twelve test guards that read a directory which had moved to
+  `agentino.tools.std`. The equivalent guards now live in that repository.

runspace-0.2.0/CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md — Runspace
+
+Notes for coding agents (and humans) working in this repository.
+
+## What this is
+
+A workspace runtime for agents: a FastAPI gateway, an app registry, chat with
+streaming and attachments, external channels, scheduled routines, and a React
+frontend. It is runtime-agnostic by construction — the agentino adapter is one
+runtime among several, and `app_registry.py` contains no `from agentino`
+imports.
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[workspace]"
+pip install pytest pytest-asyncio hypothesis ruff
+```
+
+Agentino is an optional extra, not a dependency — `pip install -e ".[agentino]"`
+if you want the in-process runtime. The test suite exercises it, so install it
+for development.
+
+## Commands
+
+```bash
+PYTHONPATH=src pytest -q                                            # default paths
+PYTHONPATH=src pytest src/runspace/contracts src/runspace/protocols \
+    src/runspace/workspace/cli/tests scripts/tests -q
+node --experimental-strip-types workspace/frontend/shared/utils/loosePayload.test.mjs
+
+ruff check .            # must be clean
+ruff format --check .   # must be clean
+PYTHONPATH=src python -m runspace.protocols.sandbox_lint <dir>   # flag banned imports in agent tools
+```
+
+CI runs all of these.
+
+## Layout
+
+```
+runspace/
+├── src/runspace/            one import root — everything ships as runspace.*
+│   ├── contracts/           wire shapes — chat, runtime, tool, workspace.yml
+│   ├── protocols/           swappable adapters behind Protocols:
+│   │                        store, vision, transport, file_storage, embeddings,
+│   │                        transcriber, clock, prompt flattening
+│   ├── workspace/backend/   gateway (FastAPI routes), app_registry, runtimes/,
+│   │                        messaging, routines, attachments, runners, scoring
+│   ├── ingestion/           inbound channels — Telegram polling, pairing
+│   ├── helpers/             session, messaging and document utilities
+│   └── runspace_cli/        the `runspace` console entry point
+├── workspace/frontend/      React components published as @runspace/ui — an npm
+│                            package, deliberately outside the Python tree
+└── templates/               workspace.yml.example
+```
+
+## Conventions that matter here
+
+- **No application logic.** This is a shared layer. Tenant behaviour comes
+  from configuration — `workspace.yml`, `routines.yml`, `SOUL.md` — never from
+  a branch in Python. That includes prompt wording, retry thresholds, tool
+  names and natural language. Where an application needs to influence
+  behaviour, give it a seam: `response_filter` names a callable the app owns,
+  and runspace calls it without knowing what it checks.
+- **No hardcoded prompts.** Agent instructions live in `SOUL.md`. Frontend
+  rendering rules live in a partial the SOUL includes, not in a Python
+  constant.
+- **No deployment-specific environment variables.** The public names are
+  `AI_BASE_URL` / `AI_API_KEY`, `EMBEDDINGS_*` and `VISION_API_KEY`. Use
+  `${VAR:-default}` in YAML; `_resolve_env_vars` expands it at load time.
+- **Runtime-agnostic by construction.** Only
+  `src/runspace/workspace/backend/runtimes/agentino.py` imports agentino, and it is one of
+  five adapters — `codex`, `claude_code`, `pi` and `openclaw` shell out to a
+  CLI instead. `app_registry.py` dispatches on `app.type` and imports none of
+  them eagerly. A sixth drops in beside them.
+- **One source of truth for prompts.** `protocols.prompt.flatten_soul` is what
+  every caller uses to produce a flattened SOUL, so they cannot drift.
+- **Property tests build their own fixtures.** `@given` runs many examples
+  against one function-scoped fixture, so shared mutable state leaks between
+  examples and looks like a bug in the code under test. Hand back a factory.

runspace-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Code of Conduct
+
+## Our pledge
+
+We want participation in this project to be a harassment-free experience for
+everyone, whatever their age, body size, disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our standards
+
+Things that help:
+
+- being welcoming and respectful of differing viewpoints
+- accepting constructive criticism gracefully
+- focusing on what is best for the project
+- showing empathy toward other people
+
+Things that are not acceptable:
+
+- sexualised language or imagery, and unwelcome sexual attention
+- trolling, insults, derogatory comments, and personal or political attacks
+- public or private harassment
+- publishing someone's private information without explicit permission
+
+## Enforcement
+
+Report unacceptable behaviour by contacting the maintainer,
+[@islavutin-oss](https://github.com/islavutin-oss), through a GitHub private message
+or a private security advisory on this repository. All reports are reviewed
+and investigated, and will be kept confidential.
+
+Maintainers may remove comments, commits, code, issues and other
+contributions that violate this Code of Conduct, and may ban contributors
+temporarily or permanently for behaviour they judge inappropriate,
+threatening, offensive or harmful.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 1.4.

runspace-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to Runspace
+
+Thanks for taking the time. This is a small project, so the process is short.
+
+## Before you start
+
+For anything beyond a bug fix or a typo, **open an issue first**. It is much
+less painful to disagree about an approach in an issue than in a finished
+pull request.
+
+## Getting set up
+
+```bash
+git clone https://github.com/islavutin-oss/runspace.git
+cd runspace
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Run the tests and the linter:
+
+```bash
+PYTHONPATH=src pytest -q
+ruff check .
+ruff format --check .
+```
+
+CI runs exactly these, on Python 3.10 through 3.13.
+
+## What a good pull request looks like
+
+- **One change per pull request.** Unrelated fixes bundled together are hard
+  to review and harder to revert.
+- **Tests come with the change.** A bug fix should include a test that fails
+  before it and passes after.
+- **The suite is green.** Not "green except for a flaky one" — if something
+  is flaky, that is worth an issue of its own.
+- **Commit messages say what changed and why.** The subject line is
+  imperative and under about 72 characters; the body explains the reasoning
+  a reviewer cannot get from the diff.
+
+We use [Conventional Commits](https://www.conventionalcommits.org) prefixes:
+`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`, `ci:`.
+
+## Style
+
+The linter settles formatting arguments, so there is nothing to debate:
+`ruff format` owns line width, `ruff check` owns the rest. Type hints on
+public functions. Comments should explain why something is the way it is —
+the code already says what it does.
+
+## Licensing
+
+Contributions are accepted under the [Apache License 2.0](LICENSE), the same
+licence the project ships under. There is no CLA.