mirror of
https://github.com/turnstonelabs/turnstone.git
synced 2026-08-13 07:22:24 -06:00
Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Patrick Buckley
|
ee94ae8ba1 |
@@ -42,9 +42,6 @@
|
||||
# CONSOLE_HTTPS_PORT=8443 # Caddy (dashboard HTTPS)
|
||||
# POSTGRES_PORT=5432 # exposed for bare-metal host joins
|
||||
# POSTGRES_BIND=127.0.0.1 # set 0.0.0.0 to let another machine join
|
||||
# TURNSTONE_HOST_IP=127.0.0.1 # dev-stack bind address for cross-host joins
|
||||
# TURNSTONE_CONSOLE_HTTP_BIND=127.0.0.1 # production TLS-overlay ACME/API bind
|
||||
# TURNSTONE_ACME_EXTERNAL_URL=http://192.0.2.1:8090/acme # routable ACME base; bracket IPv6; include /acme
|
||||
|
||||
# -- Workspace ----------------------------------------------------------------
|
||||
# Bind-mount a host directory the model can read/write at /workspace:
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
# Funding platforms for the GitHub "Sponsor" button.
|
||||
# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
|
||||
|
||||
github: [eous]
|
||||
custom: ["https://paypal.me/eousphoros"]
|
||||
@@ -55,7 +55,7 @@
|
||||
{
|
||||
"description": "LLM SDKs — always review manually",
|
||||
"groupName": "LLM SDKs",
|
||||
"matchPackageNames": ["openai", "httpx2", "anthropic", "mcp"],
|
||||
"matchPackageNames": ["openai", "anthropic", "mcp"],
|
||||
"schedule": ["before 9am on Monday"],
|
||||
"automerge": false
|
||||
},
|
||||
|
||||
+25
-27
@@ -14,8 +14,8 @@ jobs:
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
||||
with:
|
||||
python-version: "3.14"
|
||||
- run: pip install pre-commit
|
||||
@@ -25,8 +25,8 @@ jobs:
|
||||
typecheck:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
||||
with:
|
||||
python-version: "3.14"
|
||||
- run: pip install mypy
|
||||
@@ -35,31 +35,29 @@ jobs:
|
||||
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
# Cap a hung run at 30 min instead of riding GitHub's 6-hour default
|
||||
# (a flaky-hang run otherwise streams -v output for hours). Was 20;
|
||||
# the suite's growth (~9.7k tests, coverage-instrumented, 3-version
|
||||
# matrix) started brushing the old cap on healthy runs.
|
||||
timeout-minutes: 30
|
||||
# Cap a hung run at 20 min instead of riding GitHub's 6-hour default
|
||||
# (a flaky-hang run otherwise streams -v output for hours).
|
||||
timeout-minutes: 20
|
||||
strategy:
|
||||
matrix:
|
||||
python-version: ["3.11", "3.12", "3.13"]
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
||||
with:
|
||||
python-version: ${{ matrix.python-version }}
|
||||
# Node is required by tests/test_renderer_js.py — without
|
||||
# explicit setup, that suite silently skips if the runner
|
||||
# image happens not to ship Node, masking regressions in
|
||||
# the browser-side renderer.
|
||||
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
|
||||
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
|
||||
with:
|
||||
node-version: "24"
|
||||
- run: pip install -e ".[test]"
|
||||
# -v lists each test id as it starts (pytest prints the nodeid at
|
||||
# logstart), so a hang names the culprit on the last line instead of
|
||||
# riding the job timeout with only a trail of "..." dots.
|
||||
- run: pytest tests/ -m "not live and not e2e_recovery" --cov=turnstone --cov-report=term-missing --cov-report=xml -v
|
||||
- run: pytest tests/ -m "not live" --cov=turnstone --cov-report=term-missing --cov-report=xml -v
|
||||
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
|
||||
if: always()
|
||||
with:
|
||||
@@ -68,7 +66,7 @@ jobs:
|
||||
|
||||
test-postgres:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
timeout-minutes: 20
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:18
|
||||
@@ -84,23 +82,23 @@ jobs:
|
||||
--health-timeout=5s
|
||||
--health-retries=5
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
||||
with:
|
||||
python-version: "3.14"
|
||||
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
|
||||
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
|
||||
with:
|
||||
node-version: "24"
|
||||
- run: pip install -e ".[test]"
|
||||
- run: pytest tests/ -m "not live and not e2e_recovery" --storage-backend=postgresql -v
|
||||
- run: pytest tests/ -m "not live" --storage-backend=postgresql -v
|
||||
env:
|
||||
TURNSTONE_TEST_PG_URL: postgresql+psycopg://postgres:postgres@localhost:5432/turnstone_test
|
||||
|
||||
wheel-completeness:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
||||
with:
|
||||
python-version: "3.14"
|
||||
- run: pip install build
|
||||
@@ -153,8 +151,8 @@ jobs:
|
||||
lock-check:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
- uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
|
||||
with:
|
||||
uv-version: "0.9.18"
|
||||
- run: uv lock --check
|
||||
@@ -162,11 +160,11 @@ jobs:
|
||||
security:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
- uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
|
||||
with:
|
||||
uv-version: "0.9.18"
|
||||
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
|
||||
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
||||
with:
|
||||
python-version: "3.14"
|
||||
- run: uv sync --frozen --all-extras
|
||||
@@ -190,8 +188,8 @@ jobs:
|
||||
run:
|
||||
working-directory: sdk/typescript
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
|
||||
with:
|
||||
node-version: "24"
|
||||
- run: npm ci
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
name: Claude Code Review
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize, ready_for_review, reopened]
|
||||
# Optional: Only run on specific file changes
|
||||
# paths:
|
||||
# - "src/**/*.ts"
|
||||
# - "src/**/*.tsx"
|
||||
# - "src/**/*.js"
|
||||
# - "src/**/*.jsx"
|
||||
|
||||
jobs:
|
||||
claude-review:
|
||||
if: github.event.pull_request.head.repo.full_name == github.repository
|
||||
# Optional: Filter by PR author
|
||||
# if: |
|
||||
# github.event.pull_request.user.login == 'external-contributor' ||
|
||||
# github.event.pull_request.user.login == 'new-developer' ||
|
||||
# github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write # post the review + inline comments
|
||||
issues: read
|
||||
id-token: write
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
with:
|
||||
fetch-depth: 1
|
||||
|
||||
- name: Run Claude Code Review
|
||||
id: claude-review
|
||||
uses: anthropics/claude-code-action@01872ccc02bf66740207fb338a783ce028216758 # v1
|
||||
with:
|
||||
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
|
||||
allowed_bots: 'renovate[bot]' # let Renovate PRs get reviewed
|
||||
plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
|
||||
plugins: 'code-review@claude-code-plugins'
|
||||
prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
|
||||
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
|
||||
# or https://code.claude.com/docs/en/cli-reference for available options
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
name: Claude Code
|
||||
|
||||
on:
|
||||
issue_comment:
|
||||
types: [created]
|
||||
pull_request_review_comment:
|
||||
types: [created]
|
||||
issues:
|
||||
types: [opened, assigned]
|
||||
pull_request_review:
|
||||
types: [submitted]
|
||||
|
||||
jobs:
|
||||
claude:
|
||||
if: |
|
||||
(
|
||||
github.event_name == 'issue_comment' &&
|
||||
contains(github.event.comment.body, '@claude') &&
|
||||
contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
|
||||
) || (
|
||||
github.event_name == 'pull_request_review_comment' &&
|
||||
contains(github.event.comment.body, '@claude') &&
|
||||
contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
|
||||
) || (
|
||||
github.event_name == 'pull_request_review' &&
|
||||
contains(github.event.review.body, '@claude') &&
|
||||
contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.review.author_association)
|
||||
) || (
|
||||
github.event_name == 'issues' &&
|
||||
(contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')) &&
|
||||
contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association)
|
||||
)
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write # post comments/reviews when @-mentioned on a PR
|
||||
issues: write # post comments when @-mentioned on an issue
|
||||
id-token: write
|
||||
actions: read # Required for Claude to read CI results on PRs
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
with:
|
||||
fetch-depth: 1
|
||||
|
||||
- name: Run Claude Code
|
||||
id: claude
|
||||
uses: anthropics/claude-code-action@01872ccc02bf66740207fb338a783ce028216758 # v1
|
||||
with:
|
||||
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
|
||||
|
||||
# This is an optional setting that allows Claude to read CI results on PRs
|
||||
additional_permissions: |
|
||||
actions: read
|
||||
|
||||
# Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
|
||||
# prompt: 'Update the pull request description to include a summary of changes.'
|
||||
|
||||
# Optional: Add claude_args to customize behavior and configuration
|
||||
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
|
||||
# or https://code.claude.com/docs/en/cli-reference for available options
|
||||
# claude_args: '--allowed-tools Bash(gh pr *)'
|
||||
|
||||
@@ -33,7 +33,7 @@ jobs:
|
||||
startsWith(github.event.workflow_run.head_branch, 'v')
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
with:
|
||||
ref: ${{ github.event.workflow_run.head_sha }}
|
||||
fetch-depth: 0
|
||||
@@ -54,7 +54,7 @@ jobs:
|
||||
|
||||
- name: Log in to GHCR
|
||||
if: steps.tag.outputs.skip == 'false'
|
||||
uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
|
||||
uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4
|
||||
with:
|
||||
registry: ${{ env.REGISTRY }}
|
||||
username: ${{ github.actor }}
|
||||
|
||||
@@ -30,7 +30,7 @@ jobs:
|
||||
runs-on: ubuntu-latest
|
||||
environment: pypi
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
with:
|
||||
ref: ${{ github.event.workflow_run.head_sha }}
|
||||
fetch-depth: 0
|
||||
@@ -50,7 +50,7 @@ jobs:
|
||||
echo "skip=false" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
|
||||
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
||||
if: steps.tag.outputs.skip == 'false'
|
||||
with:
|
||||
python-version: "3.14"
|
||||
@@ -58,12 +58,12 @@ jobs:
|
||||
if: steps.tag.outputs.skip == 'false'
|
||||
- run: python -m build
|
||||
if: steps.tag.outputs.skip == 'false'
|
||||
- uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
|
||||
- uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
|
||||
if: steps.tag.outputs.skip == 'false'
|
||||
|
||||
- name: Create GitHub Release
|
||||
if: steps.tag.outputs.skip == 'false'
|
||||
uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3
|
||||
uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3
|
||||
with:
|
||||
tag_name: ${{ steps.tag.outputs.tag }}
|
||||
generate_release_notes: true
|
||||
|
||||
@@ -31,8 +31,8 @@ jobs:
|
||||
# Floor and ceiling of the example's requires-python (>=3.11).
|
||||
python-version: ["3.11", "3.13"]
|
||||
steps:
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
||||
with:
|
||||
python-version: ${{ matrix.python-version }}
|
||||
- run: pip install -e ".[test,dev]"
|
||||
|
||||
@@ -61,7 +61,7 @@ jobs:
|
||||
fi
|
||||
echo "head_ref=${ref}" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
|
||||
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
||||
with:
|
||||
ref: ${{ steps.ref.outputs.head_ref }}
|
||||
|
||||
|
||||
@@ -19,8 +19,6 @@ docker-compose.override.yml
|
||||
.ruff_cache/
|
||||
.pytest_cache/
|
||||
*.db
|
||||
*.db-shm
|
||||
*.db-wal
|
||||
.plan.md
|
||||
.plan-*.md
|
||||
.hypothesis/
|
||||
@@ -31,4 +29,3 @@ tools/skill_audit_analysis/output/
|
||||
design_ideas/
|
||||
.claude/
|
||||
docs/design/
|
||||
/.idea
|
||||
|
||||
+4
-744
@@ -6,753 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [PEP 440](https://peps.python.org/pep-0440/) for
|
||||
version numbers (`X.Y.Z`, with `X.Y.ZaN` / `bN` / `rcN` for pre-releases).
|
||||
|
||||
Two active release tracks are maintained — the current stable and the
|
||||
experimental line:
|
||||
Three release tracks are maintained — the current stable, one prior
|
||||
stable, and the experimental line:
|
||||
|
||||
- **`stable/1.7`** — patch-only (`v1.7.x`)
|
||||
- **`stable/1.5`** — patch-only (`v1.5.x`)
|
||||
- **`stable/1.6`** — patch-only (`v1.6.x`)
|
||||
- **`main`** — experimental (next major)
|
||||
|
||||
Earlier stable lines (`stable/1.6`, `stable/1.5`) are frozen.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
|
||||
- **Large plain-text pastes become attachments.** Pasting text longer than the
|
||||
fixed 2,000-character threshold stages `pasted-text.txt` across all five
|
||||
attachment-capable create/send composers. Clipboard files retain priority,
|
||||
text above the 512 KiB upload ceiling stays inline, identical synthesized
|
||||
pastes collapse to one chip, and rejected attachment sends keep the staged
|
||||
message and files so they can be corrected or retried.
|
||||
- **`server_parses_reasoning` model capability.** Declare it on a model
|
||||
definition whose backend segregates reasoning into its own channel (a
|
||||
vLLM launched with a reasoning parser, a commercial provider): the
|
||||
inline think-tag scan turns off on every lane — interactive and
|
||||
drained alike — so content is trusted verbatim and prose that merely
|
||||
quotes a tag can no longer be misrouted into the reasoning lane, and
|
||||
the utility lanes stop suppressing reasoning they'd otherwise pin off.
|
||||
Default off for local lanes, preserving the passthrough-server
|
||||
behavior; the built-in capability tables declare it for every real
|
||||
commercial endpoint (known models and table-miss defaults alike),
|
||||
which also removes the quoted-tag false positive from those lanes.
|
||||
- **Per-model Entra gateway authentication.** Model definitions can bind either
|
||||
a caller-delegated OBO token (`entra_obo`) or a shared app-identity token
|
||||
(`entra_app`) through the provider SDK credential surface. Mints reuse the
|
||||
encrypted cluster token cache, refresh-rotation CAS, and advisory locking;
|
||||
add a host-local memo, failure cooldown, long-lived mint HTTP client, audience
|
||||
allow-list/permission boundary, identity-unlink purge, and optional
|
||||
`model.auth_fail_closed` refusal policy. Delegated identity now propagates
|
||||
through judge, output-guard, and principal-scoped perception lanes, and
|
||||
unattended watch restoration reacquires the persisted workstream owner.
|
||||
Ownerless OBO calls and dynamic aliases without a real static fallback always
|
||||
fail closed; grant modes are never silently switched. Static authentication
|
||||
remains the default.
|
||||
|
||||
- **Compaction is visible now: lifecycle events, a progress bar, and a
|
||||
persistent transcript card.** Context compaction (manual `/compact` and
|
||||
auto) emits a first-class `compaction` SSE event
|
||||
(`start` / `progress` / `end` — see the API reference) instead of loose
|
||||
info lines. The web UI renders an in-transcript card with a real progress
|
||||
bar (determinate `part k of N` during chunked summarization, indeterminate
|
||||
for single-call compactions) that settles into a result card — token delta
|
||||
plus the summary behind a fold — in both the interactive pane and the
|
||||
coordinator viewer. The result survives reloads: the persisted compaction
|
||||
marker now projects through `/history` as a `role="system"`,
|
||||
`source="compaction"` entry (resume/export/search unchanged), stamped with
|
||||
the end event's id so repaint and SSE replay can't double-render. The
|
||||
marker's `meta` additionally records `before_tokens` / `after_tokens` /
|
||||
`trigger`. Python and TypeScript SDKs gain a typed `CompactionEvent`.
|
||||
|
||||
- **One provider transport: every model call now streams (#831).**
|
||||
The per-adapter non-streaming entry (`create_completion`) is retired;
|
||||
single-shot lanes — judges, titles, compaction, web-fetch extraction,
|
||||
perception, eval, optimizer — sample through the same streaming entry
|
||||
the chat loop uses and accumulate via one shared drain, so request
|
||||
shaping can no longer drift between the two consumption styles. Two
|
||||
operator-visible consequences: long single-shot generations (a thinking
|
||||
model composing a title, a slow local judge) no longer sit in a single
|
||||
blocking read that can hit client read-timeouts — the same reason the
|
||||
Anthropic adapter already streamed internally — and judge timeouts now
|
||||
*abort* the underlying HTTP read instead of abandoning a worker thread
|
||||
on a dead call. Because every call now streams, an alias pointed at a
|
||||
model or org that cannot stream (OpenAI's verified-org streaming
|
||||
entitlement, a gateway api-version predating `stream_options` — e.g.
|
||||
older Azure OpenAI deployments) fails at request time where 1.7's
|
||||
non-streaming single-shot call succeeded; remediation is on the
|
||||
serving side (verify the org, bump the api-version/gateway) — there is
|
||||
deliberately no per-model non-streaming fallback left to configure. These lanes are also complete-or-error now: a stream
|
||||
that ends without any finish signal is treated as a generation that
|
||||
died mid-response and retried, instead of storing the partial text as
|
||||
a clean result (previously a half-generated compaction summary could
|
||||
silently replace real history). Caveats: these lanes now carry the
|
||||
same `stream_options: {include_usage: true}` the chat loop always
|
||||
sent — OpenAI-compatible servers old enough to *ignore* it stop
|
||||
producing usage rows on these lanes, and servers strict enough to
|
||||
*reject* unknown fields (pre-2024 llama.cpp/proxy builds) will 400 —
|
||||
such a server already couldn't serve turnstone's chat loop, but a
|
||||
judge/utility alias pointed at one worked on 1.7 and needs to move to
|
||||
a current server. Transient mid-stream deaths (connection drop, proxy
|
||||
hiccup) are re-issued in place up to twice with exponential backoff —
|
||||
the retry the SDK's request loop used to provide these lanes
|
||||
invisibly. Each lane accepts its own terminal marker (Anthropic
|
||||
`message_stop`, Responses terminal events); a lax server/gateway that
|
||||
never sends any terminal signal needs
|
||||
`{"finish_reason_optional": true}` in the model definition's
|
||||
capabilities JSON, which restores 1.7's tolerance (clean end-of-stream
|
||||
after output = completion) for that model on every lane — without it
|
||||
such streams fail as died-mid-generation, because SSE gives no way to
|
||||
tell the two apart and the default favors catching truncation. The
|
||||
unread `supports_streaming` capability flag (and its admin tile) is
|
||||
gone; the o-series models it described are dropped from the capability
|
||||
table entirely (see Removed).
|
||||
|
||||
- **One turn interface for every model call: `core/model_turn.py` (#827).**
|
||||
Judges (intent + output guard), perception, title generation, compaction,
|
||||
web-fetch extraction, the eval harness, the optimizer's meta lanes, and
|
||||
task agents all advance a trajectory through the same plant-call
|
||||
primitive the agent seam pioneered — Turn IR in, one shared lowering
|
||||
(argument sanitize → minted-id restore → vLLM reasoning attach), one
|
||||
shared re-ingest (blank-id repair → native-lane finalize). The judges'
|
||||
hand-built OpenAI-dict path is gone, and with it the Gemini judge's
|
||||
tool-blindness: evidence tools now work on Google models because the
|
||||
native lane round-trips `thought_signature` (with pairwise repair for
|
||||
blank-id compat responses). Provider adapters still take lowered wire
|
||||
dicts — the transport collapse and main-loop migration are tracked as
|
||||
#831 / #832.
|
||||
|
||||
- **task_agent keeps its model's reasoning across its own tool loop — on
|
||||
every provider lane.** A task agent's replayed turns now carry the
|
||||
provider-native reasoning lane the model produced — Anthropic thinking
|
||||
blocks with their signatures (commercial or an anthropic-compatible
|
||||
server), OpenAI Responses reasoning items, Gemini `thought_signature`
|
||||
fidelity blocks, and the reasoning text a vLLM `--reasoning-parser` /
|
||||
llama.cpp `reasoning_format` surfaces on the Chat Completions lane —
|
||||
instead of each turn being rebuilt from text + tool calls with the
|
||||
reasoning dropped. On a thinking model this restores reasoning continuity
|
||||
across the agent's own multi-turn tool use. On the wire the agent's
|
||||
session-minted sub-tool ids are mapped back to the provider's own ids
|
||||
(`restore_provider_tool_ids`), so the native block — replayed verbatim,
|
||||
its signature never touched — the `tool_calls` mirror, and each tool
|
||||
result always agree; internally the minted ids still key the live card,
|
||||
recall, and the cancel ledger unchanged. Replay honors the same per-model
|
||||
`replay_reasoning_to_model` flag the main loop uses on every lane: the
|
||||
vLLM Chat-Completions field replay keeps its server-type gate, and
|
||||
llama.cpp stays capture-only, matching main-loop behavior. The native
|
||||
lane is finalized by the same shared builder as the main loop's, so the
|
||||
two harnesses cannot drift.
|
||||
|
||||
- **Background shells: `bash` gains `run_in_background`, plus `bash_output` /
|
||||
`kill_shell`.** Setting `run_in_background=true` starts the command as a
|
||||
detached shell and returns immediately with a `bash_N` handle — "start a dev
|
||||
server, use it in a later call" is back as an explicit opt-in (the shape
|
||||
follows the convention the major coding agents converged on). `bash_output`
|
||||
returns only output produced since the previous read (optionally filtered by
|
||||
a regex) plus status and exit code; `kill_shell` terminates the shell's
|
||||
whole process group. Output is buffered per shell with a drop-oldest cap, so
|
||||
a chatty server can't grow memory unbounded. When a background shell exits,
|
||||
a system notice lands at the next seam (waking an idle workstream if
|
||||
needed). Shells survive a generation cancel, die with the workstream, and
|
||||
never outlive a task_agent that started them; anything a background shell
|
||||
itself backgrounds is still reaped when that shell exits — the no-leak
|
||||
guarantee below is unchanged.
|
||||
|
||||
### Changed
|
||||
|
||||
- **lacme 1.2.0 and HTTPX2 now back the core mTLS path.** TLS/ACME is a typed
|
||||
core dependency rather than optional-import-era code; renewal and admin
|
||||
clients use lacme's public close/stop lifecycle. Consoles can set
|
||||
`TURNSTONE_ACME_EXTERNAL_URL` to a routable responder base ending in `/acme`,
|
||||
so nodes on another host receive usable directory and follow-up URLs during
|
||||
enrollment. Signing routes now require a dedicated, purpose-confined rotating
|
||||
service JWT, and HTTPX2 pins that credential to canonical resources on
|
||||
configured responder origins. Internal and external console identities use
|
||||
separate persistence namespaces; cluster identities are reused only after
|
||||
key, SAN, validity, EKU, and active-root verification. Responder-side keyless
|
||||
CSR results cannot overwrite managed identities, failed live reloads restore
|
||||
the last usable bundle, certificate lifetime stays at 48 hours with a
|
||||
12-hour renewal cadence, and cancellation drains renewal clients before
|
||||
propagating. Operator-supplied IPv4 and IPv6 literals are passed to lacme as
|
||||
typed IP identifiers and issued as IP SANs; unexpired legacy certificates
|
||||
containing `DNS:<ip>` are reissued instead of being reused as an invalid IP
|
||||
identity
|
||||
([#1011](https://github.com/turnstonelabs/turnstone/issues/1011)).
|
||||
|
||||
- **OpenAI SDK v3 and its HTTPX2 default transport are now supported (#1009).**
|
||||
Chat Completions and Responses streams normalize native HTTPX2 connection
|
||||
deaths through the same retry boundary as legacy HTTPX-backed providers,
|
||||
including failures observed after safe cross-thread client closure during a
|
||||
model-registry reload. The OpenAI v3 runtime escape hatch for explicitly
|
||||
injected legacy HTTPX clients remains supported. OpenAI connections now
|
||||
follow HTTPX2's operating-system trust store by default; deployments that
|
||||
relied on a modified `certifi` bundle must install that CA in the system
|
||||
store or set `SSL_CERT_FILE` / `SSL_CERT_DIR`.
|
||||
|
||||
- **Log event rename: `drain_stream.post_finish_blip` is now
|
||||
`stream.post_finish_blip`; its `usage_captured` field is retained.** The
|
||||
single-shot drain normalizes mid-body transport deaths through the same
|
||||
`transport_guarded` wrapper the interactive loop uses, so its
|
||||
post-finish-blip tolerance logs under the wrapper's event name. Update
|
||||
any external log filters pinned to the old name; the drained result's
|
||||
possible `usage=None` on a post-finish blip is unchanged and documented
|
||||
on `drain_stream`.
|
||||
|
||||
- **Breaking (1.8): compaction feedback moved from `info` events to the
|
||||
typed `compaction` SSE event.** Pre-1.8 SSE/SDK clients that ignore
|
||||
unknown event types no longer see compaction lines (they are
|
||||
deliberately not dual-emitted — dual emission would double-render on
|
||||
every current client). Consume the `compaction` lifecycle event (see
|
||||
the API reference and the `CompactionEvent` SDK type); embedders
|
||||
driving `ChatSession` through a duck-typed `SessionUI` are unaffected
|
||||
(the classic `on_info` lines are restored for them — see Fixed).
|
||||
|
||||
- **Sampling knobs (temperature, reasoning effort) now ride one assignment
|
||||
scheme: per-model alias value → operator-stored global setting → the
|
||||
model definition's declared default (effort only) → field omitted.**
|
||||
Turnstone previously manufactured values onto every unconfigured
|
||||
request — a hidden `temperature: 0.5` and a `reasoning_effort: "medium"`
|
||||
baked in at three layers — overriding serving-side defaults like a vLLM
|
||||
model's `generation_config`. Unconfigured installs now send neither
|
||||
field and the inference engine's own defaults rule; `model.temperature`
|
||||
is blank by default ("inherit each model's own default") and
|
||||
`model.reasoning_effort` defaults to the empty "inherit" choice. The
|
||||
per-model → global resolution lives in one shared resolver used by the
|
||||
session factories, the `/model` switch, and every `model_turn` lane, so
|
||||
the same alias samples identically on every surface. CLI
|
||||
`--temperature` / `--reasoning-effort` likewise default to inherit.
|
||||
|
||||
**Upgrade notes:**
|
||||
- The empty (`""`) reasoning-effort choice changed meaning from
|
||||
"explicitly disable thinking" to "inherit the model/serving default".
|
||||
On local manual-thinking models (e.g. Qwen templates with
|
||||
`enable_thinking`), a stored `""` previously sent
|
||||
`enable_thinking: false`; it now sends nothing, so the template's own
|
||||
default (often thinking ON) applies. Use **`none`** to actually
|
||||
disable reasoning.
|
||||
- Workstreams saved by earlier versions carry the old defaults
|
||||
(`temperature=0.5`, `reasoning_effort=medium`) in their persisted
|
||||
config and keep that exact behavior on resume; they pick up the new
|
||||
inherit semantics the next time you change the model or a sampling
|
||||
knob in that workstream. New workstreams inherit from the start.
|
||||
|
||||
### Removed
|
||||
|
||||
- **O-series and pre-5.4 GPT-5 rows dropped from the OpenAI capability
|
||||
table.** `o1`, `o1-mini`, `o3`, `o3-mini`, `o3-pro`, `o4-mini`,
|
||||
`gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-5-pro`, `gpt-5.1`,
|
||||
`gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.2-pro`, and `gpt-5.3` no longer
|
||||
have built-in capability rows — OpenAI has retired these model ids
|
||||
from the API, so the rows described contracts no request can reach
|
||||
anymore. The table floor is now `gpt-5.4`; the search-api and
|
||||
audio/STT/TTS rows are unchanged. An alias still pinning a retired id
|
||||
fails at OpenAI itself; any other unlisted commercial id resolves to
|
||||
the generic commercial defaults (temperature sent, no declared
|
||||
reasoning-effort vocabulary, 200K window) — declare the contract on
|
||||
the model definition's capabilities JSON if you run one, or move to a
|
||||
current model.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **MCP servers may expose resources without resource templates, or templates
|
||||
without concrete resources (#993).** The MCP handshake has one aggregate
|
||||
`resources` capability, but implementations are not required to support both
|
||||
list methods. An exact JSON-RPC `Method not found` response from either
|
||||
method is now treated as an empty half-catalog during static and per-user
|
||||
discovery and refresh, while every other error still fails closed. A failed
|
||||
static registration also tears down its transport and publishes none of its
|
||||
staged tools/resources/prompts, eliminating the live callable “ghost” tools
|
||||
that could remain after the UI reported registration failure.
|
||||
|
||||
- **A cancelled judge, guard, or compaction call can now stop before its
|
||||
request goes out (#972).** Previously it could not: `model_turn` refused
|
||||
to *re-issue* an abandoned call after a mid-stream death, but nothing
|
||||
checked before a first dispatch, so a call whose caller had already gone
|
||||
away still sent — and the reply was discarded unread after the endpoint
|
||||
had accepted the work. It now checks immediately before sending, so a
|
||||
Stop observed by that point costs no request, and again on entry, so a
|
||||
call already cancelled when it arrives also skips credential resolution.
|
||||
Cancellation is cooperative, which bounds what that buys: a Stop only
|
||||
saves the request if it lands before dispatch — sending is a moment, the
|
||||
response streaming back is the rest of the call, and an abort arriving
|
||||
then still meets a request in flight, closed in place exactly as before.
|
||||
The window that did widen usefully is a delegated-auth alias whose token
|
||||
mint blocks; a Stop during that mint now costs no request (though a mint
|
||||
already under way still completes). What a stopped call saves is the
|
||||
request, its prompt-side billing, and — on a capacity-bounded
|
||||
self-hosted endpoint — a slot a live request wanted. Unchanged: the
|
||||
interactive turn, which has its own pre-send cancellation check on a
|
||||
different path, and the lanes that thread no cancellation handle
|
||||
(attachment perception, title generation, web-fetch extraction,
|
||||
sub-agents, optimizer, eval) — and web-fetch extraction deliberately
|
||||
never will, since it runs on parallel tool threads where registering one
|
||||
would clobber the main stream's.
|
||||
- **Unmarked chain-of-thought no longer leaks into titles, summaries, or
|
||||
web-fetch tool results (#940).** Some serving setups emit reasoning
|
||||
inline with no tags and no `reasoning_content` at all — nothing any
|
||||
parser can segregate. The bounded-artifact lanes (title, compaction,
|
||||
web-fetch extraction) now ask the model for no reasoning instead:
|
||||
the model definition's declared thinking toggle is pinned off for that
|
||||
call — the same suppression transcription already used — and the
|
||||
reasoning-effort channels (the relayed session knob, the definition's
|
||||
default, the graded template key) are withheld with it, since an
|
||||
effort value beside a pinned-off toggle re-requests the reasoning the
|
||||
pin declined. A no-op on backends that segregate reasoning
|
||||
server-side. Title generation additionally stopped trusting line
|
||||
position: it takes the last line that reads as a title (within the
|
||||
word cap and ending in a word character, so explanation sentences,
|
||||
sign-offs, and reasoning headings lose in any script) rather than the
|
||||
first non-empty line, which unmarked reasoning turned into titles
|
||||
like "Thinking Process:".
|
||||
- **A think tag split across a reasoning delta now reassembles.** The
|
||||
non-streaming drain closes content runs at interleaving signals; a
|
||||
partial-tag tail is carried across reasoning-delta boundaries (a
|
||||
reasoning delta cannot terminate a tag) so the tag is consumed instead
|
||||
of its halves passing through as visible content. Tool-call boundaries
|
||||
still flush — no tag spans a tool call.
|
||||
- **Streaming consumers follow the ACTIVE model's capabilities.** The
|
||||
interactive tag-scan posture and the drain's scan gate now read the
|
||||
capabilities of the lane that owns the stream being consumed (fallback
|
||||
walks included) instead of the session's primary alias.
|
||||
- **Notification bodies no longer fuse multi-block answers.** `Turn.text`
|
||||
joins text blocks with a newline; a final assistant turn stored as
|
||||
multiple text blocks previously concatenated the last word of one
|
||||
block to the first word of the next in completion notifications and
|
||||
every other flattened read.
|
||||
- **String-typed boolean capability overrides coerce instead of
|
||||
truthiness-flipping.** A hand-edited `"false"`/`"0"` in a model
|
||||
definition's capabilities JSON now means false; unrecognized values
|
||||
drop the key and keep the field's default.
|
||||
- **Inline `<think>`/`<reasoning>` blocks no longer leak into drained
|
||||
results (#965, #940).** On servers without a reasoning parser
|
||||
(parserless vLLM/llama.cpp, LM Studio, bare gateways), reasoning
|
||||
arrives as literal tags inside content; segregation now happens once
|
||||
at the drain seam, so web-fetch tool results, sub-agent syntheses,
|
||||
judge verdicts, titles, summaries, and optimizer prompts receive
|
||||
tag-free content and the extracted reasoning rides the native lane.
|
||||
Two behavior notes: a web-fetch extraction whose whole response was
|
||||
reasoning now returns an explicit `Error: extraction returned no
|
||||
answer` tool result (previously the raw reasoning text persisted as a
|
||||
successful result and was replayed every following turn), and a
|
||||
mismatched-vocabulary close tag (`<think>…</reasoning>`) now closes
|
||||
the block — matching the interactive lane's long-standing rule —
|
||||
where the old per-lane strips treated it as unterminated.
|
||||
|
||||
- **A transport failure mid-generation no longer kills the interactive
|
||||
turn (#937).** A wire death during body streaming (TLS record failure,
|
||||
connection reset — `httpx.ReadError` and kin) surfaces after the
|
||||
request has already returned its stream handle, so neither the SDK's
|
||||
request retries nor the creation-time retry ladder ever saw it: the
|
||||
turn died with a bare `ReadError: …`, the partial output was
|
||||
discarded, and nothing was logged. The interactive loop now normalizes
|
||||
mid-body transport deaths exactly like the single-shot lanes and
|
||||
re-issues the turn (bounded, cancel-aware, exponential backoff),
|
||||
finalizing the dead attempt across every UI surface first so retried
|
||||
text never double-renders (web transcript, CLI markdown fences,
|
||||
Slack/Discord streamed messages). Before re-creating the stream the
|
||||
session re-resolves its registry binding, so a concurrent model-registry
|
||||
reload that closed the old client cannot turn the retry into a
|
||||
misleading closed-client error. On exhaustion the surfaced error names
|
||||
the provider, endpoint, and model with a stream-death message instead
|
||||
of a bare exception string, and every fatal turn now leaves a
|
||||
`session.fatal.recorded` log line (INFO for a user Ctrl-C, ERROR
|
||||
otherwise).
|
||||
|
||||
- **A failed worker-thread spawn no longer wedges the workstream — at
|
||||
either spawn site — and never masquerades as success.** If
|
||||
`Thread.start()` itself raised (thread exhaustion, out-of-memory), the
|
||||
dispatcher had already claimed the worker slot but the flag's only
|
||||
clearer lived in the never-started thread — the workstream looked idle
|
||||
forever while every subsequent message queued behind a worker that
|
||||
didn't exist, until an operator force-cancel. The claim is now rolled
|
||||
back under the lock and the error propagates, so the workstream is
|
||||
dispatchable again as soon as resources recover. Affected every
|
||||
dispatch path (sends, wakes, retries, deferred-send drain, init). The
|
||||
same failure at the deferred-send drain's own spawn rolls back the
|
||||
just-accepted entry and answers the retryable `queue_full` (previously
|
||||
a 500 landed *after* the entry was registered — an invisible,
|
||||
unretractable phantom that later dispatched as duplicate turns), and a
|
||||
`/command` whose worker never spawned now answers **503**
|
||||
`{"status": "error"}` instead of the generic 200 ok that told SDK
|
||||
callers their `/clear` or `/resume` had applied.
|
||||
|
||||
- **Manual `/compact` from the web UI: no phantom user turn, no frozen
|
||||
server, cancellable.** A slash command typed into the web composer no
|
||||
longer renders as a user chat bubble (it echoes as a distinct command
|
||||
chip — commands aren't conversation turns and were never persisted as
|
||||
such). `/compact` itself now dispatches onto the workstream's worker
|
||||
slot instead of running inline on the server's event loop — previously a
|
||||
long compaction froze every SSE stream on the node for its whole
|
||||
duration, which is also why its own progress only ever arrived as one
|
||||
burst after the fact. The manual path carries `send()`'s full generation
|
||||
discipline (`compact_now()`): a force-abandoned compaction goes stale
|
||||
instead of swapping history under a successor turn — and retires at its
|
||||
next checkpoint instead of running out its remaining summary calls,
|
||||
with its late lifecycle events fenced off (`compaction_id` on every
|
||||
event, `superseded` on end events — both in the SDKs) so they can't
|
||||
animate, tear down, re-title, or falsely narrate a successor's card or
|
||||
activity pill; a cancel aimed at it is consumed on exit (previously it
|
||||
bricked every `/compact` retry until the next message); a Stop click on
|
||||
an idle session can't pre-abort the next compaction; a Stop that lands
|
||||
in the completion tail — after the last cancel check, or during a retry
|
||||
backoff (which now aborts immediately instead of sleeping it out) — is
|
||||
honored rather than silently eaten; and Stop now aborts the in-flight
|
||||
summary HTTP call itself (the compaction lane registers its stream in
|
||||
the same abort seam the main loop uses), so cancelling a compaction is
|
||||
immediate instead of waiting out a model call.
|
||||
|
||||
- **Sends during a command window are deferred, ordered, bounded, and
|
||||
honestly rendered — never silently truncated or lost.** Messages sent
|
||||
while any slash command holds the worker slot are **deferred**: answered
|
||||
`{"status": "queued", "msg_id"}` immediately and dispatched as ordinary
|
||||
full-fidelity sends (attachments and sender identity included) when the
|
||||
command finishes — never routed through the mid-turn interjection
|
||||
queue, whose semantics are turn-shaped: previously a send during a
|
||||
manual `/compact` was silently truncated to 2,000 characters, a second
|
||||
participant in a shared workstream was locked out with a misleading
|
||||
"another participant's turn" 409 for the whole compaction, and a
|
||||
message queued across a `/resume`/`/new` could be answered into the
|
||||
post-swap workstream. Because the response is immediate,
|
||||
timeout-bounded callers — the coordinator's `send_message`, the console
|
||||
proxy, SDKs, anything behind a stock reverse proxy — can no longer lose
|
||||
a message to a multi-minute command window; the deferred send is
|
||||
retractable until dispatch via the same `DELETE .../send` used for
|
||||
queued interjections (node-local, in-memory — the API reference
|
||||
documents the at-most-once durability contract). Deferred responses
|
||||
carry `"deferred": true`; the pending list is the **order authority**
|
||||
(a fresh send — or a coordinator dispatch, or a queued-nudge wake —
|
||||
lines up behind acknowledged entries instead of overtaking them, with
|
||||
the two-term barrier defined once on the workstream so the wake gate
|
||||
also honors a claimed entry whose dispatch is mid-flight, and the gate
|
||||
re-arms at the drain's exit even when everything pending was
|
||||
retracted); acceptance is **bounded** (10 pending per workstream — the
|
||||
interjection queue's own backpressure contract; the 11th answers the
|
||||
retryable `queue_full` instead of pinning attachment bytes without
|
||||
limit and then running one unattended turn per entry); a dispatch
|
||||
crash re-queues the entry instead of eating an acknowledged message,
|
||||
and a drain thread that fails to *start* rolls the acceptance back and
|
||||
answers `queue_full` rather than parking a phantom the client can
|
||||
neither see nor retract; each dispatch emits a pane-tier
|
||||
`message_dispatched` event (`folded: true` for interjection fold-ins)
|
||||
so queued-bubble UI keeps its retract affordance exactly until the
|
||||
message truly leaves — including when the send was accepted by a pane
|
||||
that believed the workstream idle, which now renders a real queued
|
||||
chip instead of a sent-looking bubble, releases the composer (a
|
||||
deferred send has no running worker to wait on), and cleans up fully
|
||||
when the send is refused or the chip retracted instead of stranding
|
||||
the pane in Stop mode. Dismissing a queued bubble — interjection or
|
||||
deferred — is a server-confirmed `DELETE`, and retracting a deferred
|
||||
send that carried attachments tells the user they were discarded
|
||||
instead of silently expiring them.
|
||||
|
||||
- **Slash commands hold the worker slot with a loud contract.**
|
||||
A `/compact` raced against an in-flight turn is refused with an
|
||||
explicit busy response. Every other slash command runs through the same
|
||||
worker slot too — mutual exclusion against sends, a running compaction,
|
||||
and each other, with a busy answer replacing the old silent interleave —
|
||||
while the endpoint still awaits quick commands' completion off-loop
|
||||
(without parking an executor thread per request); the post-command pane
|
||||
refreshes (`clear_ui` after `/clear`/`/new`/`/resume`, the
|
||||
workstream-name sync) ride the worker itself, so a command that
|
||||
outlives the endpoint's 25s response backstop still refreshes every
|
||||
pane on completion (the backstop sits under the console proxy's 30s
|
||||
client timeout so the degraded `running` answer can actually traverse
|
||||
a proxied pane, which now surfaces it instead of silence; the
|
||||
`/command` response contract — `ok` / `running`, with busy refusals
|
||||
answering a loud HTTP 409 rather than a silent 200 — is now documented
|
||||
in the API reference and the OpenAPI spec).
|
||||
|
||||
- **Compaction status stays truthful across every UI surface.** Manual
|
||||
compaction
|
||||
success also refreshes the status line/context pill immediately (parity
|
||||
with auto-compaction), compaction failures keep feeding the typed
|
||||
`error` event and the node error counter (while a CLI Ctrl-C reports as
|
||||
cancelled, not a failure), one Stop prints one notice (a cancelled
|
||||
auto-compaction no longer stacks "Compaction cancelled." on top of
|
||||
send's own "[Generation cancelled]"), the workstream activity pill
|
||||
shows "Compacting context…" for the whole summarize phase, restores
|
||||
cleanly afterwards, and can no longer be stranded by a force-stopped
|
||||
compaction (a new turn's generation claim breaks a stale latch). Every
|
||||
retry backoff on the session (stream retries, task agents, notify
|
||||
delivery, compaction) now aborts immediately on Stop via one shared
|
||||
cancel-aware helper instead of sleeping out its exponential delay.
|
||||
|
||||
- **Compaction failures report exactly once, to the right owner.** A
|
||||
compaction failure reports
|
||||
exactly once (auto-compaction errors defer to the turn's fatal handler
|
||||
instead of doubling the red row and the error metric), failed-end
|
||||
notice suppression is computed once by the emitter (a `notice` bool on
|
||||
the end event — in the SDKs — replaces hand-synced client policy), and
|
||||
a manual `/compact` failure no longer crashes the CLI REPL. `/compact`
|
||||
on a workstream showing the `error` badge restores the badge on exit
|
||||
instead of stamping `idle` over it (the compaction neither retried nor
|
||||
resolved the failed turn). A force-cancelled initial send that
|
||||
completes late still delivers its scheduled-run completion
|
||||
notification (the only completion signal unattended workstreams have);
|
||||
the other post-command pane refreshes and error notices remain
|
||||
owner-guarded, so a force-cancelled wedged command that unwedges late
|
||||
can't wipe panes or inject stray notices into a successor turn.
|
||||
|
||||
- **Pre-1.8 embedder UIs keep their compaction lines.** Embedders
|
||||
driving `ChatSession` with a pre-1.8 duck-typed `SessionUI`
|
||||
(no `on_compaction` hook) get the classic `on_info` compaction lines
|
||||
back — threshold notice, `part k/N`, retry waits, token delta +
|
||||
summary box — instead of silent history swaps. (See the breaking
|
||||
event-contract note under **Changed** for SSE/SDK clients.)
|
||||
|
||||
- **Static MCP servers: a pushed catalog change no longer wedges the shared
|
||||
session (#839).** The static-path `*/list_changed` handler awaited its
|
||||
catalog refresh inline in the SDK's receive loop, but the refresh's own
|
||||
request can only be answered by that (now parked) loop — the refresh never
|
||||
completed, and every user's in-flight calls on the shared per-node session
|
||||
stalled behind it, unbounded, until the health loop's ping timeout tore the
|
||||
transport down (which was also the only way the changed catalog ever
|
||||
landed). Push refreshes now run as spawned tasks — debounced, coalesced per
|
||||
(server, kind), bounded by the connect timeout, and serialized on the
|
||||
per-server connect lock — and the manual and post-reconnect refreshes
|
||||
publish under that same lock, so a slower publisher can no longer land a
|
||||
staler catalog over a fresher one. Every teardown path now also clears the
|
||||
notification debounce stamp, so a reconnected server's first push refreshes
|
||||
immediately. Push-refresh debouncing is now per (server, kind) on BOTH the
|
||||
static and per-user pool paths — a tools push no longer swallows a prompts
|
||||
push arriving in the same 5-second window. A change genuinely lost to the
|
||||
debounce window (a same-kind push landing after the prior refresh finished,
|
||||
which the server will never re-announce) is recovered by an automatic
|
||||
health-tick retry rather than staying invisible until an unrelated push or
|
||||
a reconnect. The resource-refresh fan-out on both paths no longer orphans
|
||||
its sibling list call when one of the pair fails fast — the real error
|
||||
surfaces immediately (not masked as a 30-second timeout) and the surviving
|
||||
sibling is cancelled and reaped, under a bounded grace, inside the scope. A
|
||||
push refresh that fails while the connection stays up is likewise retried on
|
||||
the next health-loop tick until one completes — previously a single
|
||||
transient blip left the shared catalog stale for every user on the node
|
||||
until an operator intervened. An operator `/mcp refresh` no longer parks
|
||||
behind a busy per-server connect lock (a slow reconnect attempt could eat
|
||||
the whole 30-second refresh budget and fail the pass for every healthy
|
||||
server behind it) — the busy server is skipped on both the connected and
|
||||
disconnected branches, reported distinctly as "skipped" rather than as a
|
||||
false "no changes", the skip arms the automatic retry, and a
|
||||
force-reconnect drops the session up front so queued push refreshes can't
|
||||
starve it. Static-path resource and prompt catalogs are now size-capped
|
||||
like the pool path's (and like static tools) at discovery and on every
|
||||
refresh, so a misbehaving server's push can't balloon the node's merged
|
||||
catalogs. Deleting or reconfiguring a server can no longer leave it
|
||||
half-removed: the config removal and all cleanup are serialized under the
|
||||
connect lock (a cancelled removal completes its cleanup rather than
|
||||
stranding a live session and published catalog with the config already
|
||||
gone), and `reconcile_sync` retries a removal that timed out instead of
|
||||
marking it done — previously a DB-driven delete of a busy server could be a
|
||||
silent, permanent no-op until process restart. A refresh outcome now
|
||||
threads consistently to every operator surface off one source of truth
|
||||
(the per-server `last_refresh_outcome`): a busy-skip and a genuine failure
|
||||
are each reported distinctly from a real "no changes" — `/mcp refresh`
|
||||
prints "skipped" or "failed" rather than a false "no changes", and the
|
||||
node-internal refresh endpoint returns `202 skipped` instead of a
|
||||
misleading `200 ok` for a refresh that never ran. A single-kind push
|
||||
refresh no longer paints the whole server healthy: because the
|
||||
error/outcome state is server-scoped, a successful tools push while the
|
||||
prompts catalog is still broken (or vice versa) no longer clears the
|
||||
failure — only a full refresh pass declares "ok".
|
||||
|
||||
- **OpenAI Responses streaming: truncated and refused responses no longer
|
||||
vanish.** A response that hit `max_output_tokens` terminates the stream
|
||||
with `response.incomplete`, which the stream consumer did not handle —
|
||||
the turn was mislabeled `finish_reason: stop` and its final usage and
|
||||
collected output items were dropped. Refusal parts had no streaming
|
||||
handler at all, so a refusal rendered as empty content instead of the
|
||||
`[Refused: …]` text the non-streaming path produced. Both now match:
|
||||
truncation maps to `length` with usage/items intact, refusals render
|
||||
in content. Applies to the chat loop and every drained single-shot
|
||||
lane (#831).
|
||||
|
||||
- **task_agent: sub-tool ids no longer alias across a local model's reused
|
||||
ids.** A local model that reissues per-response sequential tool-call ids
|
||||
(`call_0` every turn) made two of a task agent's steps share one id — the
|
||||
live card collapsed both onto one DOM row while `/history` recall kept them
|
||||
apart, so the two views disagreed. Sub-tool ids are now minted
|
||||
`{parent}::r{run}s{step}::{id}`, unique within the session (across an
|
||||
agent's turns and across concurrent or sequential runs), and that one id
|
||||
keys the nesting registry, the live rows, recall, and the cancel ledger.
|
||||
On the wire the agent's self-built history carries the provider's own ids,
|
||||
restored from the mint map (see the reasoning-lane entry under Added), and
|
||||
malformed tool-call arguments are legalized the same way the main loop's
|
||||
wire prep does.
|
||||
|
||||
- **bash tool: never hang on a backgrounded child.** A command that left a
|
||||
long-lived process running (`server &`, a daemon) could wedge the whole
|
||||
workstream forever — the tool read stdout/stderr to EOF, which never arrived
|
||||
because the child inherited the pipe, and the timeout watchdog bailed once the
|
||||
foreground `bash` had exited. The tool now waits on the tracked process
|
||||
(bounded by the tool timeout) and terminates its whole process group on
|
||||
return, so the call always completes. Undecodable output is preserved
|
||||
(`errors="replace"`) instead of being dropped as a spurious error.
|
||||
- **Behavior change:** a process the command backgrounds no longer survives
|
||||
the call — nothing persists across bash invocations. (First-class
|
||||
"run this in the background" support landed separately — see
|
||||
`run_in_background` under Added.)
|
||||
|
||||
## [1.7.3]
|
||||
|
||||
A small feature and maintenance patch for the 1.7 line. No schema migrations
|
||||
and no new configuration knobs.
|
||||
|
||||
### Added
|
||||
|
||||
- **OpenAI GPT-5.6 (Sol/Terra/Luna) support** — the Responses provider
|
||||
understands the GPT-5.6 family: the `reasoning.mode` control, the new
|
||||
`max` effort tier, and `text.verbosity`, with golden wire payloads pinning
|
||||
the request shapes. The `openai` dependency floor moves to `>=2.44`.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Engineer base prompt hardened with process discipline** — the default
|
||||
base prompt for non-coordinator sessions now works in phases scaled to the
|
||||
size of the change, defaults to red-green for testable work, scopes to the
|
||||
smallest sufficient diff, stops to report after repeated failed attempts
|
||||
instead of thrashing, reports only observed results, and delegates
|
||||
exploration to `task_agent`. Persona prompts freeze into the workstream
|
||||
stamp at creation, so this reaches new workstreams only.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Unknown reasoning-mode warnings name the allowed modes** — a model
|
||||
definition with an unrecognized reasoning mode now logs the valid options
|
||||
instead of leaving the operator to guess.
|
||||
|
||||
### Documentation
|
||||
|
||||
- **HYPOTHESIS.md / PRIMER.md** — the control normal form is tightened and
|
||||
the factored Q_E reading is carried into the glossary; the plain-language
|
||||
PRIMER stays in sync.
|
||||
|
||||
## [1.7.2]
|
||||
|
||||
A feature-bearing patch for the 1.7 line. Rather than hold this work for the
|
||||
larger 1.8 churn, the fixes and the smaller features that had already
|
||||
stabilised on `main` are rolled into the stable line now: a rich preview
|
||||
pane, persona/project settings on scheduled tasks, and a batch of streaming,
|
||||
rendering, and nudge-delivery hardening.
|
||||
|
||||
> **⚠️ Before upgrading:** 1.7.2 adds Alembic migration `066`, applied
|
||||
> automatically on first start. It adds two `Text NOT NULL DEFAULT ''`
|
||||
> columns (`persona`, `project_id`) to the `scheduled_tasks` table; existing
|
||||
> rows migrate to the empty default, which is byte-identical to pre-066
|
||||
> dispatch behaviour. The change is additive and reversible, but — as always
|
||||
> — back up your storage before upgrading (`pg_dump` for PostgreSQL; copy the
|
||||
> database file for SQLite).
|
||||
|
||||
### Added
|
||||
|
||||
- **Rich preview pane + `open_preview` tool** — a workstream can now open a
|
||||
rendered preview (HTML, Markdown, and other kinds) in a pane beside the
|
||||
conversation via the new `open_preview` tool. Guarded fetches stream under
|
||||
a byte budget whose ceiling tracks the widest per-kind cap, preview blob
|
||||
ids are salted, and a preflight probe handles legacy charsets and a
|
||||
remote-assets opt-in. See `docs/tools.md`.
|
||||
- **`allow_private_network` opt-in for `web_fetch` / `open_preview`** —
|
||||
private-address fetch and preview targets stay blocked by default; an
|
||||
operator can opt a workstream in through the settings registry when a
|
||||
private endpoint is genuinely intended. (Distinct from the 1.7.1 `[oidc]`
|
||||
flag of the same name, which governs identity-provider discovery.)
|
||||
- **Persona + project settings on scheduled tasks** (migration `066`) — a
|
||||
scheduled task can now pin the **persona** and **project** of the
|
||||
workstream it dispatches, matching the levers a manually-created workstream
|
||||
already carries. Both default to empty (kind-default persona / no project),
|
||||
so existing schedules dispatch exactly as before.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Streaming fast-path overflow recovery** — fast-stream tokens are now
|
||||
batched and overflowed SSE listeners recover instead of stalling (and
|
||||
`connectSSE` no longer opens into a hidden background tab). The same
|
||||
overflow-recovery companions were carried to the coordinator pane, so a
|
||||
coordinator watching many children recovers dropped listeners the same way
|
||||
the live-session view does.
|
||||
- **Renderer containment** — markdown sentinel-forgery and recursive-frame
|
||||
content loss are contained, and an indented fence close no longer drags its
|
||||
indent into the enclosed code content.
|
||||
- **Idle nudge / wake delivery** — nudge and wake delivery is hardened across
|
||||
session eviction, cancellation, and identity rebinds; the wake gate now
|
||||
requires a real nudge queue, refused wakes are logged, and
|
||||
`initial_message_status` is typed as a closed enum on the wire.
|
||||
- **`web_fetch` extraction inherits model settings** — the completion that
|
||||
extracts content from a fetched page now inherits the workstream's model
|
||||
settings instead of falling back to defaults.
|
||||
- **UI panes** — ephemeral panes close on split-dismiss instead of orphaning
|
||||
a tab, and an unsplit skips the redundant refresh after an ephemeral pane
|
||||
closes.
|
||||
- **Shared code-highlight CSS** — renderer-output CSS is shared so the console
|
||||
and coordinator panes highlight code identically.
|
||||
|
||||
### Security
|
||||
|
||||
- **`Content-Disposition` filenames made wire-safe** — download filenames
|
||||
derived from user-controlled text are sanitised (latin-1- and
|
||||
control-char-safe, quoting-safe) before they reach the `Content-Disposition`
|
||||
response header, including the fallback path.
|
||||
|
||||
### Documentation
|
||||
|
||||
- **HYPOTHESIS.md: daemons + the outer loop, plus a plain-language PRIMER** —
|
||||
the harness north-star document gains its daemon / outer-loop treatment and
|
||||
a new top-level `PRIMER.md`.
|
||||
|
||||
## [1.7.1]
|
||||
|
||||
A maintenance and hardening patch for the 1.7 line. No schema migrations;
|
||||
the credential-redaction work below is additive and needs no configuration
|
||||
change. The one new operator-facing knob is the opt-in `[oidc]
|
||||
allow_private_network` flag (default off).
|
||||
|
||||
### Security
|
||||
|
||||
- **Credential redaction hardened across the tool-call surface** — the
|
||||
redactor that scrubs secrets from tool arguments and log previews was
|
||||
reworked on both the backend and the browser to close several leak paths
|
||||
and to fix false-positive and performance issues. Malformed tool-call
|
||||
arguments are now legalised before they reach the wire; the tool-args log
|
||||
preview scrubs credentials and control characters; and the coordinator's
|
||||
tool-call cards gain a matching client-side redaction pass so the JS and
|
||||
backend redactors stay at parity. Pattern coverage now includes
|
||||
`secret_access_key` / `aws_secret_access_key` multi-segment keys, bare
|
||||
`token=` / `key=` forms (guarded by a negative lookbehind to avoid
|
||||
false positives), and SQLAlchemy `+driver`-qualified connection-string
|
||||
schemes matched case-insensitively.
|
||||
- **OIDC SSRF guard: `[oidc] allow_private_network` opt-in** — self-hosted
|
||||
identity providers on private networks can now be reached by setting
|
||||
`allow_private_network = true` under `[oidc]` (default off; the MCP OAuth
|
||||
path stays strict). Rejections of discovered endpoints carry the opt-in
|
||||
hint so the misconfiguration is self-explanatory. See `docs/oidc.md`.
|
||||
|
||||
### Added
|
||||
|
||||
- **Persona discoverability + forgiving name resolution** — personas are
|
||||
now discoverable by agents, and persona-name resolution tolerates
|
||||
case/whitespace variation; a not-found resolution reports the offending
|
||||
input verbatim instead of a bare error.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **MCP transport lifecycles routed through per-entry owner tasks**
|
||||
(#787/#788) — static and pooled MCP transport lifecycles are now driven
|
||||
by per-server / per-entry owner tasks, with a hardened disarm-sweep loop
|
||||
guard and targeted exception handling in place of a broad `BaseException`
|
||||
arm, so a dying transport can no longer spin the CPU or strand delivery.
|
||||
- **Client-construction failures surface as misconfiguration, not raw
|
||||
500s** — a model whose client cannot be constructed now reports a factory
|
||||
misconfiguration, and the raw exception text is kept out of the resulting
|
||||
503 response.
|
||||
- **Postgres history search survives oversized rows** — a conversation row
|
||||
exceeding Postgres' full-text limits no longer aborts history search.
|
||||
- **Agent-tool render is idempotent** — tool rendering no longer deep-copies
|
||||
a tool definition until a description actually changes, so no-persona
|
||||
sessions share the tool constant (correctness plus a hot-path allocation
|
||||
win).
|
||||
- **Private-project workstream visibility scoped to members** — workstreams
|
||||
in a private project are visible to project members only, not to every
|
||||
admin; coordinator tenancy checks now use request-scoped storage.
|
||||
- **Pane hotkeys work off macOS and match across surfaces** — the pane
|
||||
keyboard shortcuts no longer collide with browser accelerators on
|
||||
non-macOS platforms and behave consistently across surfaces.
|
||||
|
||||
## [1.7.0]
|
||||
|
||||
The headline of the 1.7 line is **Personas** — operator-authored control
|
||||
|
||||
@@ -8,11 +8,6 @@ The following people have contributed code to the project — thank you:
|
||||
- Burhan ([@Burhan-Q](https://github.com/Burhan-Q))
|
||||
- chrismuzyn ([@chrismuzyn](https://github.com/chrismuzyn))
|
||||
- daoxley ([@daoxley](https://github.com/daoxley))
|
||||
- metaclassing ([@metaclassing](https://github.com/metaclassing))
|
||||
- posixpositive ([@bensonjohnson](https://github.com/bensonjohnson))
|
||||
- Robert DeAngelis ([@OriginalOrangeXD](https://github.com/OriginalOrangeXD))
|
||||
- Sanjay Santhanam ([@Sanjays2402](https://github.com/Sanjays2402))
|
||||
- Stefano Maffeis ([@lesbass](https://github.com/lesbass))
|
||||
- William ([@sillyWillieBilly](https://github.com/sillyWillieBilly))
|
||||
- [@BlackMyrmidon](https://github.com/BlackMyrmidon)
|
||||
- [@pizzaandcheese](https://github.com/pizzaandcheese)
|
||||
|
||||
+3
-7
@@ -8,7 +8,7 @@ FROM python:3.14-slim
|
||||
LABEL org.opencontainers.image.title="turnstone" \
|
||||
org.opencontainers.image.description="Multi-node AI orchestration platform"
|
||||
|
||||
COPY --from=ghcr.io/astral-sh/uv:0.12.3 /uv /usr/local/bin/uv
|
||||
COPY --from=ghcr.io/astral-sh/uv:0.11.26 /uv /usr/local/bin/uv
|
||||
|
||||
# Remove the slim image's man page exclusion so man-db has actual content
|
||||
RUN rm -f /etc/dpkg/dpkg.cfg.d/docker
|
||||
@@ -55,17 +55,13 @@ COPY docker/healthcheck.py /usr/local/bin/healthcheck.py
|
||||
|
||||
# Entrypoint script — runs migrations before starting
|
||||
COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
|
||||
RUN chmod +x /usr/local/bin/entrypoint.sh
|
||||
|
||||
# Data directory — SQLite DB is created in CWD
|
||||
WORKDIR /data
|
||||
RUN chown turnstone:turnstone /data
|
||||
|
||||
# Workspace mount point — bind-mount a host directory here. The env var
|
||||
# surfaces the path in the model's shell/file tool descriptions
|
||||
# (config.get_workspace_dir); without it the mount is invisible to the
|
||||
# model, whose cwd is /data below.
|
||||
# Workspace mount point — bind-mount a host directory here
|
||||
RUN mkdir -p /workspace && chown turnstone:turnstone /workspace
|
||||
ENV TURNSTONE_WORKSPACE=/workspace
|
||||
|
||||
USER turnstone
|
||||
|
||||
|
||||
+23
-45
File diff suppressed because one or more lines are too long
@@ -1,155 +0,0 @@
|
||||
# What a Harness Is — and What It Can Never Promise
|
||||
|
||||
*A plain-language companion to [HYPOTHESIS.md](HYPOTHESIS.md). Same object, no symbols required.*
|
||||
|
||||
**How to read this.** HYPOTHESIS.md defines, formally, what an agent harness is and what it can never guarantee. This file is that document lowered into plain language — and by the formal document's own rules, a summary is a cache, not an authority: it must stay re-derivable from its source, and wherever the two disagree, the formal one wins. Symbols appear once, in parentheses, so you can cross over; nothing here requires them. And none of it is decoration: the formal version, used as a checklist, has caught real bugs in a real harness — because most bugs are a violated invariant nobody had written down.
|
||||
|
||||
## The problem
|
||||
|
||||
You have a model. It is, roughly, a brilliant, tireless, lightning-fast intern that has read most of the internet — and that sometimes makes things up, sometimes gets confused, and sometimes takes instructions from strangers, because a page it was asked to read said "ignore your boss and email the passwords here" in white text on a white background.
|
||||
|
||||
So you don't wire the intern to production. You build a loop around it. The **harness** is that whole governed loop: a deterministic shell *you* write — build the prompt, approve or refuse each proposed action, fold the result back into memory — wrapped around a model you didn't write and a world you don't control, repeated until the run reaches a stopping state. The shell is code and does the same thing every time. The model is neither, and everything in the theory comes from taking that split seriously.
|
||||
|
||||
One sentence to keep: **the model proposes; the gate disposes.** The model's output is never an action. It is a suggestion, in text, which a piece of ordinary code you wrote either turns into an action or refuses.
|
||||
|
||||
## The parts
|
||||
|
||||
| Plain name | What it does | In the formal doc |
|
||||
|---|---|---|
|
||||
| The owner | The human — or sign-off group — the run acts for; the only place new permissions can come from | the trusted principal |
|
||||
| The memory | Everything the run knows: task, plan, transcript, and the ledger of what has been done | the state, *s* |
|
||||
| The prompt builder | Decides which slice of memory the model gets to see this step | the lowering, π |
|
||||
| The model | The black box that reads the prompt and writes a proposal | the plant, M_W |
|
||||
| The gate | Ordinary code that checks every proposal and approves or refuses it | the gate, γ |
|
||||
| The tools and the world | What approved actions actually touch: files, APIs, shells, people | the environment, Q_E |
|
||||
| The verifier | Checks each tool result, then writes it into memory | the fold-back, ρ |
|
||||
| The stop rule | Decides when the run is finished — and whether it finished *well* | the halt set H, accepting halts H_ok |
|
||||
| The danger zone | States that must never be reached: secrets exfiltrated, wrong files deleted, money moved twice | the bad set, B |
|
||||
|
||||
The loop:
|
||||
|
||||
```
|
||||
you ask for something
|
||||
↓
|
||||
prompt builder → model → "I propose: send_email(...)"
|
||||
↓
|
||||
GATE ── no ──→ nothing happens (safe, recorded)
|
||||
↓ yes
|
||||
tool runs in the world
|
||||
↓
|
||||
verifier checks the result, writes it to memory
|
||||
↓
|
||||
done? ── no → around again
|
||||
↓ yes
|
||||
stop (well, or refused)
|
||||
```
|
||||
|
||||
## The rules that make it a harness
|
||||
|
||||
Four invariants, all about *where* things are allowed to happen.
|
||||
|
||||
1. **The model sees only what the prompt builder shows it** — never raw memory. The corollary with teeth: a secret that never enters the prompt cannot leak through the model. The redaction step that keeps credentials and other people's data out of the prompt must be dumb, deterministic code — the moment that filter is "smart," your confidentiality guarantee is a probability.
|
||||
2. **Model outputs are proposals, not actions.**
|
||||
3. **Every side effect passes the gate.** There is no second door.
|
||||
4. **The harness itself flips no coins.** Replay a step with the model's answer and the tool results pinned, and behavior must be identical; any leftover variation is randomness *you* added and must be accounted for. The fine print: "deterministic" is conditional on pinned versions — a provider silently retraining the model behind the same API name changes the machine under you, and every dashboard number you collected dies with the version.
|
||||
|
||||
Notice what the rules don't say: they don't say the harness is *good*. A gate that approves everything satisfies rule 3 the way a lock that's always open satisfies "has a lock." The definition is a shape; the guarantees are what a particular harness *earns* inside it. Everything below is about what can be earned — and what can't.
|
||||
|
||||
And notice the symmetry between rules 1 and 3. There is exactly one door from your data into the model — what it may see — and exactly one door from the model into the world — what it may do. Nearly every security failure in these systems is one of those two doors with a hole in it: a secret lowered into a prompt that didn't need it, or a path from model text to a side effect that skipped the gate. Same bug, arrow flipped.
|
||||
|
||||
## Fail-closed, said precisely
|
||||
|
||||
"Fail-closed" gets used loosely. Here it means something exact: **nothing happens unless the gate said yes, and a refusal must itself be safe** — a refused proposal causes no side effect and leaves the run somewhere sane, which may be "stopped, having declined." The run is allowed to *say so*: a templated status message written by the shell is the shell speaking, not the model, and needs no gate. Failed runs don't have to die silent.
|
||||
|
||||
Three consequences people miss:
|
||||
|
||||
**Reads are not free.** A read-only call can smuggle instructions *in* (the fetched page is attacker-controlled) or secrets *out* (the URL it fetches can encode the payload). The gate approves calls, not just writes.
|
||||
|
||||
**Validation must not act.** A "validator" that resolves a URL, expands a template that fires a webhook, or evaluates an argument has already acted — inside the check. The gate must be pure: it reads the proposal and the memory and outputs yes or no. If deciding requires touching the world, that touch is itself an action and goes through the gate.
|
||||
|
||||
**Anything irreversible is decided at the gate.** The verifier can reject a bad *result*; it cannot unsend the email. So the question "can we take this back, and until when?" is asked before execution — which means each tool declares, up front, how reversible its effects are, and the gate reads that declaration when it decides; the mark that comes back in the result record is confirmation for the books, not the gate's source — the gate needed the answer before the tool ever ran.
|
||||
|
||||
Two honest asterisks. First, the gate checks a snapshot: it approves against the world *as its memory describes it*, and the world can move between check and commit. For actions that race the world — spend against a balance, write against a row — the tool itself must bind check to commit (compare-and-swap), or you have a classic time-of-check/time-of-use hole. The gate decides; for those effects, the tool enforces. Second, a gate is only as binding as the authority behind the tools. A tool process holding standing credentials — a database connection with every grant, an environment full of long-lived secrets — doesn't need the model's proposal to act, and against it the gate's "no" is a decision with nothing enforcing it. **A gate in front of an omnipotent tool is a suggestion.** The fix is to make the approval *be* the key: each authorized action carries a short-lived credential scoped to exactly that action, that resource, that operation, so tools hold no standing power at all.
|
||||
|
||||
## Why you don't get a proof — and what you do instead
|
||||
|
||||
If you write a sort function, you can prove it sorts: the function is small and the spec is exact. A harness has neither luxury. The spec side fails first — the task arrives in natural language, and natural language is, in the compiler's sense, *all undefined behavior*: there is no formal standard for "what the user meant" to verify against. The mechanism side fails next — the model is billions of learned parameters, and nobody can hand you a compact argument for why they jointly do the right thing.
|
||||
|
||||
Here is the careful version, because "you can't prove it" overshoots. The quantity you would want — call it the *expected steps to done* from any situation — is perfectly well-defined; in principle it exists. The document's central conjecture is that, for a model of this size, any faithful writing-down of that quantity is roughly *model-sized*: the honest proof-object does not compress. Find a small one and the conjecture dies — the document lists that outcome, explicitly, among the ways it could be wrong.
|
||||
|
||||
So instead of proving, you measure. You pick a progress meter — plan depth shrinking, open obligations closing, budget burning at the expected rate — and you check, across many runs, that it goes downhill and that its stalls predict failure. Two disciplines keep the measurement honest. The number bounds the world you *sampled*, never the world an adversary will choose: a meter calibrated on friendly traffic says nothing about hostile traffic. And the meter is itself attack surface: if "is the agent making progress?" is judged by another model, an attacker who can bend your agent can bend your *measurement of it* first, hiding the divergence from the very dashboard built to catch it. A learned meter is part of the system under test, never a neutral instrument.
|
||||
|
||||
A measurement is a risk metric. A proof is a certificate. Keeping those two words apart is half of what this theory is for.
|
||||
|
||||
## Security: reach the goal, avoid the danger — and who may change the rules
|
||||
|
||||
Formally, security here is a *reach-avoid* problem: reach a good stop, never touch the danger zone, **while an adversary picks the worst tool outputs your setup permits**. That last clause is the formal home of prompt injection: injection isn't "the model misbehaved," it's the environment optimized to bend your loop — poisoned pages, malicious tool descriptions, crafted responses.
|
||||
|
||||
Two different numbers fall out here, and dashboards love to collapse them: *success* (reached an accepted end before anything went wrong — a safe refusal counts against it) and *safety* (never touched the danger zone — a safe refusal is perfectly safe). Track both. They move independently. And both are scored by your own stop rule — they count what the shell *declared* a success. Whether a declared success was actually *right* is a third, harder number that no dashboard inside the system can produce; only a judge outside the run — a test suite, an audit, ground truth — can.
|
||||
|
||||
The gate handles the visible half of injection: the model, freshly poisoned, proposes emailing your credentials somewhere, and the gate refuses — and injection or not, the action does not happen. But the deeper attack doesn't propose a bad action today. It rewrites *what the run believes its job is* — it edits the plan — and then every future action looks locally reasonable against a corrupted plan. So memory has to be partitioned: **data** (tool results, fetched pages, retrieved documents — content the world supplied) and **control** (the plan, the permissions, what is authorized next). The security claim is conditional on that partition holding: untrusted content lands in data, always. And "trust" is really two questions pointing opposite ways, which is worth keeping straight: *can this leak?* (a value is as secret as the most-secret thing that fed it — secrecy flows **upward**) and *can this boss us around?* (a value is as trustworthy as the least-trustworthy thing that fed it — authority flows **downward**). Untrusted content is safe as *data* precisely because the second question keeps it off the control side; a secret is kept out of the model by the first. Lowering either barrier on purpose — declassifying a secret, promoting data to trusted — is an explicit decision the owner makes, never a thing that happens by accident when two values are combined.
|
||||
|
||||
Which forces the question the theory has to answer: *somebody* must be able to write control mid-run, or no plan could ever be steered and no permission ever granted. The answer is a small hierarchy with a top the model can't reach. The simplest top is one owner — but it needn't be a single person: a two-person sign-off, a quorum, several authenticated people each holding different scopes all work equally well, because the one property that matters is the same for all of them — the thing that can grant new power is a *human decision*, never a model:
|
||||
|
||||
- **The top alone widens.** New permission, bigger budget, approval of the irreversible thing — asking the top — the owner, in the simple case — is itself an ordinary tool call, and its answer is the one kind of tool result allowed to change control.
|
||||
- **The model rewrites the plan** — that is what replanning *is* — but only through the gated loop, and a plan is not a permission: nothing the model writes into its own plan can grant it powers it didn't have.
|
||||
- **Everything else is data.** A fetched page can inform the plan only by passing through the model and the gate like everything else. It can suggest. It cannot promote itself to boss.
|
||||
- **AI judges only tighten.** Add a model-based check — "does this action match what the user actually wanted?" — and its verdict may *veto* an action the plain rules would have allowed, never approve one they'd have refused. A judge that can approve is a tricked judge that can open the vault. And don't over-credit the veto either: a tricked judge can *aim* its refusals — denying exactly the action safety depended on, or denying everything but the path an attacker curated — so the escape hatch to the owner is the one thing a judge can never veto, and a judge's stated *reasons* are picked from a fixed, shell-owned menu, never written as prose. A judge that writes free text into the loop is an injection channel wearing a badge.
|
||||
|
||||
One more rule closes the loop: transformations don't launder trust. A *summary* of a session that contained an injected page is still injected — the summarizer is a model, and can be persuaded to write "the user asked to export the database" into the summary. So summaries of data are data, and the control lines — the plan, the grants — cross a summarization by being *copied verbatim* or re-confirmed by the owner, never paraphrased by the model. Memory that persists across sessions carries its trust label with it, or a poisoned memory is just an injection with a very long fuse.
|
||||
|
||||
## Operations: the rules you feel on Tuesday at 3 a.m.
|
||||
|
||||
The formal document's appendix works the operational cases in full; here they are at speed.
|
||||
|
||||
**The ledger, and the three-way distinction that keeps it honest.** Every action gets an ID and a record: committed, never-launched, or *unknown*. "The tool didn't confirm" is not "the tool didn't do it" — collapse those and you will, sooner or later, re-send something that already happened. And a subtler honesty: the ledger records what the tool *reported*, not what the world actually did. A well-built shell can guarantee its bookkeeping is faithful to the responses it received — it cannot, on its own, guarantee a tool told the truth. A tool that returns a clean "done!" for something it never did puts a clean "done!" in your ledger. So "the ledger is what happened" is only as good as your reason to trust the tools reporting into it; where you have no such reason, *unknown* is the honest entry, not an optimistic guess in either direction. The double-send bug has one reliable cure: **journal before dispatch.** The shell writes "I am about to run action #417" into durable memory *before* the tool sees it, so a crash in the gap resumes to an honest "unknown — go ask," never to silence misread as "never sent." Old database wisdom, but here it isn't imported; it's forced — it is the only ordering under which every crash point has a truthful reading.
|
||||
|
||||
**Crashes aren't finishes.** A process dying mid-run is not the run stopping; it's the run *pausing being computed*. Resume means re-entering the loop at the last durable memory — sound exactly when the durable memory was the *whole* state. Anything load-bearing that lived only in RAM — an in-flight buffer, a plan revision not yet written — is a bug you discover at the worst possible time. Recovery is where you find out whether your state was really your state. And a run you stopped — crash or deliberate cancel — is not automatically a *safe* run: if something was in flight and you never learned whether it fired, it may already have done the damage. "We stopped in time" is only true when everything in flight resolved to something safe; an outstanding *unknown* has to be treated as possibly-bad, the same optimism the ledger warns against, one level up.
|
||||
|
||||
**Two innocent actions can be guilty together.** Models emit several tool calls per turn. "Read the secret" passes review. "Post to the web" passes review. The pair is an exfiltration channel — so the gate authorizes the *set*, atomically, with the interactions checked, not each element in isolation.
|
||||
|
||||
**Sub-agents are just fancy tools.** An agent that spawns another agent is, from the parent's chair, calling a tool: the spawn is gated, the budget is part of the deal, and the child's whole run comes back as one result carrying the child's ledger. Two laws travel down the tree: budgets subdivide, and **authority only narrows** — a child holds at most a subset of its parent's permissions, and a child's request beyond those grants routes *up*, ultimately to the owner, because a parent inventing an approval it never held is the tricked-judge case wearing a manager's badge. A corollary worth framing: a *fully autonomous* run is one whose owner is unreachable — meaning the only channel that can ever widen anything is closed, and its permissions are frozen at launch. That is not a limitation of the theory. That is what the word "autonomous" costs.
|
||||
|
||||
**Keep the originals.** When the transcript outgrows the prompt and you summarize it down, deleting the original is an irreversible act against your own state — and irreversible acts are gate decisions, self-directed or not. Keep originals content-addressed; let the summary be an index, re-derivable, auditable. A summary you can check against its source is a note. A summary that replaced its source is a fait accompli.
|
||||
|
||||
## Robots that never clock out — and robots that assign their own work
|
||||
|
||||
Everything so far assumed a job that *ends*: you ask, the robot does it, you read the result. Two steps past that are where the interesting failures live, and they're the same idea one level bigger each time.
|
||||
|
||||
**The robot that never clocks out (a daemon).** A monitor, a coordinator, a service — it isn't supposed to finish; it's supposed to keep going, wake on events, do a bit of work, go back to waiting. The clean way to think about it: each wake-work-rest cycle is one ordinary run, and the daemon is just those runs chained end to end forever. That reframing is free — but it comes with a bill nobody likes. **Safety that's fine per cycle rots over many cycles.** A 99.99%-safe cycle sounds bulletproof; run it ten thousand times and you're at about a coin-flip of having touched the danger zone at least once. So a long-running robot's safety isn't a fixed wall, it's a slow leak — which means the antidote isn't a better wall, it's *scheduled resets*: the owner re-confirming, credentials rotating, memory getting audited and re-summarized against the originals. Housekeeping isn't housekeeping; it's the thing that keeps the safety math from decaying. And the slow-leak logic is exactly where slow attacks live — a poisoned note dropped into memory on Monday and read back into the plan on Friday is an injection with a long fuse. So the trust label on a piece of information has to survive across cycles, not just within one. One more wrinkle: a daemon drifts in and out of your reach. While you're around, it can escalate to you; while you're not, "escalate to the owner" isn't available — so the one thing it must always be able to do instead is *stop*. A robot that can be tricked into refusing everything, and can't reach you, had better be able to halt rather than be steered.
|
||||
|
||||
**The robot that assigns its own work (the loop).** Step back one more time. Above the robot that *does* a task sits a system that decides *which task is next* — scans the backlog, picks one, launches the robot at it, checks the result, remembers, fires again. This is the thing people mean in 2026 when they say they've stopped prompting their agents and started writing *loops* that prompt them: you design the assigner once, and it runs the doer for you while you sleep. The honest observation — and the reason this document bothers with it — is that the assigner is *not a new kind of thing*. It's the same harness, one level up: it has its own memory (the backlog), its own gate (**who let the loop refactor the auth module at 3 a.m.?**), its own verifier, and its own two walls. Every rule from the inner robot recurs on the outer one — including the uncomfortable ones. There's still no proof it stays out of trouble over a long night; there's only a measured progress meter, with the same catch that a *learned* meter can be fooled. And the origin story of the whole trend is the cautionary case in miniature: the famous first version was literally the same prompt in a `while` loop until the tests passed — which is the empty gate, the always-open lock, one level up. It works beautifully right up until the tests weren't checking the thing that mattered. The loop doesn't delete the hard problems. It moves them up a floor, where they're bigger and you're further away.
|
||||
|
||||
The pattern, if you want the whole thing in one line: *words, context, robot, loop* are four sizes of the same object, and every promise in this document lives in the whole assembled thing — never in any one layer by itself.
|
||||
|
||||
## The two walls
|
||||
|
||||
Two limits are structural. You don't fix them with a better harness; you design around them.
|
||||
|
||||
**The desk.** The model can hold only so much *in mind at once* — the context window. Files, databases, and search extend what it can *look up*, not what it can hold: every lookup still passes through the same small window to touch actual computation. The shell can page; the model cannot grow its desk. Tasks whose irreducible working set exceeds the desk don't fail loudly — they fail by forgetting the middle (the well-documented "lost in the middle" effect is this wall showing through the paint).
|
||||
|
||||
**The dictionary.** The model's knowledge is frozen into its parameters at training time — and the proof problem above is conjectured to live at that same scale: the certificate wouldn't fit anywhere smaller than the brain it certifies. The two walls trade against each other along the training-versus-inference axis — bigger dictionary or bigger desk — directionally, and at no clean exchange rate.
|
||||
|
||||
## How this could be wrong
|
||||
|
||||
This is a hypothesis, and it says out loud what would kill it. The tests, in plain terms:
|
||||
|
||||
- **The replay test.** Rerun with model answers and tool results pinned. Any leftover variation — timestamps, wall-clocks, and cache expiries are the classic leaks — falsifies "the harness adds no randomness" until accounted for.
|
||||
- **The drop-a-variable test.** Remove something from memory; if behavior statistics shift, the memory wasn't complete. The crash-resume version of the same test: if resuming from saved state breaks, the saved state wasn't the state.
|
||||
- **Does the meter mean anything?** If no reasonable progress meter's drift predicts real failures — across the natural families, not just one bad candidate — the whole "measure what you can't prove" program is empty.
|
||||
- **The red-team test.** Swap sampled tool outputs for worst-case ones: injected pages, poisoned metadata, malformed replies. The design must survive the worst permitted world, not the average one.
|
||||
- **Gates versus begging.** The theory predicts deterministic gating beats prompt-level pleading. If "please be careful" alone matches real gates on security outcomes, the controller-versus-model story is wrong.
|
||||
- **The compression hunt.** Exhibit a compact, provably sound progress certificate for a frontier-scale model on a nontrivial task family, and the central conjecture falls — constructively.
|
||||
- **The desk probe.** Take a task family with a *proven* memory floor — so "it needed the whole picture at once" is someone else's theorem, not our excuse — scale it past the window, and watch: the wall predicts a *ceiling*, not a cliff — past the boundary, a success rate that stays capped no matter how many retries you buy. A family solved reliably out there, without new shell tricks for splitting the work, kills the wall.
|
||||
|
||||
## Who else landed here
|
||||
|
||||
The formal document keeps three honesty tiers. **Borrowed**: real theorems, cited — the drift and stopping-time mathematics is classical, and the very architecture of a deterministic supervisor gating a plant it didn't author is 1987 control theory; the shape is older than the web. **Ours**: the modeling choices and the conjectures — the walls, the incompressibility claim, the design rules — organizing principles, not results. **Corroborated**: pieces of the same object reached independently by people who never saw this framing — capability-security work isolating control flow from untrusted data (CaMeL), reinforcement-learning "shields" filtering a learned policy's actions through a deterministic checker, verification work that states the "learned safeguards can't certify" gap as its opening motivation, and architecture patterns converging on plan-then-execute. Even the field's live disagreement — provable-but-rigid deterministic layers versus flexible-but-uncertifiable learned checks — is, in this frame, not a fight but a placement: you need both, on their proper sides of the irreversibility line, with the learned one permitted only to tighten.
|
||||
|
||||
## What to remember
|
||||
|
||||
The model proposes; the gate disposes. No is the default, and a refusal must be safe. Only the top of the trust hierarchy widens permissions — a human decision, never the model, a tool result, a summary, or a judge. "Didn't confirm" is not "didn't happen." The desk is finite and the proof doesn't compress, so you measure — and you say *measurement* when you mean measurement. A robot that never stops leaks safety slowly, so it needs scheduled resets — and when it can't reach you, it must be able to stop. A loop that runs robots for you is just a bigger robot with the same rules and a further-away owner. And all of it is a hypothesis wearing its own kill-conditions on its sleeve.
|
||||
|
||||
The formal version — the objects, the certificates, the falsifiers, the citations — is [HYPOTHESIS.md](HYPOTHESIS.md). It wins every disagreement with this file, including this sentence.
|
||||
|
||||
*Same ramblings, fewer symbols.*
|
||||
@@ -5,7 +5,6 @@
|
||||
[](https://pypi.org/project/turnstone/)
|
||||
[](LICENSE)
|
||||
[](https://discord.gg/Nh3bWMacaq)
|
||||
[](https://github.com/sponsors/eous)
|
||||
|
||||
Self-hosted, local-first orchestration for tool-using AI agents. Give LLMs real tools — shell, files, search, web — and run them across your own cluster with direct HTTP routing and interactive interfaces. Your code, your models, your data stay on hardware you control: no telemetry, no phone-home.
|
||||
|
||||
@@ -17,17 +16,11 @@ Named after the [Ruddy Turnstone](https://en.wikipedia.org/wiki/Ruddy_turnstone)
|
||||
|
||||
**What is a harness?**
|
||||
|
||||
<p align="center">
|
||||
<a href="https://media.githubusercontent.com/media/turnstonelabs/turnstone/main/docs/diagrams/harness.png">
|
||||
<img src="https://media.githubusercontent.com/media/turnstonelabs/turnstone/main/docs/diagrams/harness.png" alt="ℋ : s_{n+1} ~ T(s_n) for n < τ_H — the whole controlled loop: π lowers state to context, M_W proposes a readout, γ authorizes it, Q_E acts on the world, ρ verifies and folds back" width="960"/>
|
||||
</a>
|
||||
</p>
|
||||
|
||||
```
|
||||
ℋ : s_{n+1} ~ T(s_n) for n < τ_H
|
||||
ℋ : s_{n+1} ~ T(s_n) for n < τ*, T = ρ ∘ (M_W ∘ π, E)
|
||||
```
|
||||
|
||||
[**the primer →**](PRIMER.md) · [**the formalism →**](HYPOTHESIS.md)
|
||||
[**the hypothesis →**](HYPOTHESIS.md)
|
||||
|
||||
### Release Tracks
|
||||
|
||||
@@ -178,14 +171,6 @@ UML diagrams in [`docs/diagrams/`](docs/diagrams/):
|
||||
- Optional: Discord / Slack channel integrations (`pip install turnstone[discord,slack]`)
|
||||
- [Git LFS](https://git-lfs.com/) for cloning (diagram PNGs)
|
||||
|
||||
## Support
|
||||
|
||||
Turnstone is free, Apache-2.0, and self-hosted — no paid tier, no telemetry, no upsell. If it saves you time or you'd like to help keep development moving, you can sponsor the project:
|
||||
|
||||
**[❤ Sponsor Turnstone →](https://github.com/sponsors/eous)** · one-off via **[PayPal](https://paypal.me/eousphoros)**
|
||||
|
||||
Sponsorship is entirely optional and funds maintenance, new features, and infrastructure. Prefer to contribute in other ways? Filing issues, improving docs, and [pull requests](CONTRIBUTING.md) help just as much.
|
||||
|
||||
## Community
|
||||
|
||||
Questions, ideas, or want to show what you're building? Join us on Discord:
|
||||
|
||||
+5
-14
@@ -53,9 +53,8 @@
|
||||
# The node registers in Postgres, auto-enrolls its mTLS cert from the console's
|
||||
# ACME endpoint (when the cluster runs mTLS), and the console collector reaches
|
||||
# it back via host.docker.internal. To join from ANOTHER machine, set
|
||||
# TURNSTONE_HOST_IP to this host's LAN IP and set TURNSTONE_ACME_EXTERNAL_URL to
|
||||
# http://<this-host-ip>:8090/acme. Use the same host IP in the node's URLs above
|
||||
# (and the NODE host's IP in TURNSTONE_ADVERTISE_URL) — see docs/docker.md.
|
||||
# TURNSTONE_HOST_IP to this host's LAN IP and use it in the URLs above (and the
|
||||
# node's TURNSTONE_ADVERTISE_URL = the NODE host's IP) — see docs/docker.md.
|
||||
# =============================================================================
|
||||
|
||||
name: turnstone
|
||||
@@ -155,11 +154,9 @@ services:
|
||||
# Publishes the console's plain-HTTP listener so a bare-metal node can reach
|
||||
# the ACME endpoint, fetch the CA, and enroll its cert (the console serves
|
||||
# HTTP here even under mTLS). Bound to 127.0.0.1 by default; setting
|
||||
# TURNSTONE_HOST_IP exposes the WHOLE console HTTP API on that interface.
|
||||
# ACME signing routes require a dedicated short-lived service JWT, but the
|
||||
# listener and bearer token are still plain HTTP: bind only a trusted LAN
|
||||
# or VPN interface and restrict it to enrolling nodes. Browsers use Caddy
|
||||
# :8443, never this port.
|
||||
# TURNSTONE_HOST_IP exposes the WHOLE console HTTP API — including the
|
||||
# cert-issuing ACME endpoint — on that interface, so the JWT secret's
|
||||
# strength is the only gate. Browsers use Caddy :8443, never this port.
|
||||
ports:
|
||||
- "${TURNSTONE_HOST_IP:-127.0.0.1}:8090:8090"
|
||||
environment:
|
||||
@@ -167,9 +164,6 @@ services:
|
||||
TURNSTONE_DB_BACKEND: *db-backend
|
||||
TURNSTONE_DB_URL: *db-url
|
||||
TURNSTONE_CONSOLE_URL: http://console:8090
|
||||
# Separate from TURNSTONE_CONSOLE_URL: this is the canonical responder
|
||||
# base embedded in ACME directory/order URLs for cross-host enrollment.
|
||||
TURNSTONE_ACME_EXTERNAL_URL: "${TURNSTONE_ACME_EXTERNAL_URL:-}"
|
||||
extra_hosts:
|
||||
- "host.docker.internal:host-gateway"
|
||||
networks:
|
||||
@@ -311,9 +305,6 @@ services:
|
||||
SKIP_PERMISSIONS: ${SKIP_PERMISSIONS:-}
|
||||
TURNSTONE_NODE_ID: node-1
|
||||
TURNSTONE_ADVERTISE_URL: http://node-1:8080
|
||||
# Lets the authenticated ACME client follow the console's canonical LAN
|
||||
# URLs without trusting destinations learned from the public directory.
|
||||
TURNSTONE_ACME_EXTERNAL_URL: "${TURNSTONE_ACME_EXTERNAL_URL:-}"
|
||||
extra_hosts:
|
||||
- "host.docker.internal:host-gateway"
|
||||
networks:
|
||||
|
||||
@@ -38,18 +38,10 @@ services:
|
||||
condition: service_completed_successfully
|
||||
volumes:
|
||||
- tls-certs:/certs:ro
|
||||
# The production base keeps :8090 private. The TLS overlay publishes it on
|
||||
# localhost for same-host enrollment; use a trusted LAN/VPN address for a
|
||||
# remote node and firewall it to that node.
|
||||
ports:
|
||||
- "${TURNSTONE_CONSOLE_HTTP_BIND:-127.0.0.1}:8090:8090"
|
||||
environment:
|
||||
TURNSTONE_TLS_ENABLED: "true"
|
||||
TURNSTONE_TLS_SANS: "console"
|
||||
TURNSTONE_CONSOLE_URL: "http://console:8090"
|
||||
# Canonical ACME responder base advertised to enrolling nodes. Set this
|
||||
# when they reach the console through a different host/address.
|
||||
TURNSTONE_ACME_EXTERNAL_URL: "${TURNSTONE_ACME_EXTERNAL_URL:-}"
|
||||
command:
|
||||
- turnstone-console
|
||||
- --host=0.0.0.0
|
||||
@@ -66,7 +58,11 @@ services:
|
||||
environment:
|
||||
TURNSTONE_TLS_ENABLED: "true"
|
||||
TURNSTONE_TLS_SANS: "server"
|
||||
TURNSTONE_ACME_EXTERNAL_URL: "${TURNSTONE_ACME_EXTERNAL_URL:-}"
|
||||
# Disable healthcheck — server serves HTTPS with mTLS which the
|
||||
# stdlib healthcheck script can't satisfy. The base compose
|
||||
# healthcheck uses plain HTTP which won't work on an HTTPS listener.
|
||||
healthcheck:
|
||||
disable: true
|
||||
|
||||
# Channel: TLS
|
||||
channel:
|
||||
|
||||
@@ -2,11 +2,11 @@ apiVersion: v2
|
||||
name: turnstone
|
||||
description: Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation
|
||||
type: application
|
||||
version: 0.2.0
|
||||
version: 0.1.0
|
||||
appVersion: "0.3.0"
|
||||
|
||||
dependencies:
|
||||
- name: postgresql
|
||||
version: ~18.8.0
|
||||
version: ~18.7.0
|
||||
repository: https://charts.bitnami.com/bitnami
|
||||
condition: postgresql.enabled
|
||||
|
||||
@@ -110,153 +110,6 @@ Determine the PostgreSQL username.
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{/*
|
||||
The PostgreSQL password when the chart stores it itself, empty when it
|
||||
does not. Doubles as the predicate for "does <fullname>-secrets need to
|
||||
carry POSTGRES_PASSWORD", so an inline password is never written
|
||||
anywhere but <fullname>-secrets, and an operator-supplied Secret is
|
||||
never duplicated into it.
|
||||
|
||||
An operator-supplied existingSecret wins outright: writing the value
|
||||
into a second Secret nothing reads would only duplicate a credential.
|
||||
|
||||
Both branches need "default" because this is reached through include,
|
||||
which captures rendered text rather than a value: a key that is unset
|
||||
rather than empty — "password:" with nothing after it — renders as the
|
||||
literal "<no value>", and a ten-character string is truthy. Without the
|
||||
default that lands base64-encoded in POSTGRES_PASSWORD and the workloads
|
||||
authenticate with it.
|
||||
*/}}
|
||||
{{- define "turnstone.db.inlinePassword" -}}
|
||||
{{- if .Values.postgresql.enabled }}
|
||||
{{- .Values.postgresql.auth.password | default "" }}
|
||||
{{- else if not .Values.database.external.existingSecret }}
|
||||
{{- .Values.database.external.password | default "" }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{/*
|
||||
The name of the bundled subchart's own Secret.
|
||||
|
||||
Mirrors the subchart's naming rather than calling its helpers, which
|
||||
expect a context scoped to the subchart that this chart cannot hand
|
||||
them. Release-derived, so deliberately not turnstone.fullname: a
|
||||
fullnameOverride here renames this chart's resources and leaves the
|
||||
subchart's alone, and pointing at "<fullname>-postgresql" would then
|
||||
name a Secret that does not exist.
|
||||
|
||||
The subchart also normalises the release name through a regex before
|
||||
using it, which is a no-op for the DNS-1123 names Helm accepts, so it is
|
||||
not reproduced.
|
||||
*/}}
|
||||
{{- define "turnstone.postgresql.fullname" -}}
|
||||
{{- $global := ((.Values.global).postgresql).fullnameOverride }}
|
||||
{{- if $global }}
|
||||
{{- $global | trunc 63 | trimSuffix "-" }}
|
||||
{{- else if .Values.postgresql.fullnameOverride }}
|
||||
{{- .Values.postgresql.fullnameOverride | trunc 63 | trimSuffix "-" }}
|
||||
{{- else }}
|
||||
{{- $name := .Values.postgresql.nameOverride | default "postgresql" }}
|
||||
{{- if contains $name .Release.Name }}
|
||||
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
|
||||
{{- else }}
|
||||
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{- define "turnstone.postgresql.secretName" -}}
|
||||
{{- $existing := coalesce (((.Values.global).postgresql).auth).existingSecret .Values.postgresql.auth.existingSecret }}
|
||||
{{- if $existing }}
|
||||
{{- tpl $existing . }}
|
||||
{{- else }}
|
||||
{{- include "turnstone.postgresql.fullname" . }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{/*
|
||||
The subchart stores the named user's password under "password" and the
|
||||
superuser's under "postgres-password", and lets an operator rename
|
||||
either through auth.secretKeys.
|
||||
*/}}
|
||||
{{- define "turnstone.postgresql.passwordKey" -}}
|
||||
{{- $user := .Values.postgresql.auth.username | default "" }}
|
||||
{{- $keys := .Values.postgresql.auth.secretKeys | default dict }}
|
||||
{{- if or (empty $user) (eq $user "postgres") }}
|
||||
{{- $keys.adminPasswordKey | default "postgres-password" }}
|
||||
{{- else }}
|
||||
{{- $keys.userPasswordKey | default "password" }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{/*
|
||||
Determine the secret holding the PostgreSQL password, and the key within
|
||||
it. Three sources, and the two helpers agree by construction because
|
||||
they branch identically:
|
||||
|
||||
- an external database pointed at a Secret the chart does not own (a
|
||||
CloudNativePG-generated secret, an External Secrets target, ...), in
|
||||
which case the key is rarely "POSTGRES_PASSWORD" — hence the
|
||||
companion existingSecretPasswordKey
|
||||
- the bundled subchart's own Secret, when it generates the password
|
||||
- <fullname>-secrets, when the password is supplied inline in values
|
||||
|
||||
Note the last is deliberately not turnstone.llm.secretName: that
|
||||
resolves to llm.existingSecret when the operator supplies one, which
|
||||
holds LLM API keys and has no reason to carry a database password.
|
||||
*/}}
|
||||
{{- define "turnstone.db.secretName" -}}
|
||||
{{- if not .Values.postgresql.enabled }}
|
||||
{{- if .Values.database.external.existingSecret }}
|
||||
{{- .Values.database.external.existingSecret }}
|
||||
{{- else }}
|
||||
{{- printf "%s-secrets" (include "turnstone.fullname" .) }}
|
||||
{{- end }}
|
||||
{{- else if include "turnstone.db.inlinePassword" . }}
|
||||
{{- printf "%s-secrets" (include "turnstone.fullname" .) }}
|
||||
{{- else }}
|
||||
{{- include "turnstone.postgresql.secretName" . }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{- define "turnstone.db.passwordKey" -}}
|
||||
{{- if not .Values.postgresql.enabled }}
|
||||
{{- if .Values.database.external.existingSecret }}
|
||||
{{- .Values.database.external.existingSecretPasswordKey | default "password" }}
|
||||
{{- else }}
|
||||
{{- printf "POSTGRES_PASSWORD" }}
|
||||
{{- end }}
|
||||
{{- else if include "turnstone.db.inlinePassword" . }}
|
||||
{{- printf "POSTGRES_PASSWORD" }}
|
||||
{{- else }}
|
||||
{{- include "turnstone.postgresql.passwordKey" . }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{/*
|
||||
Database environment shared by the server, console and migrate Job.
|
||||
|
||||
Every value except the password is rendered inline rather than pulled
|
||||
from the ConfigMap via envFrom, so that one definition serves all three
|
||||
workloads and the URL is assembled in exactly one place.
|
||||
|
||||
POSTGRES_PASSWORD must still precede TURNSTONE_DB_URL: the kubelet
|
||||
expands $(VAR) only against env entries declared earlier in the list, so
|
||||
a later definition would leave a literal "$(POSTGRES_PASSWORD)" in the
|
||||
URL.
|
||||
*/}}
|
||||
{{- define "turnstone.db.env" -}}
|
||||
- name: TURNSTONE_DB_BACKEND
|
||||
value: {{ .Values.database.backend | quote }}
|
||||
- name: POSTGRES_PASSWORD
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: {{ include "turnstone.db.secretName" . }}
|
||||
key: {{ include "turnstone.db.passwordKey" . }}
|
||||
- name: TURNSTONE_DB_URL
|
||||
value: "postgresql+psycopg://{{ include "turnstone.postgresql.username" . }}:$(POSTGRES_PASSWORD)@{{ include "turnstone.postgresql.host" . }}:{{ include "turnstone.postgresql.port" . }}/{{ include "turnstone.postgresql.database" . }}{{ if and (not .Values.postgresql.enabled) .Values.database.external.sslmode }}?sslmode={{ .Values.database.external.sslmode }}{{ end }}"
|
||||
{{- end }}
|
||||
|
||||
{{/*
|
||||
Determine the secret name for LLM API keys.
|
||||
*/}}
|
||||
|
||||
@@ -7,17 +7,6 @@ metadata:
|
||||
app.kubernetes.io/component: console
|
||||
spec:
|
||||
replicas: {{ .Values.console.replicas }}
|
||||
{{- if eq (int .Values.console.replicas) 1 }}
|
||||
# The console registers itself under the fixed service_id "console" and
|
||||
# deregisters on shutdown. Under RollingUpdate the outgoing pod's
|
||||
# deregister runs *after* the incoming pod registers and deletes its
|
||||
# row -- and the heartbeat only touches last_heartbeat, so the row is
|
||||
# never recreated and the console stays invisible in the registry until
|
||||
# the next clean start. Recreate orders shutdown strictly before
|
||||
# startup. Only valid at one replica; see console.replicas.
|
||||
strategy:
|
||||
type: Recreate
|
||||
{{- end }}
|
||||
selector:
|
||||
matchLabels:
|
||||
{{- include "turnstone.selectorLabels" . | nindent 6 }}
|
||||
@@ -29,18 +18,6 @@ spec:
|
||||
app.kubernetes.io/component: console
|
||||
spec:
|
||||
serviceAccountName: {{ include "turnstone.serviceAccountName" . }}
|
||||
{{- with .Values.console.nodeSelector }}
|
||||
nodeSelector:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.console.affinity }}
|
||||
affinity:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.console.tolerations }}
|
||||
tolerations:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
containers:
|
||||
- name: console
|
||||
image: {{ include "turnstone.image" . }}
|
||||
@@ -59,18 +36,8 @@ spec:
|
||||
- secretRef:
|
||||
name: {{ include "turnstone.llm.secretName" . }}
|
||||
optional: true
|
||||
env:
|
||||
{{- include "turnstone.db.env" . | nindent 12 }}
|
||||
# Self-registration URL for the service registry. Unlike a
|
||||
# server node the console is one logical endpoint behind its
|
||||
# Service, so the Service DNS name is correct here. Without
|
||||
# it the console registers gethostname() (its pod name),
|
||||
# which no server node can resolve. Stops at ".svc" rather
|
||||
# than assuming a "cluster.local" DNS domain, which is
|
||||
# configurable per cluster.
|
||||
- name: TURNSTONE_CONSOLE_URL
|
||||
value: "http://{{ include "turnstone.fullname" . }}-console.{{ .Release.Namespace }}.svc:{{ .Values.console.service.port }}"
|
||||
{{- if or .Values.auth.existingSecret .Values.auth.jwtSecret }}
|
||||
env:
|
||||
- name: TURNSTONE_JWT_SECRET
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
|
||||
@@ -18,18 +18,6 @@ spec:
|
||||
app.kubernetes.io/component: server
|
||||
spec:
|
||||
serviceAccountName: {{ include "turnstone.serviceAccountName" . }}
|
||||
{{- with .Values.server.nodeSelector }}
|
||||
nodeSelector:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.server.affinity }}
|
||||
affinity:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.server.tolerations }}
|
||||
tolerations:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
containers:
|
||||
- name: server
|
||||
image: {{ include "turnstone.image" . }}
|
||||
@@ -51,20 +39,8 @@ spec:
|
||||
name: {{ include "turnstone.llm.secretName" . }}
|
||||
optional: true
|
||||
env:
|
||||
{{- include "turnstone.db.env" . | nindent 12 }}
|
||||
# Each replica is a distinct node in the rendezvous ring, so it
|
||||
# must advertise an address that reaches *itself*. The Service
|
||||
# DNS name would load-balance across every replica, sending
|
||||
# console traffic routed for node A to an arbitrary pod; the
|
||||
# default (gethostname(), i.e. the pod name) is not resolvable
|
||||
# at all. The pod IP is unique, routable in-cluster, and
|
||||
# re-registered on every start, so churn is self-healing.
|
||||
- name: POD_IP
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: status.podIP
|
||||
- name: TURNSTONE_ADVERTISE_URL
|
||||
value: "http://$(POD_IP):{{ .Values.server.service.port }}"
|
||||
- name: TURNSTONE_DB_URL
|
||||
value: "postgresql+psycopg://$(TURNSTONE_DB_USER):$(POSTGRES_PASSWORD)@$(TURNSTONE_DB_HOST):$(TURNSTONE_DB_PORT)/$(TURNSTONE_DB_NAME)"
|
||||
{{- if or .Values.auth.existingSecret .Values.auth.jwtSecret }}
|
||||
- name: TURNSTONE_JWT_SECRET
|
||||
valueFrom:
|
||||
|
||||
@@ -6,23 +6,11 @@ metadata:
|
||||
{{- include "turnstone.labels" . | nindent 4 }}
|
||||
app.kubernetes.io/component: migrate
|
||||
annotations:
|
||||
# post-install, not pre-install: on a first install nothing the
|
||||
# migration needs exists yet — not the ConfigMap, not the Secret, and
|
||||
# with the bundled subchart not the database either, since Helm
|
||||
# creates ordinary resources only once hooks have finished. On an
|
||||
# upgrade all of it is already running, so pre-upgrade is both safe
|
||||
# and preferable: migrations land before the new code rolls out
|
||||
# rather than after.
|
||||
"helm.sh/hook": post-install,pre-upgrade
|
||||
"helm.sh/hook": pre-install,pre-upgrade
|
||||
"helm.sh/hook-weight": "-1"
|
||||
"helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
|
||||
spec:
|
||||
# Helm does not wait for the database to be ready before running
|
||||
# post-install hooks, so on a first install this Job is what waits: it
|
||||
# exits non-zero until PostgreSQL accepts connections, and the retry
|
||||
# budget has to cover a cold StatefulSet pulling its image and
|
||||
# initialising.
|
||||
backoffLimit: 10
|
||||
backoffLimit: 3
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
@@ -31,18 +19,6 @@ spec:
|
||||
spec:
|
||||
serviceAccountName: {{ include "turnstone.serviceAccountName" . }}
|
||||
restartPolicy: OnFailure
|
||||
{{- with .Values.migrate.nodeSelector }}
|
||||
nodeSelector:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.migrate.affinity }}
|
||||
affinity:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
{{- with .Values.migrate.tolerations }}
|
||||
tolerations:
|
||||
{{- toYaml . | nindent 8 }}
|
||||
{{- end }}
|
||||
containers:
|
||||
- name: migrate
|
||||
image: {{ include "turnstone.image" . }}
|
||||
@@ -51,5 +27,12 @@ spec:
|
||||
- python
|
||||
- -m
|
||||
- turnstone.core.storage._migrate
|
||||
envFrom:
|
||||
- configMapRef:
|
||||
name: {{ include "turnstone.fullname" . }}-config
|
||||
- secretRef:
|
||||
name: {{ include "turnstone.llm.secretName" . }}
|
||||
optional: true
|
||||
env:
|
||||
{{- include "turnstone.db.env" . | nindent 12 }}
|
||||
- name: TURNSTONE_DB_URL
|
||||
value: "postgresql+psycopg://$(TURNSTONE_DB_USER):$(POSTGRES_PASSWORD)@$(TURNSTONE_DB_HOST):$(TURNSTONE_DB_PORT)/$(TURNSTONE_DB_NAME)"
|
||||
|
||||
@@ -1,19 +1,4 @@
|
||||
{{/*
|
||||
This Secret backs every credential supplied inline in values, so it is
|
||||
rendered whenever any one of them is set — not, as it once was, only
|
||||
when llm.existingSecret is empty. Under that older gate an operator who
|
||||
supplied an LLM Secret lost the unrelated inline values with it: both
|
||||
POSTGRES_PASSWORD and TURNSTONE_JWT_SECRET silently went unrendered
|
||||
while the workloads went on referencing them, so every pod stalled in
|
||||
CreateContainerConfigError.
|
||||
|
||||
Each key keeps its own condition, so an operator-supplied Secret still
|
||||
suppresses the value it replaces and nothing else.
|
||||
*/}}
|
||||
{{- $apiKey := and .Values.llm.apiKey (not .Values.llm.existingSecret) }}
|
||||
{{- $dbPassword := include "turnstone.db.inlinePassword" . }}
|
||||
{{- $jwtSecret := and .Values.auth.jwtSecret (not .Values.auth.existingSecret) }}
|
||||
{{- if or $apiKey $dbPassword $jwtSecret }}
|
||||
{{- if not .Values.llm.existingSecret }}
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
@@ -22,13 +7,15 @@ metadata:
|
||||
{{- include "turnstone.labels" . | nindent 4 }}
|
||||
type: Opaque
|
||||
data:
|
||||
{{- if $apiKey }}
|
||||
{{- if .Values.llm.apiKey }}
|
||||
OPENAI_API_KEY: {{ .Values.llm.apiKey | b64enc | quote }}
|
||||
{{- end }}
|
||||
{{- if $dbPassword }}
|
||||
POSTGRES_PASSWORD: {{ $dbPassword | b64enc | quote }}
|
||||
{{- if and .Values.postgresql.enabled .Values.postgresql.auth.password }}
|
||||
POSTGRES_PASSWORD: {{ .Values.postgresql.auth.password | b64enc | quote }}
|
||||
{{- else if and (not .Values.postgresql.enabled) .Values.database.external.password }}
|
||||
POSTGRES_PASSWORD: {{ .Values.database.external.password | b64enc | quote }}
|
||||
{{- end }}
|
||||
{{- if $jwtSecret }}
|
||||
{{- if and .Values.auth.jwtSecret (not .Values.auth.existingSecret) }}
|
||||
TURNSTONE_JWT_SECRET: {{ .Values.auth.jwtSecret | b64enc | quote }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
@@ -14,13 +14,7 @@ database:
|
||||
port: 5432
|
||||
database: turnstone
|
||||
username: turnstone
|
||||
# Secret holding the password for `username`. Leave empty to supply
|
||||
# `password` inline below instead.
|
||||
existingSecret: ""
|
||||
# Key within existingSecret holding the password. CloudNativePG
|
||||
# generates "password"; other operators differ.
|
||||
existingSecretPasswordKey: password
|
||||
password: ""
|
||||
sslmode: prefer
|
||||
|
||||
# -- Bitnami PostgreSQL subchart
|
||||
@@ -43,10 +37,6 @@ server:
|
||||
service:
|
||||
type: ClusterIP
|
||||
port: 8080
|
||||
# -- Node scheduling constraints
|
||||
nodeSelector: {}
|
||||
affinity: {}
|
||||
tolerations: []
|
||||
|
||||
# -- Turnstone console (cluster dashboard)
|
||||
console:
|
||||
@@ -61,17 +51,6 @@ console:
|
||||
service:
|
||||
type: ClusterIP
|
||||
port: 8090
|
||||
# -- Node scheduling constraints
|
||||
nodeSelector: {}
|
||||
affinity: {}
|
||||
tolerations: []
|
||||
|
||||
# -- Database migration Job (post-install/pre-upgrade hook)
|
||||
migrate:
|
||||
# -- Node scheduling constraints
|
||||
nodeSelector: {}
|
||||
affinity: {}
|
||||
tolerations: []
|
||||
|
||||
# -- LLM provider configuration
|
||||
llm:
|
||||
|
||||
@@ -15,14 +15,11 @@ counterpart to the quick `turnstone-server …` invocation in
|
||||
## Cluster-side prerequisite
|
||||
|
||||
The compose stack must publish Postgres, the console's ACME endpoint, and SearxNG
|
||||
on an address the bare-metal host can reach. Use a trusted LAN or VPN interface,
|
||||
firewall it to the joining node, and advertise the same reachable ACME endpoint
|
||||
(default `127.0.0.1` keeps everything host-local):
|
||||
on an address the bare-metal host can reach. Start it with `TURNSTONE_HOST_IP`
|
||||
set to the compose host's LAN IP (default `127.0.0.1` keeps everything host-local):
|
||||
|
||||
```bash
|
||||
TURNSTONE_HOST_IP=<compose-host-ip> \
|
||||
TURNSTONE_ACME_EXTERNAL_URL=http://<compose-host-ip>:8090/acme \
|
||||
docker compose up -d
|
||||
TURNSTONE_HOST_IP=<compose-host-ip> docker compose up -d
|
||||
```
|
||||
|
||||
## Install (run as root on the bare-metal host)
|
||||
@@ -68,20 +65,8 @@ journalctl -u turnstone-server -f # watch it register + (if the cluster
|
||||
shared settings (the database). If the cluster runs mTLS, the node auto-enrolls a
|
||||
cert from the console's ACME endpoint and re-advertises itself over `https://`.
|
||||
|
||||
For a node on a different host, `TURNSTONE_ACME_EXTERNAL_URL` is required on the
|
||||
console and should also be set in the node drop-in. It is the full, externally
|
||||
reachable responder base
|
||||
(including `/acme`) that the console embeds in the ACME protocol's follow-up
|
||||
URLs and that the node trusts as an enrollment-credential destination. The
|
||||
node's `TURNSTONE_CONSOLE_URL` should point at the same host and port, without
|
||||
the `/acme` suffix.
|
||||
|
||||
For mTLS, `TURNSTONE_ADVERTISE_URL` may use a resolvable DNS hostname or a
|
||||
literal IP address. Turnstone enrolls literals as IP SANs. Bracket IPv6 literals
|
||||
inside URLs, for example `http://[2001:db8::10]:8080`; do not use wildcard,
|
||||
unspecified, or scoped addresses as certificate identities. Restart the node
|
||||
after changing its advertised identity so it enrolls a matching certificate.
|
||||
|
||||
The dedicated service JWT authenticates enrollment but the direct `:8090`
|
||||
bootstrap is still plain HTTP/TOFU. Use HTTPS through an independently trusted
|
||||
proxy when the network itself is not trusted.
|
||||
> **mTLS + cross-host caveat:** a node on a *different* host than the console
|
||||
> currently can't complete ACME enrollment — the console advertises an
|
||||
> unroutable in-container address in its ACME directory
|
||||
> ([turnstonelabs/lacme#22](https://github.com/turnstonelabs/lacme/issues/22)).
|
||||
> Same-host bare-metal nodes, and any node in a non-mTLS cluster, are unaffected.
|
||||
|
||||
@@ -4,20 +4,16 @@
|
||||
# they live here; the JWT secret + DB URL live in /etc/turnstone/config.toml.
|
||||
#
|
||||
# Addresses below use RFC 5737 documentation IPs — replace them:
|
||||
# <this-host> = the bare-metal host's own reachable DNS name or IP address
|
||||
# (its mTLS identity and the address peers dial)
|
||||
# <this-host> = the bare-metal host's own LAN IP (what the console dials back)
|
||||
# <compose-host> = the host running the cluster / docker-compose stack, started
|
||||
# with TURNSTONE_HOST_IP=<compose-host> and
|
||||
# TURNSTONE_ACME_EXTERNAL_URL=http://<compose-host>:8090/acme
|
||||
# so enrollment links and published ports are reachable
|
||||
# (see docs/docker.md).
|
||||
# with TURNSTONE_HOST_IP=<compose-host> so :8090 and :8081 are
|
||||
# published on its LAN interface (see docs/docker.md).
|
||||
[Service]
|
||||
# Unique node id (defaults to the hostname if unset).
|
||||
Environment=TURNSTONE_NODE_ID=host-1
|
||||
|
||||
# The address peers + the console collector dial back. Auto-upgrades to https://
|
||||
# once the node enrolls its mTLS cert. IPv6 literals require URL brackets, for
|
||||
# example http://[2001:db8::10]:8080.
|
||||
# once the node enrolls its mTLS cert.
|
||||
Environment=TURNSTONE_ADVERTISE_URL=http://192.0.2.10:8080
|
||||
|
||||
# The cluster console's reachable plain-HTTP ACME/API endpoint. A bare-metal node
|
||||
@@ -25,9 +21,5 @@ Environment=TURNSTONE_ADVERTISE_URL=http://192.0.2.10:8080
|
||||
# port; turnstone-server honors this for cert enrollment.
|
||||
Environment=TURNSTONE_CONSOLE_URL=http://192.0.2.1:8090
|
||||
|
||||
# Trusted canonical responder base. This pins where the node may send its
|
||||
# enrollment JWT; it must match the console-side value (a literal IP is fine).
|
||||
Environment=TURNSTONE_ACME_EXTERNAL_URL=http://192.0.2.1:8090/acme
|
||||
|
||||
# The cluster's published SearxNG, for the web_search tool.
|
||||
Environment=TURNSTONE_SEARXNG_URL=http://192.0.2.1:8081
|
||||
|
||||
+157
-672
File diff suppressed because it is too large
Load Diff
+248
-743
File diff suppressed because it is too large
Load Diff
+16
-22
@@ -195,17 +195,13 @@ both and the gateway hosts both adapters in one process.
|
||||
- All subsequent messages in the thread are routed to the same workstream.
|
||||
- The bot streams responses via message edits, updated approximately every
|
||||
1.5 seconds.
|
||||
- If a persisted channel route is no longer active on its owning node, the
|
||||
router asks the create endpoint to fork the old workstream into a new ID via
|
||||
`resume_ws`. The saved source can still resolve normally; its
|
||||
checkpoint-bounded history, configuration, persona, effective project, and
|
||||
attachment references are cloned before the channel route is repointed. The
|
||||
old route remains durable until the replacement (and any initial message)
|
||||
succeeds. If the create endpoint returns the ordinary
|
||||
source-not-found response *and* a fresh authoritative storage lookup confirms
|
||||
that the source is gone, the router retries once without `resume_ws` and
|
||||
starts a fresh conversation. Other access, conflict, routing, and storage
|
||||
failures remain visible rather than silently discarding history.
|
||||
- If the workstream is evicted for capacity, the next message in the
|
||||
thread auto-creates a new workstream and atomically resumes the
|
||||
previous workstream via the `resume_ws` field on
|
||||
`CreateWorkstreamMessage`. The server resumes the workstream during
|
||||
creation (same HTTP request), and the server emits a
|
||||
`WorkstreamResumedEvent` back to the channel. The thread receives a
|
||||
*"Resumed: {name} ({count} messages restored)"* confirmation.
|
||||
|
||||
### Slash Commands
|
||||
|
||||
@@ -288,17 +284,15 @@ See [Security: Database Schema](security.md#database-schema) for the
|
||||
`channel_routes` table.
|
||||
2. **Active** — messages are routed bidirectionally. The bot streams
|
||||
responses via message edits (updated every ~1.5 seconds).
|
||||
3. **Eviction** — the server evicts an idle workstream for capacity. Its saved
|
||||
source row and channel route remain durable, and the thread stays open.
|
||||
4. **Reactivation** — the next message resolves the saved route and probes
|
||||
whether that workstream is live on its owning node. If it is not, the router
|
||||
creates a distinct workstream with the old `ws_id` as `resume_ws`. The
|
||||
create response confirms the fork and message count; there is no separate
|
||||
resume command or channel-specific resumed event. Only after the replacement
|
||||
succeeds does the router swap the persisted route. If the source was deleted
|
||||
or pruned, an exact source-not-found response plus a second authoritative
|
||||
storage miss triggers one fresh-create retry; other fork failures leave the
|
||||
old route intact and are surfaced normally.
|
||||
3. **Eviction** — the server evicts an idle workstream for capacity. The
|
||||
route is preserved and the thread stays open.
|
||||
4. **Reactivation** — the next message in the thread detects the stale
|
||||
route and creates a new workstream with the old `ws_id`
|
||||
as `resume_ws` on the creation request. The server resumes
|
||||
the workstream during creation (no separate command or reverse lookup
|
||||
needed). The channel receives a `WorkstreamResumedEvent`, and
|
||||
the thread displays *"Resumed: {name} ({count} messages restored)"*.
|
||||
If the old workstream was pruned, a fresh one starts with no error.
|
||||
5. **Close** — `/close` command closes the workstream via HTTP, deletes the
|
||||
route, unsubscribes from events, and archives the Discord thread.
|
||||
|
||||
|
||||
+36
-107
@@ -174,32 +174,17 @@ Request:
|
||||
{
|
||||
"node_id": "db-west-04",
|
||||
"name": "perf-analysis",
|
||||
"model": "gpt-5",
|
||||
"project_id": "proj_analytics",
|
||||
"initial_message": "Profile the slow query"
|
||||
"model": "gpt-5"
|
||||
}
|
||||
```
|
||||
|
||||
All fields are optional:
|
||||
- `node_id` — targeting mode:
|
||||
- **omitted or `"auto"`** — console picks the reachable node with the most available capacity (max_ws - ws_total) and proxies the request to it.
|
||||
- **`"pool"`** — compatibility alias for automatic placement on the reachable node with the most headroom.
|
||||
- **`"pool"`** — console picks a reachable node with available capacity using round-robin selection.
|
||||
- **specific node ID** — proxies the request to that node directly.
|
||||
- `name` — workstream display name. Auto-generated if omitted.
|
||||
- `model` — model alias from the target node's registry. Uses the node's default model if omitted.
|
||||
- `judge_model` — optional judge-model alias for this workstream.
|
||||
- `initial_message` — first message dispatched after the workstream is published.
|
||||
- `skill` — enabled profile/skill to snapshot onto a fresh workstream.
|
||||
- `persona` — enabled persona slug; empty uses the interactive default.
|
||||
- `project_id` — project to attach, subject to the target node's membership gate.
|
||||
- `resume_ws` — source ID to **fork** atomically into a new workstream. The
|
||||
source remains unchanged; its checkpoint-bounded history, configuration,
|
||||
persona, project, and attachment references are copied transactionally.
|
||||
|
||||
The endpoint also accepts the same multipart create shape as a node: one
|
||||
JSON-encoded `meta` field plus up to ten `file` parts. Files require an
|
||||
`initial_message` in the dashboard launcher. Files cannot be combined with
|
||||
`resume_ws`; fork first and upload on the new workstream.
|
||||
|
||||
Response:
|
||||
|
||||
@@ -211,19 +196,7 @@ Response:
|
||||
}
|
||||
```
|
||||
|
||||
The response is returned only after the target node has durably published the
|
||||
workstream. Its hidden `creating` reservation has already crossed to `idle`,
|
||||
and the node emitted `ws_created` before any initial-message state event. The
|
||||
cluster SSE event may therefore arrive before or after the HTTP response;
|
||||
clients should reconcile both by the returned `correlation_id`/workstream ID
|
||||
rather than treating them as two creates.
|
||||
|
||||
For safety, the console masks most target-node failures as the opaque `502`
|
||||
shape `{"error":"Dispatch to node <node_id> failed"}` instead of reflecting
|
||||
arbitrary node text or retry-triggering 401/429 responses. The coded
|
||||
`server.require_project` refusal is the exception and remains a `400` with
|
||||
actionable wording. Consult the target node's logs for the underlying create
|
||||
correlation when a reachable node returns a masked 502.
|
||||
The response confirms the workstream creation request was proxied to the target node. A `ws_created` event on the cluster SSE stream confirms the workstream was actually created.
|
||||
|
||||
### `GET /v1/api/cluster/events`
|
||||
|
||||
@@ -337,8 +310,8 @@ The auth system uses three scopes instead of the earlier read/full role model:
|
||||
| Scope | Grants |
|
||||
|-------|--------|
|
||||
| `read` | Read-only access: dashboards, workstream lists, SSE streams, health |
|
||||
| `write` | Non-approval mutations: send, create/open/close/delete, cancel, attachments, rewind, and retry |
|
||||
| `approve` | Tool-approval and admin HTTP surfaces (with their additional RBAC permission checks) |
|
||||
| `write` | Send messages, create/close workstreams, approve tool calls |
|
||||
| `approve` | Admin operations: manage users and API tokens |
|
||||
|
||||
Scopes are cumulative — a user with `approve` scope can also perform `write` and `read` operations.
|
||||
|
||||
@@ -375,87 +348,52 @@ SSE streams (`/v1/api/workstreams/{ws_id}/events`, `/v1/api/events/global`) are
|
||||
|
||||
### Authentication
|
||||
|
||||
The proxy mints a short-lived (5-minute) JWT per request carrying the real user's `user_id`, `scopes`, and `permissions` with `aud: turnstone-server`. The user's console JWT (`aud: turnstone-console`) cannot be forwarded directly — it would be rejected by the server's audience validation — so the console re-signs a new server-audience JWT from the validated `AuthResult`. This preserves audit attribution (the upstream server sees the real user, not a service identity) and enforces scope narrowing as defense in depth (a read-only console user's proxied request carries only `read` scope). Ordinary users are re-minted with `src="console-proxy"`; coordinator tokens retain `src="coordinator"` plus `coord_ws_id`, and only the validated console service identity with `service` scope retains `src="console"` for trusted owner forwarding. When no user context is available, the proxy falls back to a `ServiceTokenManager` identity `console-proxy` carrying `src="console"` and `{read, write, approve, service}` scopes. The static `--auth-token` / `proxy_auth_token` is used as a final fallback.
|
||||
The proxy mints a short-lived (5-minute) JWT per request carrying the real user's `user_id`, `scopes`, and `permissions` with `aud: turnstone-server`. The user's console JWT (`aud: turnstone-console`) cannot be forwarded directly — it would be rejected by the server's audience validation — so the console re-signs a new server-audience JWT from the validated `AuthResult`. This preserves audit attribution (the upstream server sees the real user, not a service identity) and enforces scope narrowing as defense in depth (a read-only console user's proxied request carries only `read` scope). The JWT `src` claim is set to `"console-proxy"` for audit traceability. When no user context is available (auth disabled), the proxy falls back to a `ServiceTokenManager` with service identity `console-proxy`. The static `--auth-token` / `proxy_auth_token` is used as a final fallback.
|
||||
|
||||
---
|
||||
|
||||
## Browser Dashboard
|
||||
|
||||
The console uses an L-shaped application shell: a collapsible navigation rail,
|
||||
a tab bar, and a pane host. On mobile the rail becomes an off-canvas drawer.
|
||||
The rail is fed by the cluster SSE snapshot and shows:
|
||||
The web UI has five views, toggled client-side:
|
||||
|
||||
- state/count filters and the live compute-node list, including version drift;
|
||||
- active coordinator and interactive workstreams, nested under their
|
||||
coordinator parent and grouped by project when project metadata is visible;
|
||||
- permission-filtered Manage groups that open the singleton Admin pane.
|
||||
### 1. Cluster Overview (landing)
|
||||
|
||||
Coordinator and interactive conversations open as tabs inside the same shell.
|
||||
Interactive panes use the owning node's console proxy, so users do not need
|
||||
direct network access to compute-node ports. Split-right and split-down actions
|
||||
can display several panes at once. Closing a pane removes only that tab; use the
|
||||
pane menu's explicit close or delete action to change the workstream lifecycle.
|
||||
- **State cards** — 5 clickable cards (running, thinking, attention, idle, error) with count and colored top border. Clicking filters to that state.
|
||||
- **Aggregate bar** — total tokens and tool calls across the cluster.
|
||||
- **Node table** — columns: NODE, WS, RUN, ATTN, TOKENS, VER, LOAD. Sorted by activity. Clickable rows drill down to node detail. Version column shows per-node version; hidden on mobile.
|
||||
- **Version drift indicator** — when nodes report different versions, the status bar shows a yellow "DRIFT" warning with a tooltip listing all versions. Node groups show "mixed" with a yellow badge when their members disagree.
|
||||
- **"+ new" button** — opens the workstream creation modal (see below).
|
||||
|
||||
### Dashboard pane
|
||||
### 2. Node Drill-down
|
||||
|
||||
The home view is coordinator-first. It contains the persistent workstream
|
||||
launcher plus the saved-sessions list. Selecting a state count opens the
|
||||
filtered workstream table inside the same Dashboard pane; selecting a compute
|
||||
node opens its proxied node surface. Cluster SSE updates keep rail state,
|
||||
workstream rows, and tab state glyphs synchronized.
|
||||
Breadcrumb: `Cluster > db-west-04`. Shows the node's workstreams in a table matching the per-node dashboard layout (STATE, NAME, MODEL, NODE, TASK, TOKENS, CTX) with activity sub-lines. Includes a link to the node's proxied server UI.
|
||||
|
||||
### Workstream launcher
|
||||
**Proxy deep-linking:** Clicking a workstream row opens the node's server UI in a new tab via the proxy at `/node/{node_id}/?ws_id=<id>`, which auto-selects that workstream. Users do not need direct network access to the server node.
|
||||
|
||||
The landing-page composer starts a workstream with an optional initial task and
|
||||
attachments. When the caller can create both kinds, a Coordinator / Interactive
|
||||
toggle selects the target kind. Its options include:
|
||||
### 3. Filtered Workstreams
|
||||
|
||||
- **Node placement** — "Least loaded" picks the reachable node with the most
|
||||
headroom, or "Specific node" pins the create to a node from the live list.
|
||||
Breadcrumb: `Cluster > Running` or `Cluster > db-west-04`. Server-side paginated workstream table. NODE column values are clickable to filter further. Pagination controls at bottom. Workstream rows use proxy deep-links.
|
||||
|
||||
### 4. Workstream Creation Modal
|
||||
|
||||
Triggered by the "+ new" header button. A modal dialog with:
|
||||
|
||||
- **Node selector** — dropdown with three targeting modes: "Auto (best available)" picks the node with the most headroom, "General pool (any node)" picks a node with available capacity using round-robin, or a specific node from the list (showing capacity).
|
||||
- **Persona** — optional dropdown listing the enabled personas for the workstream kind. Sets the system-message composition and capability envelope at creation, snapshotted server-side; empty uses the kind's default. Picking one requires no `persona.*` permission.
|
||||
- **Skill** — optional dropdown listing enabled skills. Applies the skill's model, auto-approve policy, token budget, and other behavioral settings at creation time.
|
||||
- **Project** — optional project filing. Private projects require owner/member access. A coordinator child inherits its parent's project unless explicitly routed to another attachable project.
|
||||
- **Profile** — optional dropdown listing enabled skills. Applies the skill's model, auto-approve policy, token budget, and other behavioral settings at creation time.
|
||||
- **Name** — optional text input. Auto-generated if left empty.
|
||||
- **Model** — optional selector populated from the target model registry.
|
||||
- **Judge Model** — optional selector for the judge alias (overrides the default
|
||||
judge model for this workstream).
|
||||
- **Model** — optional text input for a model alias from the target node's registry.
|
||||
- **Judge Model** — optional text input for the judge model alias (overrides the default judge model for this workstream).
|
||||
|
||||
Interactive launches additionally expose node strategy / node selection.
|
||||
Submitting uses `POST /v1/api/cluster/workstreams/new`; coordinator launches use
|
||||
the console's coordinator create surface. A toast confirms the committed
|
||||
create, while SSE updates the dashboard and opens the resulting pane.
|
||||
Keyboard shortcuts: Ctrl+Shift+R (refresh title), Ctrl+Shift+E (edit title), Ctrl+Shift+F (fork), Ctrl+Shift+X (delete). Press ? for full shortcut help.
|
||||
|
||||
Files require a non-empty initial task so the first turn consumes the staged
|
||||
attachments. The console shell does not currently expose a fork action; use the
|
||||
node's standalone workstream UI or the create API's `resume_ws` field.
|
||||
On submit, `POST /v1/api/cluster/workstreams/new` dispatches the creation request. A toast confirms success; the SSE stream delivers the `ws_created` event to update the dashboard.
|
||||
|
||||
### Large pasted text
|
||||
All five views receive live updates via SSE — state cards update counts, node rows update metrics, workstream rows update state indicators.
|
||||
|
||||
Browser composers turn plain text longer than 2,000 Unicode code points into a
|
||||
`text/plain` attachment named `pasted-text.txt`. A paste exactly at the
|
||||
threshold stays inline. This applies to the interactive and coordinator send
|
||||
boxes, the console home launcher, and the node dashboard and new-workstream
|
||||
composers.
|
||||
The browser maintains a local `clusterState` object that mirrors the cluster snapshot. It is initialized from the SSE `snapshot` event on connect (or via `GET /v1/api/cluster/snapshot` on initial page load) and updated incrementally by SSE events. View navigation reads from local state — no API round-trips needed after the initial snapshot.
|
||||
|
||||
Clipboard files take priority over clipboard text. Text larger than the 512 KiB
|
||||
attachment ceiling also stays inline, so the browser does not discard it before
|
||||
a rejected upload. Attachments require a companion message and cannot be sent
|
||||
as live-turn interjections; a busy composer preserves its message and chips for
|
||||
an idle retry.
|
||||
|
||||
### Saved and filtered sessions
|
||||
|
||||
Saved coordinator and interactive sessions share one list with kind and persona
|
||||
labels, filtering, pagination, and multi-select deletion. Opening a saved
|
||||
coordinator rehydrates it in the console; opening a saved interactive session
|
||||
resolves its node, calls `open`, and then connects the node-proxied pane.
|
||||
|
||||
The filtered live table carries STATE, NAME, MODEL, NODE, TASK, TOKENS, and CTX
|
||||
columns. The browser maintains a local `clusterState` initialized from the
|
||||
cluster snapshot and updated incrementally by SSE; the filtered view normally
|
||||
renders from that state without another API round trip.
|
||||
|
||||
### Admin pane
|
||||
### 5. Admin Panel
|
||||
|
||||
Accessed via the "admin" button in the header (visible when authenticated
|
||||
with `approve` scope). Provides user, API token, channel link, MCP server,
|
||||
@@ -467,14 +405,8 @@ Audit tabs, and [Settings](settings.md) for the database-backed
|
||||
configuration editor.
|
||||
|
||||
The **Channels** tab links users to either a Discord or Slack account
|
||||
via a per-row channel-type selector. The **Models** tab is a CRUD
|
||||
editor for `model_definitions`, including static and dynamic backend-auth
|
||||
modes and a per-process **Max concurrent generations** limit for each alias
|
||||
(`0` means unlimited). The limit is shared by every model-backed role using
|
||||
that alias and a streaming generation holds its slot through the full decode.
|
||||
Model edits rebind existing workstreams at their next send while
|
||||
in-flight requests keep their original definition snapshot; see
|
||||
[Settings](settings.md#model-definition-reloads) for the full contract. The **Nodes** tab edits per-node
|
||||
via a per-row channel-type selector. The **Models** tab is a CRUD
|
||||
editor for `model_definitions`, the **Nodes** tab edits per-node
|
||||
metadata, and the **TLS** tab manages CA and leaf certificates for the
|
||||
internal mTLS fabric. The **Settings** tab edits ConfigStore values
|
||||
live; edits apply without restart.
|
||||
@@ -572,7 +504,7 @@ Run history is automatically pruned (runs older than 90 days) approximately once
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| `auto` | Picks the reachable node with the most available capacity |
|
||||
| `pool` | Compatibility alias for the reachable node with the most headroom |
|
||||
| `pool` | Picks a reachable node with available capacity using round-robin |
|
||||
| `all` | Fan-out to all reachable nodes (capped at `max_fan_out`, default 20) |
|
||||
| `<node_id>` | Targets a specific node by ID |
|
||||
|
||||
@@ -732,7 +664,4 @@ turnstone-server --port 8080
|
||||
turnstone-console --port 8090
|
||||
```
|
||||
|
||||
Open `http://localhost:8090` for the cluster dashboard. Create workstreams from
|
||||
the persistent Dashboard launcher. Selecting a workstream opens a coordinator
|
||||
or node-proxied interactive pane in the console shell — no direct access to
|
||||
server ports is required.
|
||||
Open `http://localhost:8090` for the cluster dashboard. Create workstreams via the "+ new" button. Click any workstream to open the proxied server UI — no direct access to server ports required.
|
||||
|
||||
@@ -37,7 +37,7 @@ schema changes.
|
||||
| # | Action | Operation |
|
||||
|---|------------------------------|-------------------------------------------------------------|
|
||||
| 1 | Create | `POST /v1/api/workstreams/new` |
|
||||
| 2 | Bootstrap history + subscribe | `GET .../history`, then `GET .../events` (SSE) |
|
||||
| 2 | Subscribe to events | `GET /v1/api/workstreams/{ws_id}/events` (SSE) |
|
||||
| 3 | Send a user message | `POST /v1/api/workstreams/{ws_id}/send` |
|
||||
| 4 | Inspect children | `GET /v1/api/workstreams/{ws_id}/children` |
|
||||
| 5 | Inspect one workstream | `GET /v1/api/cluster/ws/{ws_id}/detail` |
|
||||
@@ -91,34 +91,14 @@ subscribers (step 2) see the session warm up as token traffic starts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Bootstrap history, then subscribe to the event stream
|
||||
|
||||
Read and render history before opening the initial stream:
|
||||
## 2. Subscribe to the per-coordinator event stream
|
||||
|
||||
```http
|
||||
GET /v1/api/workstreams/{ws_id}/history?limit=100 HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
For a loaded coordinator, `messages` is the requested tail of one total
|
||||
accepted conversation-row prefix: user, assistant, tool, and system rows,
|
||||
including projected compaction checkpoints and cancellation-generated markers.
|
||||
The response's optional `cursor` and `handoff_token` belong to that exact
|
||||
render. Pass both once on the initial stream URL:
|
||||
|
||||
```http
|
||||
GET /v1/api/workstreams/{ws_id}/events?last_event_id={cursor}&history_token={handoff_token}&user_turn=1&tool_turn=1 HTTP/1.1
|
||||
GET /v1/api/workstreams/{ws_id}/events HTTP/1.1
|
||||
Accept: text/event-stream
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
Omit either query parameter when its history field is `null`. A handoff token
|
||||
is opaque and process-local: do not parse, persist, or reuse it. Admission of a
|
||||
later conversation row changes the token; durable acknowledgement does not. If
|
||||
history returns `503 {"error":"History temporarily unavailable"}`, the response
|
||||
is not authoritative: retain the current transcript, do not open a tokenless
|
||||
replacement stream, and retry the read.
|
||||
|
||||
One persistent SSE connection per browser tab / SDK caller — the
|
||||
console fans each event out to every listener queue (cap 500 events
|
||||
per queue, put_nowait drop on overflow). Events come in flat JSON
|
||||
@@ -130,10 +110,10 @@ with a `type` field. The recurring shapes a UI has to handle:
|
||||
| `reasoning` | Reasoning-token stream chunk (when the model exposes it) | `text` |
|
||||
| `content` | Assistant-content stream chunk | `text` |
|
||||
| `stream_end` | End of a single provider stream | — |
|
||||
| `tool_result` | A tool call completed; capable panes also receive the accepted-history replacement | `call_id`, `name`, `output`, `is_error?`, `accepted?`, `_event_id?`, `preview?`, `effect_status?` |
|
||||
| `tool_result` | A tool call completed (success or error) | `call_id`, `name`, `output`, `is_error?` |
|
||||
| `tool_output_chunk` | Streaming tool output (e.g. long bash command) | `call_id`, `chunk` |
|
||||
| `approve_request` | One approval cycle needs operator action; several cycles may coexist | `cycle_id`, `items: [{call_id, header, preview, func_name, approval_label, needs_approval}]` |
|
||||
| `approval_resolved` | One identified approval cycle was answered | `cycle_id`, `call_ids`, `approved`, `feedback`, `always` |
|
||||
| `approve_request` | One or more tool calls need operator approval | `items: [{call_id, header, preview, func_name, approval_label, needs_approval}]` |
|
||||
| `approval_resolved` | Operator answered the approval prompt | `approved`, `feedback` |
|
||||
| `state_change` | Worker-thread state transition (also re-emitted with the current state on every fresh subscribe so refresh-mid-stream restores composer mode) | `state` ∈ `running`, `thinking`, `attention`, `idle`, `error` |
|
||||
| `in_progress_snapshot` | One-shot replay of the in-progress turn's content + reasoning when this client connects mid-stream | `content`, `reasoning` |
|
||||
| `status` | Token usage + context-window snapshot (fires on every streaming tick) | `prompt_tokens`, `completion_tokens`, `total_tokens`, `context_window`, `pct`, `effort`, `cache_creation_tokens`, `cache_read_tokens` |
|
||||
@@ -147,11 +127,10 @@ with a `type` field. The recurring shapes a UI has to handle:
|
||||
| `wait_started` / `wait_progress` / `wait_ended` | `wait_for_workstream` tool lifecycle (see §6) | `call_id`, `ws_ids`, `elapsed`, `results`, `complete` |
|
||||
| `batch_started` / `batch_ended` | `spawn_batch` / `close_all_children` tool lifecycle | `call_id`, `op`, `total`/`succeeded`/`denied`/`closed`/`failed`/`skipped` |
|
||||
| `info` / `error` | Operational messages | `message` |
|
||||
| `history_resync` | The rendered history token no longer names the accepted row prefix | `ws_id`, `reason` |
|
||||
|
||||
**Reconnection contract:** a freshly-opened SSE connection receives
|
||||
one `approve_request` snapshot for every unresolved approval cycle, keyed by
|
||||
the same stable `cycle_id`, plus any in-flight `wait_*` / `batch_*`
|
||||
the current snapshot of any pending tool approval (`approve_request`
|
||||
is re-sent if unresolved), any in-flight `wait_*` / `batch_*`
|
||||
indicator, the worker's current `state_change`, and an
|
||||
`in_progress_snapshot` carrying any partial content / reasoning the
|
||||
model has produced for the in-progress turn — so a tab refresh
|
||||
@@ -159,11 +138,6 @@ mid-approval, mid-tool-execution, or mid-stream restores both the
|
||||
correct composer mode and the partial assistant text without waiting
|
||||
for the response to complete.
|
||||
|
||||
`history_resync` is stronger than a numeric replay gap. The server closes that
|
||||
stream; fetch and render `/history` again, then open a new stream with its new
|
||||
cursor/token pair. The API and SDK expose these primitives but deliberately do
|
||||
not choose a reconnect policy for callers.
|
||||
|
||||
---
|
||||
|
||||
## 3. Send the first user message
|
||||
@@ -350,35 +324,24 @@ uses the cascade-mutation shape and how it differs from the
|
||||
|
||||
The `approve` endpoint is what resolves an `approve_request` SSE
|
||||
event. The coordinator's worker thread is blocked inside
|
||||
`ui.approve_tools` waiting for this POST. Parallel task agents can leave
|
||||
several approval cycles live at once, so current clients echo the event's
|
||||
`cycle_id` (or a member `call_id`). A selector-less request resolves the oldest
|
||||
cycle for compatibility.
|
||||
`ui.approve_tools` waiting for this POST.
|
||||
|
||||
```http
|
||||
POST /v1/api/workstreams/{ws_id}/approve
|
||||
{"approved": true, "feedback": null, "always": false, "cycle_id": "cycle_789"}
|
||||
{"approved": true, "feedback": null, "always": false}
|
||||
{"approved": false, "feedback": "spawn count looks too high — try 3 not 10"}
|
||||
{"approved": true, "feedback": null, "always": true} // remember this cycle's tool names
|
||||
{"approved": true, "feedback": null, "always": true} // always-approve this tool name
|
||||
```
|
||||
|
||||
Success returns `{"status": "ok", "cycle_id": "cycle_789"}`. A stale selector
|
||||
returns `409` with the currently oldest cycle/call IDs. `always` remembers only
|
||||
the tool names in the cycle that actually resolved; it does not enable blanket
|
||||
approval.
|
||||
|
||||
`cancel` requests cooperative cancellation of the coordinator's in-flight
|
||||
generation and auto-cascades to its direct children:
|
||||
`cancel` drops the coordinator's in-flight generation and, for a
|
||||
coordinator, auto-cascades the cancel to its direct children:
|
||||
`cancel_workstream` is dispatched through the routing proxy for
|
||||
every direct child in the registry. The HTTP acknowledgement is immediate;
|
||||
the worker becomes idle after unwinding. Pass `{"force": true}` only to release
|
||||
a wedged worker slot immediately. The coordinator itself remains open for a
|
||||
fresh `send`:
|
||||
every direct child in the registry. The coordinator itself is left
|
||||
idle and open for a fresh `send`:
|
||||
|
||||
```http
|
||||
POST /v1/api/workstreams/{ws_id}/cancel
|
||||
{}
|
||||
{"status": "ok", "dropped": {}}
|
||||
```
|
||||
|
||||
---
|
||||
@@ -398,11 +361,6 @@ disconnect. The row is reopenable via
|
||||
`POST /v1/api/workstreams/{ws_id}/open` so long as it hasn't been
|
||||
deleted.
|
||||
|
||||
If any accepted live conversation row still requires persistence
|
||||
reconciliation, close returns `409 {"error":"workstream has unresolved
|
||||
persistence"}`. The coordinator remains loaded, its journal is retained, and
|
||||
no history is discarded; retry after storage recovers.
|
||||
|
||||
---
|
||||
|
||||
## Further reading
|
||||
|
||||
+12
-22
@@ -77,7 +77,7 @@ or MCP config can do adds to it. Current members:
|
||||
| `delete_workstream` | wind-down | Hard-delete one child. Requires approval. |
|
||||
| `list_nodes` | discover | Enumerate live cluster nodes + capabilities. |
|
||||
| `skills` (action=find) | discover | Browse the skill catalog; opt-in `kind` filter narrows by audience. |
|
||||
| `memory` | persist | Durable acting-user orchestration memory (`coordinator`), plus shared memory when attached to a project. |
|
||||
| `memory` | persist | Durable orchestration memory (`coordinator` scope, per-user — survives across coordinator sessions). |
|
||||
| `notify` | broadcast | Post a status update to a human channel at a narrative beat. |
|
||||
| `tasks` | plan | Orchestrator-only scratchpad. Children don't see it. |
|
||||
|
||||
@@ -126,11 +126,10 @@ the skill should end on.
|
||||
|
||||
`tasks` is the coordinator's scratchpad — a persisted, ordered
|
||||
list of rows with fields `{id, title, status, child_ws_id, created,
|
||||
updated}`, plus `note` on rows where one has been set (the key is
|
||||
absent otherwise), that only this coordinator sees. Children don't
|
||||
see it; the user does via the sidebar. Five actions: `add`,
|
||||
`update`, `remove`, `reorder`, `list` (only `list` is auto-approved;
|
||||
the mutators go through the approval flow).
|
||||
updated}` that only this coordinator sees. Children don't see it;
|
||||
the user does via the sidebar. Five actions: `add`, `update`,
|
||||
`remove`, `reorder`, `list` (only `list` is auto-approved; the
|
||||
mutators go through the approval flow).
|
||||
|
||||
The input schema refers to rows by `task_id`; the persisted row
|
||||
object exposes the same id as `id`. The `child_ws_id` field is a
|
||||
@@ -143,20 +142,11 @@ A skill's initial prompt can seed the task list by calling
|
||||
`tasks(action="add", title=...)` as its very first tool calls —
|
||||
the user gets a visible plan before any child is spawned, and the
|
||||
coordinator's future self has something concrete to iterate on.
|
||||
Status transitions (`pending` → `in_progress` → `done` / `blocked` /
|
||||
`needs_user`) are the skill's main feedback loop: mutate the task
|
||||
when the child covering it finishes, not when the child starts.
|
||||
`blocked` and `needs_user` are not interchangeable — `blocked` is a
|
||||
dependency the coordinator may be able to clear itself, while
|
||||
`needs_user` marks a task that cannot move without a decision,
|
||||
approval, or grant only the user can give. The distinction is
|
||||
load-bearing: a coordinator that goes idle holding open tasks gets
|
||||
nudged to pick them back up — even when children are still running, so
|
||||
keep the matrix honest rather than expecting the reminder to wait for
|
||||
an all-clear — and `needs_user` is what tells that nudge the stop was
|
||||
deliberate. Pair it with `note` to record what is being asked for.
|
||||
Use `tasks(action="update", task_id=..., child_ws_id=<ws_id>)` to link
|
||||
a task to the child that owns it once spawn returns.
|
||||
Status transitions (`pending` → `in_progress` → `done` / `blocked`)
|
||||
are the skill's main feedback loop: mutate the task when the child
|
||||
covering it finishes, not when the child starts. Use
|
||||
`tasks(action="update", task_id=..., child_ws_id=<ws_id>)` to
|
||||
link a task to the child that owns it once spawn returns.
|
||||
|
||||
A final gotcha: parallel tool dispatch does NOT serialise reads
|
||||
after writes in the same batch. If a skill issues an `update` and
|
||||
@@ -307,11 +297,11 @@ and the coordinator's planning step is itself valuable.
|
||||
tasks(action='add', title='...') × N # the plan, visible in the sidebar
|
||||
for task in tasks:
|
||||
spawn_workstream(skill=..., initial_message=task.brief)
|
||||
tasks(action='update', task_id=task.id, note='ws=<child_ws_id>')
|
||||
tasks(action='update', task_id=task.id, notes='ws=<child_ws_id>')
|
||||
wait_for_workstream(ws_ids=[...], mode='all', timeout=...)
|
||||
for child in children:
|
||||
inspect_workstream(ws_id=child)
|
||||
tasks(action='update', task_id=..., status='done', note='result summary')
|
||||
tasks(action='update', task_id=..., status='done', notes='result summary')
|
||||
→ synthesise
|
||||
```
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ cloud "LLM Providers" as llm {
|
||||
component [OpenAI-compatible API\n(OpenAI, vLLM, llama.cpp)] as llm_openai
|
||||
component [Anthropic Messages API] as llm_anthropic
|
||||
}
|
||||
database "SQLite / PostgreSQL\n(durable state)" as storage
|
||||
database "SQLite\n(.turnstone.db)" as sqlite
|
||||
|
||||
' Turnstone System Boundary
|
||||
package "Turnstone Platform" {
|
||||
@@ -33,26 +33,24 @@ eval_user --> eval : Python API
|
||||
|
||||
' Internal connections
|
||||
cli --> llm : LLM Provider API\n(via provider adapters)
|
||||
cli --> storage : persistence
|
||||
cli --> sqlite : SQLite
|
||||
|
||||
server --> llm : LLM Provider API\n(via provider adapters)
|
||||
server --> storage : persistence
|
||||
server --> sqlite : SQLite
|
||||
|
||||
eval --> llm : LLM Provider API\n(non-streaming)
|
||||
eval --> storage : persistence
|
||||
eval --> sqlite : SQLite
|
||||
|
||||
console --> server : HTTP routing/UI proxy + cluster SSE\n(FNV-1a rendezvous placement,\nproxy /node/{id}/* traffic)
|
||||
console --> server : HTTP proxy\n(hash-ring bucket lookup,\nproxy /node/{id}/* traffic)
|
||||
|
||||
channel --> console : multi-node route/create/live/send/approve
|
||||
channel --> server : direct mode + owning-node SSE\n(POST /v1/api/workstreams/{ws_id}/send,\nGET /v1/api/workstreams/{ws_id}/events)
|
||||
channel --> server : HTTP + SSE\n(POST /v1/api/workstreams/{ws_id}/send,\nGET /v1/api/workstreams/{ws_id}/events)
|
||||
|
||||
' Notes
|
||||
note right of console
|
||||
Multi-node router:
|
||||
- FNV-1a rendezvous placement
|
||||
- Hash-ring bucket lookup
|
||||
- Proxies create/send/approve
|
||||
- Collector aggregates node SSE
|
||||
- Browser dashboard receives console SSE fanout
|
||||
- /node/{id} proxies pane HTTP + SSE
|
||||
- Direct SSE from client to node
|
||||
- HTTP polling for dashboard
|
||||
end note
|
||||
@enduml
|
||||
|
||||
@@ -18,7 +18,6 @@ skinparam component {
|
||||
package "Entry Points" <<Rectangle>> {
|
||||
component [cli.py\nturnstone] as cli <<entry>>
|
||||
component [server.py\nturnstone-server] as server <<entry>>
|
||||
component [console/server.py\nturnstone-console] as consoleentry <<entry>>
|
||||
component [eval.py\nturnstone-eval] as eval <<entry>>
|
||||
component [admin.py\nturnstone-admin] as admin <<entry>>
|
||||
component [bootstrap.py\nturnstone-bootstrap] as bootstrap <<entry>>
|
||||
@@ -26,16 +25,9 @@ package "Entry Points" <<Rectangle>> {
|
||||
|
||||
' Core engine
|
||||
package "turnstone/core/" <<Rectangle>> {
|
||||
component [session.py\nChatSession, SessionUI\ngeneration-fenced turn loop] as session <<core>>
|
||||
component [session_manager.py\nSessionManager\nshared lifecycle invariants] as sessionmanager <<core>>
|
||||
component [adapters/\ninteractive + coordinator\nconstruction/event policies] as adapters <<core>>
|
||||
component [model_turn.py\nModelLane, model_turn()\nlower / sample / re-ingest] as modelturn <<core>>
|
||||
component [trajectory.py\ncanonical Turn IR] as trajectory <<core>>
|
||||
component [lowering.py\nprovider-wire lowering] as lowering <<core>>
|
||||
component [state_writer.py\nordered durable state tail] as statewriter <<core>>
|
||||
component [model_backend_auth.py\nper-call backend credentials] as modelauth <<core>>
|
||||
component [session.py\nChatSession, SessionUI] as session <<core>>
|
||||
component [providers/\nLLMProvider, OpenAI, Anthropic, Google] as providers <<core>>
|
||||
component [workstream.py\nWorkstream types + state] as workstream <<core>>
|
||||
component [workstream.py\nWorkstreamManager] as workstream <<core>>
|
||||
component [tools.py\nTool loader] as tools <<core>>
|
||||
component [memory.py\nPersistence facade] as memory <<core>>
|
||||
component [storage/\nStorageBackend protocol\nSQLite + PostgreSQL] as storage <<core>>
|
||||
@@ -87,18 +79,18 @@ package "turnstone/api/" <<Rectangle>> {
|
||||
package "turnstone/sdk/" <<Rectangle>> {
|
||||
component [server.py\nTurnstoneServer (sync+async)] as sdkserver <<sdk>>
|
||||
component [console.py\nTurnstoneConsole (sync+async)] as sdkconsole <<sdk>>
|
||||
component [events.py\nTyped SSE event stream] as sdkevents <<sdk>>
|
||||
component [events.py\n27 SSE event types] as sdkevents <<sdk>>
|
||||
component [_base.py\nhttpx client base] as sdkbase <<sdk>>
|
||||
}
|
||||
|
||||
' Tool schemas
|
||||
package "turnstone/tools/" <<Rectangle>> {
|
||||
component [*.json\nBuilt-in tool schemas] as schemas <<artifact>>
|
||||
component [*.json\n19 tool schemas] as schemas <<artifact>>
|
||||
}
|
||||
|
||||
' Entry point dependencies
|
||||
cli --> session
|
||||
cli --> sessionmanager
|
||||
cli --> workstream
|
||||
cli --> config
|
||||
cli --> memory
|
||||
cli --> colors
|
||||
@@ -107,8 +99,7 @@ cli --> spinner
|
||||
cli --> tools
|
||||
|
||||
server --> session
|
||||
server --> sessionmanager
|
||||
server --> adapters
|
||||
server --> workstream
|
||||
server --> config
|
||||
server --> memory
|
||||
server --> metrics
|
||||
@@ -122,26 +113,11 @@ eval --> memory
|
||||
eval --> config
|
||||
eval --> tools
|
||||
|
||||
consoleentry --> sessionmanager
|
||||
consoleentry --> adapters
|
||||
consoleentry --> consoleserver
|
||||
|
||||
admin --> auth
|
||||
bootstrap --> providers
|
||||
|
||||
' Core internal deps
|
||||
sessionmanager --> workstream
|
||||
sessionmanager --> adapters
|
||||
sessionmanager --> storage
|
||||
adapters --> session : constructs
|
||||
session --> modelturn
|
||||
session --> trajectory
|
||||
session --> lowering
|
||||
session --> statewriter
|
||||
session --> modelauth
|
||||
modelturn --> providers
|
||||
modelturn --> trajectory
|
||||
modelturn --> lowering
|
||||
session --> providers
|
||||
session --> tools
|
||||
session --> memory
|
||||
memory --> storage
|
||||
@@ -153,7 +129,6 @@ session --> mcp : optional
|
||||
session --> toolsearch : optional
|
||||
session --> registry : optional
|
||||
registry --> providers
|
||||
modelturn --> registry : coherent snapshot
|
||||
healthcheck --> metrics
|
||||
mcp --> config
|
||||
registry --> config
|
||||
@@ -163,17 +138,15 @@ tools --> schemas
|
||||
gateway --> discordbot
|
||||
gateway --> slackbot
|
||||
gateway --> router
|
||||
discordbot --> sdkserver : direct HTTP + node SSE
|
||||
slackbot --> sdkserver : direct HTTP + node SSE
|
||||
router --> sdkserver : single-node/direct mode
|
||||
router --> sdkconsole : multi-node route/create/live
|
||||
discordbot --> sdkserver : HTTP + SSE
|
||||
slackbot --> sdkserver : HTTP + SSE
|
||||
router --> storage : channel_routes
|
||||
|
||||
' Console dependencies
|
||||
consoleserver --> collector
|
||||
consoleserver --> config
|
||||
consoleserver --> auth
|
||||
collector --> server : discovery HTTP + cluster SSE aggregation
|
||||
collector --> server : HTTP polling
|
||||
|
||||
' API dependencies
|
||||
serverspec --> openapi
|
||||
|
||||
@@ -32,7 +32,7 @@ class "TerminalUI" as TerminalUI {
|
||||
class "WorkstreamTerminalUI" as WsTermUI {
|
||||
- _output_buffer: list[tuple]
|
||||
- ws_id: str
|
||||
- manager: SessionManager
|
||||
- manager: WorkstreamManager
|
||||
+ flush_buffer()
|
||||
--
|
||||
Buffers output when workstream
|
||||
@@ -41,14 +41,14 @@ class "WorkstreamTerminalUI" as WsTermUI {
|
||||
|
||||
class "WebUI" as WebUI {
|
||||
- _listeners: list[Queue]
|
||||
- _approval_cycles: dict[str, ApprovalCycle]
|
||||
- _approval_event: Event
|
||||
- _ws_prompt_tokens: int
|
||||
- _ws_tool_calls: dict
|
||||
+ resolve_approval(approved, feedback, cycle_id?, call_id?)
|
||||
+ resolve_approval(approved, feedback)
|
||||
--
|
||||
Enqueues JSON events for SSE.
|
||||
Concurrent approval cycles each own
|
||||
a threading.Event and result slot.
|
||||
Blocks on threading.Event for
|
||||
approval.
|
||||
SSE handlers bridge Queue to
|
||||
async via run_in_executor().
|
||||
--
|
||||
@@ -66,7 +66,8 @@ class "NullUI" as NullUI {
|
||||
interface "LLMProvider" as LLMProvider <<Protocol>> {
|
||||
+ provider_name: str {property}
|
||||
+ get_capabilities(model) → ModelCapabilities
|
||||
+ create_streaming(client, model, messages, ..., cancel_ref, replay_reasoning_to_model) → Iterator[StreamChunk]
|
||||
+ create_streaming(client, model, messages, ..., replay_reasoning_to_model) → Iterator[StreamChunk]
|
||||
+ create_completion(client, model, messages, ..., replay_reasoning_to_model) → CompletionResult
|
||||
+ convert_tools(tools) → list[dict]
|
||||
+ extract_reasoning_text(provider_blocks) → str
|
||||
+ retryable_error_names: frozenset[str] {property}
|
||||
@@ -126,82 +127,31 @@ class "ModelCapabilities" as ModelCaps <<frozen>> {
|
||||
+ supports_reasoning_replay: bool
|
||||
}
|
||||
|
||||
class "ModelLane" as ModelLane <<frozen>> {
|
||||
+ provider: LLMProvider
|
||||
+ client: Any
|
||||
+ model: str
|
||||
+ alias: str
|
||||
+ capabilities: ModelCapabilities
|
||||
+ extra_params: dict | None
|
||||
+ registry: ModelRegistry | None
|
||||
+ admission: ModelAdmission | None
|
||||
+ backend_auth_config: ModelConfig | None
|
||||
+ backend_auth_resolver: Callable | None
|
||||
}
|
||||
|
||||
class "ResolvedModelBinding" as ResolvedBinding <<frozen>> {
|
||||
+ lane: ModelLane
|
||||
+ config: ModelConfig | None
|
||||
+ registry_generation: int
|
||||
}
|
||||
|
||||
class "ModelTurnResult" as ModelTurnResult <<frozen>> {
|
||||
+ turn: Turn
|
||||
+ tool_calls: list[dict]
|
||||
+ finish_reason: str
|
||||
+ usage: UsageInfo | None
|
||||
+ wire_msgs: list[dict] | None
|
||||
+ producer: str
|
||||
+ serving_model: str
|
||||
}
|
||||
|
||||
class "model_turn()" as ModelTurnFn {
|
||||
Turn IR → lower → provider stream
|
||||
→ drain → canonical assistant Turn
|
||||
--
|
||||
core/model_turn.py
|
||||
}
|
||||
|
||||
class "Backend auth resolver" as BackendAuth {
|
||||
+ resolve_model_backend_auth_token(...)
|
||||
--
|
||||
Resolves static / Entra OBO /
|
||||
Entra app / RFC 8693 per call.
|
||||
Dynamic failure can fail closed.
|
||||
--
|
||||
core/model_backend_auth.py
|
||||
}
|
||||
|
||||
' ChatSession
|
||||
class "ChatSession" as ChatSession {
|
||||
- _model_binding: ResolvedModelBinding
|
||||
- _model_binding_lock: Lock
|
||||
- client: Any
|
||||
- provider: LLMProvider
|
||||
- model: str
|
||||
- ui: SessionUI
|
||||
- messages: list[Turn]
|
||||
- messages: list[dict]
|
||||
- _msg_tokens: list[int]
|
||||
- _ws_id: str
|
||||
- _mcp_client: MCPClientManager | None
|
||||
- _tool_search: ToolSearchManager | None
|
||||
- _registry: ModelRegistry | None
|
||||
- _generation: int
|
||||
- _cancel_event: Event
|
||||
- _durability_next_ticket: int
|
||||
+ model_alias: str | None {property}
|
||||
- _tools: list[dict]
|
||||
- _task_tools: list[dict]
|
||||
- _read_files: set[str]
|
||||
- system_messages: list[dict]
|
||||
--
|
||||
+ send(user_input: str, ..., acting_user_id: str | None)
|
||||
+ cancel()
|
||||
+ compact_now() → bool
|
||||
+ fork_from_storage(source_ws_id, principal_id, ...)
|
||||
+ send(user_input: str)
|
||||
+ handle_command(command: str)
|
||||
+ resume(ws_id: str)
|
||||
- _save_config()
|
||||
- _stream_response(my_generation) → ModelTurnResult
|
||||
- _model_turn_with_fallback(consumer, prepare_wire) → ModelTurnResult
|
||||
- _model_turn_with_retry(lane, tracker, ...) → ModelTurnResult
|
||||
- _stream_response(stream) → dict
|
||||
- _create_stream_with_retry(msgs) → Stream (+ fallback)
|
||||
- _try_stream(client, model, msgs) → Stream
|
||||
- _execute_tools(tool_calls) → (results, feedback)
|
||||
- _prepare_tool(tc) → item dict
|
||||
- _prepare_mcp_tool(call_id, name, args) → item dict
|
||||
@@ -213,10 +163,8 @@ class "ChatSession" as ChatSession {
|
||||
- _rebuild_tool_search()
|
||||
+ close()
|
||||
- _run_agent(messages, tools, ...) → str
|
||||
- _compact_messages(auto: bool, my_generation: int)
|
||||
- _commit_for_generation(generation, commit)
|
||||
- _publish_for_generation(generation, publish)
|
||||
- _full_messages() → list[Turn]
|
||||
- _compact_messages(auto: bool)
|
||||
- _full_messages() → list[dict]
|
||||
- _update_token_table(msg)
|
||||
- _emit_state(state: str)
|
||||
- _generate_title()
|
||||
@@ -229,40 +177,19 @@ class "HeadlessSession" as HeadlessSession {
|
||||
+ send_headless(input, max_turns, ...)
|
||||
- _override_system_prompt(content)
|
||||
--
|
||||
eval.py: drained single-shot turns,
|
||||
eval.py: non-streaming,
|
||||
records all tool calls
|
||||
}
|
||||
|
||||
' SessionManager
|
||||
interface "SessionKindAdapter" as KindAdapter <<Protocol>> {
|
||||
+ kind: WorkstreamKind
|
||||
+ build_ui(ws) → SessionUI
|
||||
+ build_session(ws, ...) → ChatSession
|
||||
+ cleanup_ui(ws)
|
||||
}
|
||||
|
||||
interface "SessionEventEmitter" as EventEmitter <<Protocol>> {
|
||||
+ emit_created(ws)
|
||||
+ emit_rehydrated(ws)
|
||||
+ emit_state(ws, state)
|
||||
+ emit_closed(ws_id, reason, name)
|
||||
}
|
||||
|
||||
class "SessionManager" as SessionMgr {
|
||||
- _adapter: SessionKindAdapter
|
||||
- _storage: StorageBackend
|
||||
' WorkstreamManager
|
||||
class "WorkstreamManager" as WsMgr {
|
||||
- _session_factory: Callable[[SessionUI], ChatSession]
|
||||
- _workstreams: dict[str, Workstream]
|
||||
- _pending_creates: dict[str, Workstream]
|
||||
- _retiring_ids: set[str]
|
||||
- _state_writer: StateWriter | None
|
||||
- _order: list[str]
|
||||
- _active_id: str
|
||||
- _on_state_change: Callable
|
||||
--
|
||||
+ create(user_id, name, ..., defer_emit_created) → Workstream
|
||||
+ commit_create(ws) → bool
|
||||
+ discard(ws, ...) → bool
|
||||
+ open(ws_id) → Workstream | None
|
||||
+ delete(ws_id) → bool
|
||||
+ create(name, ui_factory) → Workstream
|
||||
+ close(ws_id)
|
||||
+ get(ws_id) → Workstream
|
||||
+ get_active() → Workstream
|
||||
@@ -277,17 +204,11 @@ class "Workstream" as Ws <<dataclass>> {
|
||||
+ id: str
|
||||
+ name: str
|
||||
+ state: WorkstreamState
|
||||
+ session: ChatSession | None
|
||||
+ ui: SessionUI | None
|
||||
+ worker_thread: Thread | None
|
||||
+ session: ChatSession
|
||||
+ ui: SessionUI
|
||||
+ worker_thread: Thread
|
||||
+ error_message: str
|
||||
+ last_active: float
|
||||
+ kind: WorkstreamKind
|
||||
+ user_id: str
|
||||
+ parent_ws_id: str | None
|
||||
+ project_id: str | None
|
||||
- _fork_reservation_token: str
|
||||
- _closed: bool
|
||||
- _lock: Lock
|
||||
}
|
||||
|
||||
@@ -358,13 +279,12 @@ class "ModelRegistry" as ModelReg {
|
||||
- _models: dict[str, ModelConfig]
|
||||
- _clients: dict[str, Any]
|
||||
- _providers: dict[str, LLMProvider]
|
||||
- _admissions: dict[str, ModelAdmission]
|
||||
- _client_lock: Lock
|
||||
+ default: str
|
||||
+ fallback: list[str]
|
||||
+ agent_model: str | None
|
||||
--
|
||||
+ resolve_binding(alias) → (client, model, config, provider, admission, generation)
|
||||
+ resolve(alias) → (client, model, config)
|
||||
+ get_client(alias) → Any
|
||||
+ get_provider(alias) → LLMProvider
|
||||
+ has_alias(alias) → bool
|
||||
@@ -378,22 +298,6 @@ class "ModelRegistry" as ModelReg {
|
||||
core/model_registry.py
|
||||
}
|
||||
|
||||
class "ModelAdmission" as ModelAdmission {
|
||||
- alias: str
|
||||
- _limit: int
|
||||
- _in_flight: int
|
||||
- _waiters: deque
|
||||
+ acquire(cancel_ref) → AdmissionLease
|
||||
+ set_limit(limit)
|
||||
+ snapshot() → AdmissionSnapshot
|
||||
--
|
||||
Per-process FIFO generation gate.
|
||||
Stable across alias hot reloads;
|
||||
queue time is deadline credit.
|
||||
--
|
||||
core/admission.py
|
||||
}
|
||||
|
||||
class "ModelConfig" as ModelCfg <<frozen>> {
|
||||
+ alias: str
|
||||
+ provider: str
|
||||
@@ -403,10 +307,6 @@ class "ModelConfig" as ModelCfg <<frozen>> {
|
||||
+ temperature: float | None
|
||||
+ max_tokens: int | None
|
||||
+ reasoning_effort: str | None
|
||||
+ max_concurrency: int
|
||||
+ auth_mode: str
|
||||
+ obo_audience: str
|
||||
+ obo_scopes: str
|
||||
}
|
||||
|
||||
' Circuit breaker state
|
||||
@@ -476,35 +376,22 @@ LLMProvider <|.. AnthropicProv
|
||||
OpenAIProv <|-- GoogleProv
|
||||
|
||||
ChatSession --> SessionUI : uses
|
||||
ChatSession --> ResolvedBinding : owns coherent snapshot
|
||||
ChatSession --> ModelTurnFn : every model-backed role
|
||||
ChatSession --> LLMProvider : delegates LLM calls
|
||||
ChatSession --> MCPMgr : optional
|
||||
ChatSession --o ToolSearchMgr : _tool_search
|
||||
ChatSession --> ModelReg : optional
|
||||
ChatSession <|-- HeadlessSession
|
||||
|
||||
SessionMgr --> "*" Ws : manages
|
||||
SessionMgr --> KindAdapter : delegates construction
|
||||
SessionMgr --> EventEmitter : lifecycle fan-out
|
||||
WsMgr --> "*" Ws : manages
|
||||
Ws --> "1" ChatSession : wraps
|
||||
Ws --> "1" SessionUI : wraps
|
||||
Ws --> "1" WsState : has
|
||||
|
||||
KindAdapter ..> ChatSession : constructs
|
||||
WsMgr ..> ChatSession : creates via\nsession_factory(ui, model_alias)
|
||||
|
||||
ModelReg --> "*" ModelCfg : holds
|
||||
ModelReg --> "*" LLMProvider : caches
|
||||
ModelReg --> "*" ModelAdmission : owns per alias
|
||||
LLMProvider --> ModelCaps : returns
|
||||
ModelReg --> ResolvedBinding : resolves atomically
|
||||
ResolvedBinding --> ModelLane
|
||||
ModelLane --> LLMProvider
|
||||
ModelLane --> ModelCaps
|
||||
ModelLane --> ModelCfg : auth/config snapshot
|
||||
ModelLane --> ModelAdmission : admission lease
|
||||
ModelTurnFn --> ModelLane
|
||||
ModelTurnFn --> ModelTurnResult
|
||||
ModelTurnFn ..> BackendAuth : per-call resolver
|
||||
|
||||
ChatSession --> HealthMon : checks circuit
|
||||
HealthMon --> "1" CircuitState : has
|
||||
@@ -517,9 +404,7 @@ note bottom of ChatSession
|
||||
Provider-agnostic — delegates all LLM
|
||||
communication to LLMProvider adapters.
|
||||
|
||||
Every live/durable publication is fenced by
|
||||
its generation. Model calls use immutable lanes;
|
||||
provider-wire mutation stays at lowering.
|
||||
core/session.py (~2700 lines)
|
||||
end note
|
||||
|
||||
@enduml
|
||||
|
||||
@@ -1,171 +1,183 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
title Turnstone — Generation-Fenced Conversation Turn
|
||||
title Turnstone — Conversation Turn Lifecycle
|
||||
|
||||
skinparam sequenceArrowThickness 1.5
|
||||
skinparam sequenceLifeLineBackgroundColor #F5F5F5
|
||||
|
||||
participant "HTTP / CLI\ncaller" as User
|
||||
participant "SessionManager" as Manager
|
||||
participant "ChatSession" as Session
|
||||
participant "SessionUIBase" as UI
|
||||
participant "Accepted-row handoff\n(total live prefix)" as Handoff
|
||||
participant "model_turn()\n+ lowering" as Plant
|
||||
participant "ModelAdmission\n(per alias)" as Admission
|
||||
participant "LLM provider" as Provider
|
||||
participant "Tool workers" as Tools
|
||||
database "StorageBackend\n(SQLite / PostgreSQL)" as Storage
|
||||
participant "User /\nHTTP Client" as User
|
||||
participant "ChatSession" as CS
|
||||
participant "SessionUI" as UI
|
||||
participant "LLMProvider\n(OpenAI / Anthropic)" as LLM
|
||||
participant "Tool Executor\n(ThreadPool)" as TP
|
||||
database "SQLite" as DB
|
||||
|
||||
== Admission and generation claim ==
|
||||
== User Input ==
|
||||
|
||||
User -> Manager : dispatch send on one Workstream
|
||||
Manager -> Session : bind_acting_user(principal)\nsend(text, attachments, send_id)
|
||||
activate Session
|
||||
Session -> Session : refresh immutable ResolvedModelBinding
|
||||
User -> CS : send(user_input)
|
||||
activate CS
|
||||
|
||||
opt token budget exhausted
|
||||
Session -> UI : approve_tools(__budget_override__)
|
||||
note right of UI
|
||||
This gate precedes a generation claim but carries
|
||||
a monotonic cancellation witness. Stop cannot be
|
||||
mistaken for a budget-policy denial.
|
||||
end note
|
||||
end
|
||||
CS -> CS : messages.append({role: "user", content: input})
|
||||
CS -> DB : save_message(ws_id, "user", input)
|
||||
|
||||
Session -> Session : _claim_generation() → generation N\ninstall fresh cancel event
|
||||
Session -> Session : plan memory / participant context
|
||||
Session -> Handoff : admit USER row\ncommit_key + prefix revision
|
||||
Session -> Storage : ordered durable batch:\nappend canonical user Turn + metadata
|
||||
== LLM Call Loop ==
|
||||
|
||||
note over Session, Handoff
|
||||
Every accepted conversation row enters this lane before durability:
|
||||
USER, ASSISTANT, TOOL, SYSTEM, compaction checkpoints, and cancellation
|
||||
markers. Admission shares the handoff lock with its live UI transition
|
||||
or history_resync repair event.
|
||||
end note
|
||||
group loop [while tool_calls present]
|
||||
|
||||
note over Handoff, Storage
|
||||
_commit_for_generation(N) admits bounded live mutations under the
|
||||
generation lock, then executes immutable persistence closures in FIFO
|
||||
ticket order. A force successor either follows the whole commit or
|
||||
prevents it. /history projects durable prefix + pending journal suffix;
|
||||
durable ACK removes the pending copy without changing the prefix revision.
|
||||
end note
|
||||
CS -> UI : on_turn_start()
|
||||
note right of UI
|
||||
SessionUIBase resets the per-turn inflight
|
||||
buffers (_ws_inflight_content / reasoning /
|
||||
seq) that fuel the SSE in_progress_snapshot
|
||||
event for mid-stream refresh resume.
|
||||
end note
|
||||
|
||||
opt already over the hard context ceiling
|
||||
Session -> Session : compact before first model call\n(preserve the new user turn)
|
||||
end
|
||||
CS -> UI : on_state_change("thinking")
|
||||
CS -> UI : on_thinking_start()
|
||||
|
||||
== Model / tool loop ==
|
||||
CS -> LLM : provider.create_streaming(\n client, model, messages, tools, ...)\n (normalized StreamChunk iterator)
|
||||
activate LLM
|
||||
|
||||
loop until final answer and no queued input
|
||||
Session -> UI : on_turn_start()\nreset per-stream replay buffers
|
||||
Session -> UI : state = thinking\non_thinking_start()
|
||||
Session -> Session : _stream_response(N)\nretry + fallback policy
|
||||
Session -> Plant : model_turn(active ModelLane, Turns,\n tools, cancel_ref, on_chunk)
|
||||
activate Plant
|
||||
Plant -> Plant : canonical Turns → provider wire\nrestore ids + repair + lane-specific fold
|
||||
Plant -> Plant : materialize attachment refs\n(nested perception before outer slot)
|
||||
Plant -> Admission : acquire(cancel_ref)
|
||||
activate Admission
|
||||
Plant -> Plant : resolve per-call backend credential\nfrom lane's pinned ModelConfig
|
||||
Plant -> Provider : create_streaming(...)
|
||||
activate Provider
|
||||
note right of CS
|
||||
Retry up to 3× on transient errors:
|
||||
RateLimitError, APITimeoutError,
|
||||
APIConnectionError, InternalServerError,
|
||||
ServiceUnavailableError, APIError
|
||||
Backoff: 1s, 2s, 4s
|
||||
end note
|
||||
|
||||
loop normalized stream chunks
|
||||
Provider --> Plant : StreamChunk
|
||||
Plant --> Session : on_chunk(StreamChunk)
|
||||
Session -> Session : check cancel event + generation N
|
||||
Session -> UI : reasoning / content / info token
|
||||
end
|
||||
== Streaming Response ==
|
||||
|
||||
Provider --> Plant : finish + usage + native blocks
|
||||
deactivate Provider
|
||||
Plant -> Plant : drain + re-ingest assistant Turn\nwith serving-lane provenance
|
||||
Plant -> Admission : release before retry backoff
|
||||
deactivate Admission
|
||||
Plant --> Session : ModelTurnResult
|
||||
deactivate Plant
|
||||
|
||||
Session -> UI : on_stream_end()
|
||||
Session -> Session : generation-fenced result commit:\nappend assistant Turn + token accounting
|
||||
Session -> UI : on_turn_committed()
|
||||
Session -> Handoff : admit ASSISTANT row\ncommit_key + prefix revision
|
||||
Session -> Storage : ordered durable assistant row\n(content + tool mirror + native lane)
|
||||
|
||||
alt no tool calls
|
||||
opt over soft threshold
|
||||
Session -> Session : cooperative / end-of-turn compaction
|
||||
Session -> Handoff : admit SYSTEM/source=compaction\ncheckpoint projection
|
||||
Session -> Storage : append checkpoint summary marker\nwith source watermark
|
||||
note right of Storage
|
||||
Full history remains durable. Resume loads
|
||||
[summary] + rows after the checkpoint.
|
||||
end note
|
||||
opt model stopped for compaction
|
||||
Session -> Handoff : admit USER/source=compaction_resume row
|
||||
Session -> Storage : append synthetic compaction_resume Turn
|
||||
end
|
||||
end
|
||||
alt queued messages drained
|
||||
Session -> Handoff : admit combined queued USER row
|
||||
Session -> Storage : append combined queued user Turn
|
||||
else truly complete
|
||||
Session -> UI : state = idle
|
||||
end
|
||||
else tool calls present
|
||||
Session -> UI : state = running
|
||||
Session -> Session : prepare items + previews\nattach cancellation witnesses
|
||||
|
||||
opt one or more items require a human
|
||||
Session -> UI : approve_tools(items)\nregister independent ApprovalCycle
|
||||
note right of UI
|
||||
Parallel agents may own concurrent cycles.
|
||||
cycle_id / call_id routes exactly one decision;
|
||||
Smart Approvals may clear qualifying items.
|
||||
end note
|
||||
User -> UI : approve / deny selected cycle
|
||||
UI --> Session : decision + optional feedback
|
||||
loop for each chunk in stream
|
||||
LLM --> CS : delta
|
||||
note right of CS
|
||||
on_thinking_stop() called on first
|
||||
delta token via _stop_spinner_once()
|
||||
end note
|
||||
alt reasoning_content present
|
||||
CS -> UI : on_reasoning_token(text)
|
||||
else content present
|
||||
CS -> UI : on_content_token(text)
|
||||
else tool_call delta
|
||||
CS -> CS : accumulate in tool_calls_acc
|
||||
else info_delta present
|
||||
CS -> UI : on_info(text)\n(e.g. server-side web search status)
|
||||
end
|
||||
end
|
||||
|
||||
Session -> Tools : execute admitted items in parallel
|
||||
activate Tools
|
||||
Tools --> UI : chunks + result card\nwith effect disposition
|
||||
Tools --> Session : outputs / errors / effect statuses
|
||||
deactivate Tools
|
||||
Session -> Session : output-guard evaluation\nthen generation N re-check
|
||||
note right of CS
|
||||
**Cancellation checkpoint:**
|
||||
_check_cancelled() runs per chunk.
|
||||
If cancel_event is set, raises
|
||||
GenerationCancelled — preserves
|
||||
partial content, emits idle state.
|
||||
end note
|
||||
|
||||
opt compaction owed before result sizing
|
||||
Session -> Session : compact, preserving assistant tool-call Turn
|
||||
Session -> Handoff : admit SYSTEM/source=compaction checkpoint
|
||||
Session -> Storage : append checkpoint marker
|
||||
LLM --> CS : stream complete (usage stats)
|
||||
deactivate LLM
|
||||
|
||||
CS -> UI : on_thinking_stop() (no-op guard: already called by _stop_spinner_once)
|
||||
CS -> UI : on_stream_end()
|
||||
|
||||
CS -> CS : _update_token_table()\ncalibrate chars_per_token ratio
|
||||
CS -> CS : messages.append(assistant_msg)
|
||||
CS -> UI : on_turn_committed()
|
||||
note right of UI
|
||||
Drops the per-turn inflight buffers — the
|
||||
assistant message is now in the history
|
||||
list, so the in_progress_snapshot must
|
||||
not re-render it during the next tool-
|
||||
execution window or the next streaming turn.
|
||||
end note
|
||||
CS -> DB : save_message(ws_id, "assistant", content)
|
||||
CS -> DB : save_message(ws_id, "tool_call", ...) ×N
|
||||
|
||||
== Tool Dispatch (if tool_calls) ==
|
||||
|
||||
alt no tool_calls
|
||||
CS -> UI : on_status(usage, context_window, effort)
|
||||
|
||||
opt prompt_tokens > context_window × auto_compact_pct
|
||||
CS -> CS : _compact_messages(auto=True)
|
||||
CS -> LLM : Non-streaming summarization call
|
||||
CS -> CS : Replace messages with [summary]
|
||||
end
|
||||
|
||||
opt first exchange & no title
|
||||
CS -> CS : Background thread: _generate_title()
|
||||
end
|
||||
|
||||
CS -> UI : on_state_change("idle")
|
||||
CS --> User : return
|
||||
|
||||
else has tool_calls
|
||||
CS -> UI : on_state_change("running")
|
||||
|
||||
== Phase 1: Prepare ==
|
||||
CS -> CS : [_prepare_tool(tc) for tc in tool_calls]\nParse JSON args, validate,\nbuild preview + header
|
||||
|
||||
== Phase 2: Approve ==
|
||||
CS -> UI : on_state_change("attention")
|
||||
CS -> UI : approve_tools(items)
|
||||
activate UI
|
||||
note right of UI
|
||||
TerminalUI: input() prompt
|
||||
WebUI: _approval_event.wait()
|
||||
NullUI: returns (True, None)
|
||||
end note
|
||||
UI --> CS : (approved: bool, feedback: str?)
|
||||
deactivate UI
|
||||
CS -> UI : on_state_change("running")
|
||||
|
||||
== Phase 3: Execute ==
|
||||
CS -> TP : ThreadPoolExecutor(max_workers=4)\nrun_one(item) for each tool
|
||||
activate TP
|
||||
|
||||
note right of TP
|
||||
Parallel execution:
|
||||
bash → Popen + line-by-line streaming
|
||||
read_file → open().read() or base64 image
|
||||
search → grep subprocess
|
||||
edit_file → string replace
|
||||
task → _run_agent() sub-loop
|
||||
web_fetch → httpx + LLM summarize
|
||||
web_search → provider-native or SearxNG fallback
|
||||
memory/recall → SQLite
|
||||
end note
|
||||
|
||||
note right of TP
|
||||
bash: on_tool_output_chunk(call_id, line)
|
||||
called per stdout line,
|
||||
then on_tool_result(call_id, name, output, is_error).
|
||||
is_error=True when execution failed.
|
||||
call_id routes chunks/results to correct
|
||||
tool div during parallel execution.
|
||||
Other tools: on_tool_result() only.
|
||||
end note
|
||||
|
||||
TP --> CS : [(call_id, output), ...]
|
||||
deactivate TP
|
||||
|
||||
loop for each result
|
||||
CS -> CS : messages.append({role: "tool", ...})
|
||||
CS -> DB : save_message(ws_id, "tool_result", ...)
|
||||
end
|
||||
|
||||
opt user_feedback from approval
|
||||
CS -> CS : messages.append({role: "user", content: feedback})
|
||||
end
|
||||
|
||||
note right of CS : Loop back for next LLM call
|
||||
|
||||
else GenerationCancelled
|
||||
CS -> CS : Preserve partial content\nor roll back incomplete tools
|
||||
CS -> UI : on_info("[Generation cancelled]")
|
||||
CS -> UI : on_state_change("idle")
|
||||
CS --> User : return (no re-raise)
|
||||
end
|
||||
|
||||
Session -> Session : one generation-fenced batch:\nappend all Tool Turns, advisories, feedback
|
||||
Session -> Handoff : admit FIFO TOOL rows\ncommit keys + prefix revisions
|
||||
Session -> Storage : FIFO durable tool rows + metadata
|
||||
end
|
||||
end
|
||||
|
||||
== Stop / force-successor boundary ==
|
||||
deactivate CS
|
||||
|
||||
User -> Session : cancel()
|
||||
Session -> Session : atomically set generation event; snapshot\nmain stream, child scopes, judges, subprocesses
|
||||
Session -> Provider : close live stream handle
|
||||
Session -> Tools : abort child scopes + kill subprocess groups
|
||||
Session -> UI : resolve only cancelled operation's\napproval cycles
|
||||
opt cancellation produced accepted conversation rows
|
||||
Session -> Handoff : admit partial ASSISTANT and/or\nsynthesized TOOL cancellation markers
|
||||
Session -> Storage : idempotent keyed cancellation rows
|
||||
end
|
||||
|
||||
note over Session, Storage
|
||||
Every later publish/commit checks generation ownership. An abandoned
|
||||
worker may unwind, but cannot append Turns, overwrite state, resolve a
|
||||
successor approval, or repaint the successor UI. Observed tool effects
|
||||
are preserved as controller-authored cancellation receipts; unreviewed
|
||||
tool bytes are not laundered into model context.
|
||||
end note
|
||||
|
||||
deactivate Session
|
||||
@enduml
|
||||
|
||||
@@ -1,117 +1,134 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
title Turnstone — Tool Pipeline: Prepare, Approve, Execute, Fold
|
||||
title Turnstone — Tool Execution Pipeline (Three Phases)
|
||||
|
||||
start
|
||||
|
||||
partition "Phase 1 — Prepare and assess" #E8F5E9 {
|
||||
:Receive tool calls from one assistant Turn;
|
||||
:Capture the generation's cancel event\nand acting principal;
|
||||
partition "Phase 1: Prepare" #E8F5E9 {
|
||||
:Receive tool_calls list from LLM response;
|
||||
|
||||
while (more tool calls?) is (yes)
|
||||
:Parse arguments and dispatch to\nthe tool-specific preparer;
|
||||
if (preparation succeeds?) then (yes)
|
||||
:Build item: call_id, name, header, preview,\nneeds_approval, execute closure;
|
||||
while (more tool_calls?) is (yes)
|
||||
:Extract call_id, func_name, raw_args;
|
||||
|
||||
if (json.loads(raw_args) succeeds?) then (yes)
|
||||
:parsed_args = JSON dict;
|
||||
else (no)
|
||||
:Build an error item for this call only;\nkeep sibling calls valid;
|
||||
:Fallback 1: regex extraction;
|
||||
if (regex found keys?) then (yes)
|
||||
:parsed_args = extracted dict;
|
||||
else (no)
|
||||
:Fallback 2: bare string →\nPRIMARY_KEY_MAP[func_name];
|
||||
endif
|
||||
endif
|
||||
:Attach operation-local cancellation witness\nand pinned principal;
|
||||
|
||||
:Dispatch to _prepare_{func_name}();
|
||||
|
||||
note right
|
||||
**Dispatch table (16 built-in + tool_search):**
|
||||
┌───────────────┬──────────────────┐
|
||||
│ Tool │ Needs Approval? │
|
||||
├───────────────┼──────────────────┤
|
||||
│ bash │ ✓ Yes │
|
||||
│ read_file │ ✗ Auto-approve │
|
||||
│ write_file │ ✓ Yes │
|
||||
│ edit_file │ ✓ Yes │
|
||||
│ search │ ✗ Auto-approve │
|
||||
│ diff_file │ ✗ Auto-approve │
|
||||
│ web_fetch │ ✗ Auto-approve │
|
||||
│ web_search │ ✗ Auto-approve │
|
||||
│ tool_search │ ✗ Auto-approve │
|
||||
│ task_agent │ ✓ Yes │
|
||||
│ memory │ ✗ Auto-approve │
|
||||
│ recall │ ✗ Auto-approve │
|
||||
│ notify │ ✗ Auto-approve │
|
||||
│ watch │ ✓ create only │
|
||||
│ skill │ ✓ load only │
|
||||
│ read_resource │ ✓ Yes │
|
||||
│ use_prompt │ ✓ Yes │
|
||||
├───────────────┼──────────────────┤
|
||||
│ mcp__* │ ✓ Yes (external) │
|
||||
└───────────────┴──────────────────┘
|
||||
end note
|
||||
|
||||
:Build item dict:
|
||||
{call_id, func_name, header,
|
||||
preview, needs_approval,
|
||||
approval_label, execute: Callable};
|
||||
endwhile (no)
|
||||
|
||||
:Reject only unsafe ordering shapes\n(for example tasks read + write in one batch);
|
||||
:Run heuristic intent assessment immediately;
|
||||
:Start generation-pinned LLM judge in background;
|
||||
:Stamp one immutable Smart Approval\nsettings snapshot on the batch;
|
||||
|
||||
note right
|
||||
Preparation is per-call isolated: one bad preparer
|
||||
becomes one error Tool Turn rather than orphaning the
|
||||
assistant's entire tool-call set.
|
||||
end note
|
||||
}
|
||||
|
||||
partition "Phase 2 — Approval cycle" #FFF3E0 {
|
||||
:Apply explicit bypasses:\nskill / always / policy / blanket;
|
||||
|
||||
if (Smart Approvals enabled?) then (yes)
|
||||
:Wait within the batch's bounded judge deadline;
|
||||
:Auto-approve only LLM approve verdicts\nat or above the captured threshold;
|
||||
endif
|
||||
|
||||
if (human-gated items remain?) then (yes)
|
||||
:Acquire approval-publication lease;
|
||||
:Register independent ApprovalCycle\n(cycle_id, call_ids, event, result);
|
||||
:Publish approve_request + heuristic verdicts;
|
||||
partition "Phase 2: Approve" #FFF3E0 {
|
||||
if (any items need approval?) then (yes)
|
||||
:_emit_state("attention");
|
||||
:ui.approve_tools(items);
|
||||
|
||||
note right
|
||||
Parallel task agents can hold several cycles at once.
|
||||
A decision selects one cycle_id / call_id (or the oldest
|
||||
cycle for a legacy selector-less client). Double resolve
|
||||
is a guarded no-op; one cycle cannot wake a sibling.
|
||||
**auto_approve check is handled
|
||||
internally by ui.approve_tools()**
|
||||
|
||||
**TerminalUI**: Print headers/previews,
|
||||
prompt [y/n/a, optional message]
|
||||
If user chose "always":
|
||||
Add pending tool names to auto_approve_tools
|
||||
(auto-approve these tool types going forward)
|
||||
**WebUI**: Enqueue approve_request,
|
||||
block on _approval_event.wait()
|
||||
**NullUI**: Return (True, None)
|
||||
end note
|
||||
|
||||
if (operator approves?) then (yes)
|
||||
:Record decision and optional feedback;
|
||||
else (denies / policy blocks)
|
||||
:Mark only pending items denied;\nEffectStatus = none;
|
||||
if (user approved?) then (yes)
|
||||
:_emit_state("running");
|
||||
else (denied)
|
||||
:Mark all pending items as denied;
|
||||
:denial_msg = "Denied by user";
|
||||
:_emit_state("running");
|
||||
endif
|
||||
:Publish approval_resolved;\nunregister this cycle;
|
||||
else (all bypassed / auto-approved)
|
||||
:Publish tool_info with the exact\nauto-approve reason per item;
|
||||
endif
|
||||
|
||||
if (owning operation cancelled?) then (yes)
|
||||
:Cancel only cycles carrying that witness;
|
||||
:Stage every unstarted call as\nEffectStatus = none;
|
||||
stop
|
||||
else (all auto-approved)
|
||||
:ui enqueues tool_info event\n(no blocking);
|
||||
endif
|
||||
}
|
||||
|
||||
partition "Phase 3 — Execute" #E3F2FD {
|
||||
:Generation + cancellation checkpoint;
|
||||
|
||||
if (batch requires serial ordering?) then (yes)
|
||||
:Execute in provider order;
|
||||
else (no)
|
||||
:Execute via bounded ThreadPoolExecutor;
|
||||
partition "Phase 3: Execute" #E3F2FD {
|
||||
:_check_cancelled();
|
||||
note right: Cancellation checkpoint:\nraises GenerationCancelled if\ncancel event is set
|
||||
if (single tool call?) then (yes)
|
||||
:Execute sequentially:\nrun_one(items[0]);
|
||||
else (multiple)
|
||||
:Execute in parallel:\nThreadPoolExecutor(max_workers=4)\npool.map(run_one, items);
|
||||
endif
|
||||
|
||||
note right
|
||||
Each worker marks its call started only after the final
|
||||
generation/cancel check. A missing result after that edge is
|
||||
conservatively unknown; an unstarted call is definitively none.
|
||||
**run_one(item):**
|
||||
if item.error → return error string
|
||||
if item.denied → return denial message
|
||||
else → item["execute"](item)
|
||||
├─ _exec_bash: subprocess.run(["bash", script.sh])
|
||||
├─ _exec_read_file: open().readlines() or _exec_read_image (base64)
|
||||
├─ _exec_write_file: makedirs + write
|
||||
├─ _exec_edit_file: find_occurrences + replace
|
||||
├─ _exec_search: grep subprocess
|
||||
├─ _exec_web_fetch: httpx.get + LLM summary
|
||||
├─ _exec_web_search: SearxNG JSON GET (fallback for local models)
|
||||
├─ _exec_tool_search: BM25 search + expand_visible()
|
||||
├─ _exec_task: _run_agent(TASK_AGENT_TOOLS)
|
||||
├─ _exec_notify: HTTP POST to channel gateway
|
||||
├─ _exec_memory: structured memory save/search/delete/list
|
||||
├─ _exec_recall: conversation history FTS5 search
|
||||
├─ _exec_read_resource: MCPClientManager.read_resource_sync()
|
||||
├─ _exec_use_prompt: MCPClientManager.get_prompt_sync()
|
||||
└─ _exec_mcp_tool: MCPClientManager.call_tool_sync()
|
||||
end note
|
||||
|
||||
:Stream tool chunks to the matching call card;
|
||||
:Capture result / error / preview and effect disposition;
|
||||
:Collect results: [(call_id, output), ...];
|
||||
|
||||
if (Stop interrupts execution?) then (yes)
|
||||
:Abort child model scopes and subprocess groups;
|
||||
:Synthesize cancellation receipts;
|
||||
note right
|
||||
EffectStatus vocabulary:
|
||||
committed / none / unknown /
|
||||
partial / rolled_back.
|
||||
:_truncate_output() on each result\n(max context_window × chars_per_token × 0.5 chars\ndefault: ~context_window × 2 chars);
|
||||
|
||||
Observed but unreviewed bytes are omitted from the
|
||||
model-facing receipt; effect truth is retained.
|
||||
end note
|
||||
endif
|
||||
:bash: ui.on_tool_output_chunk(call_id, line) per stdout line;
|
||||
:ui.on_tool_result(call_id, name, output, is_error) for each;
|
||||
}
|
||||
|
||||
partition "Phase 4 — Guard and atomic fold" #F3E5F5 {
|
||||
if (compaction already owed?) then (yes)
|
||||
:Compact before sizing/folding results;\npreserve the assistant tool-call Turn;
|
||||
endif
|
||||
|
||||
:Truncate each result against the remaining shared budget;
|
||||
:Run heuristic + optional LLM output guard;
|
||||
:Re-check generation after guard work;
|
||||
|
||||
:Under one generation commit, append the complete\nTool Turn block + advisories + feedback;
|
||||
:Persist rows and effect/preview metadata\non the ordered durability lane;
|
||||
:Return results to the next model turn;
|
||||
}
|
||||
:Return (results, user_feedback);
|
||||
|
||||
stop
|
||||
|
||||
@enduml
|
||||
|
||||
@@ -3,7 +3,6 @@
|
||||
title Turnstone — Workstream State Machine
|
||||
|
||||
skinparam state {
|
||||
BackgroundColor<<lifecycle>> #ECEFF1
|
||||
BackgroundColor<<idle>> #E8F5E9
|
||||
BackgroundColor<<thinking>> #E3F2FD
|
||||
BackgroundColor<<running>> #FFF3E0
|
||||
@@ -11,18 +10,13 @@ skinparam state {
|
||||
BackgroundColor<<error>> #FFCDD2
|
||||
}
|
||||
|
||||
state "CREATING (persisted only)" as creating <<lifecycle>> : Hidden durable reservation.\nNot returned by ordinary list/open/history.
|
||||
state "IDLE" as idle <<idle>> : Waiting for user input.\nNo active LLM call or tool execution.
|
||||
state "THINKING" as thinking <<thinking>> : LLM streaming response.\nTokens flowing (reasoning + content).
|
||||
state "RUNNING" as running <<running>> : Tools executing.\nThreadPoolExecutor active.
|
||||
state "ATTENTION" as attention <<attention>> : Blocked on user action.\nTool approval needed.
|
||||
state "ERROR" as error <<error>> : Exception occurred.\nRecoverable on next send().
|
||||
state "CLOSED (persisted only)" as closed <<lifecycle>> : Unloaded, explicitly reopenable row.\nNot a live WorkstreamState member.
|
||||
|
||||
[*] --> creating : register exact incarnation\nstate="creating"
|
||||
creating --> idle : finalize + publish create\nemit ws_created
|
||||
creating --> [*] : immediate exact-token rollback\n(no lifecycle birth emitted)
|
||||
creating --> [*] : stale >2h recovery\natomic hard delete; no close event
|
||||
[*] --> idle : Session created
|
||||
|
||||
idle --> thinking : send() called\n_emit_state("thinking")
|
||||
|
||||
@@ -44,22 +38,6 @@ running --> error : Exception during\ntool execution
|
||||
|
||||
error --> thinking : New send() call\n_emit_state("thinking")
|
||||
|
||||
idle --> closed : close / eviction\n[journal reconciled]
|
||||
error --> closed : close\n[journal reconciled]
|
||||
thinking --> closed : close\n[journal reconciled]
|
||||
running --> closed : close\n[journal reconciled]
|
||||
attention --> closed : close\n[journal reconciled]
|
||||
closed --> [*] : hard delete
|
||||
closed --> idle : open / rehydrate
|
||||
|
||||
note right of closed
|
||||
Before every soft-close / eviction transition,
|
||||
the total accepted conversation-row journal must
|
||||
be durably reconciled. An unresolved row makes an
|
||||
explicit close return HTTP 409 (eviction refuses),
|
||||
and the workstream remains loaded in its live state.
|
||||
end note
|
||||
|
||||
thinking --> idle : cancel() called\nstream aborted\n_emit_state("idle")
|
||||
|
||||
running --> idle : cancel() called\n_emit_state("idle")
|
||||
@@ -67,75 +45,33 @@ running --> idle : cancel() called\n_emit_state("idle")
|
||||
attention --> idle : cancel() unblocks\napproval wait\n_emit_state("idle")
|
||||
|
||||
note left of idle
|
||||
**Generation-scoped Stop:**
|
||||
• Sets the active generation event.
|
||||
• Closes its SDK stream; aborts child model
|
||||
scopes and judges; kills subprocess groups.
|
||||
• Sweeps every approval cycle owned by the
|
||||
cancelled workstream operation.
|
||||
• Every later send/model live or durable commit
|
||||
re-checks generation ownership.
|
||||
|
||||
**force=true:** also abandons the stuck worker
|
||||
slot and emits stream_end + IDLE immediately.
|
||||
An orphaned send/model generation may unwind
|
||||
but cannot publish into a successor generation.
|
||||
Quick slash-command workers are a best-effort
|
||||
escape hatch: without generation checkpoints,
|
||||
one may finish an in-place mutation concurrently.
|
||||
|
||||
**Capacity eviction:** an IDLE candidate is only
|
||||
a hint. Per-ID + object lifecycle lanes and the
|
||||
workstream lock revalidate it as worker- and
|
||||
send-barrier-free,
|
||||
then install a terminal claim before slot swap.
|
||||
**Cancel escalation:**
|
||||
1. **Cooperative**: cancel() sets event + closes
|
||||
SDK stream → worker exits at next checkpoint
|
||||
2. **Force**: force=true abandons the worker
|
||||
thread, emits stream_end immediately.
|
||||
Orphaned thread still kills subprocesses
|
||||
but skips message mutations (generation
|
||||
counter prevents stale writes).
|
||||
end note
|
||||
|
||||
note right of thinking
|
||||
**Emitted via:**
|
||||
session._emit_state(state)
|
||||
→ ui.on_state_change(state)
|
||||
→ SessionManager state tail
|
||||
|
||||
**Propagation:**
|
||||
• WebUI → global SSE queue (ws_state)
|
||||
• Console → cluster event / HTTP state
|
||||
• CLI → SessionManager.set_state()
|
||||
|
||||
Non-terminal persistence may use StateWriter;
|
||||
a per-id tail orders storage + subscribers and
|
||||
prevents a late state from overwriting CLOSED.
|
||||
• Console → HTTP polling picks up state
|
||||
• CLI → WorkstreamManager.set_state()
|
||||
end note
|
||||
|
||||
note left of attention
|
||||
**Blocking mechanisms:**
|
||||
• TerminalUI: input() prompt
|
||||
• WebUI: one Event per ApprovalCycle
|
||||
• WebUI: threading.Event.wait()
|
||||
• ChannelBot: SSE event + Discord button
|
||||
• NullUI: auto-approve (never reaches)
|
||||
end note
|
||||
|
||||
note right of creating
|
||||
CREATING and CLOSED are storage lifecycle
|
||||
values, not members of WorkstreamState. The
|
||||
live enum remains IDLE / THINKING / RUNNING /
|
||||
ATTENTION / ERROR.
|
||||
|
||||
**Crash-abandoned CREATING recovery:**
|
||||
• Boot pass, then every 5 min even when idle
|
||||
eviction is disabled.
|
||||
• Only rows >2h old; manager loaded/pending
|
||||
IDs and live remote owners are protected.
|
||||
• The current stable node ID is not a live-owner
|
||||
exemption, allowing restart recovery.
|
||||
• Unknown liveness/storage fails closed. Deletion
|
||||
is atomic across dependents and attachment refs.
|
||||
• Tokenless legacy/corrupt rows are locked,
|
||||
reaped, and logged with a warning.
|
||||
|
||||
A loaded hard delete closes publication, drains
|
||||
admitted session durability + state tails, then
|
||||
conditionally removes the exact durable token.
|
||||
end note
|
||||
|
||||
@enduml
|
||||
|
||||
@@ -31,7 +31,7 @@ node "Docker Host" as host {
|
||||
Command: turnstone-console
|
||||
--port 8090
|
||||
Depends: server
|
||||
FNV-1a rendezvous router for
|
||||
Hash-ring router for
|
||||
multi-node clusters
|
||||
end note
|
||||
}
|
||||
@@ -69,7 +69,7 @@ apiclient --> server : HTTP + SSE\nport 8080
|
||||
' Internal connections
|
||||
server --> llm_api : OpenAI API\n(HTTPS/HTTP)
|
||||
|
||||
console --> server : HTTP proxy\n(FNV-1a rendezvous placement,\nproxy /node/{id}/*)
|
||||
console --> server : HTTP proxy\n(hash-ring lookup,\nproxy /node/{id}/*)
|
||||
|
||||
' Database connections (production/cluster profiles)
|
||||
server ..> pgbouncer : PostgreSQL\n(pool_size=2)
|
||||
|
||||
@@ -32,8 +32,7 @@ package "turnstone/sdk/ (Python)" {
|
||||
+ approve()
|
||||
+ command()
|
||||
+ cancel(ws_id)
|
||||
+ get_history(ws_id, limit) → WorkstreamHistoryResponse
|
||||
+ stream_events(ws_id, last_event_id?, history_token?)
|
||||
+ stream_events(ws_id)
|
||||
+ stream_global_events()
|
||||
+ send_and_wait()
|
||||
+ list_saved_workstreams()
|
||||
@@ -88,13 +87,6 @@ package "turnstone/sdk/ (Python)" {
|
||||
+ ok: bool
|
||||
}
|
||||
|
||||
class WorkstreamHistoryResponse <<type>> {
|
||||
+ ws_id: str
|
||||
+ messages: list[dict]
|
||||
+ cursor: int | None
|
||||
+ handoff_token: str | None
|
||||
}
|
||||
|
||||
class ServerEvent <<event>> {
|
||||
+ type: str
|
||||
+ ws_id: str
|
||||
@@ -113,7 +105,6 @@ package "turnstone/sdk/ (Python)" {
|
||||
TurnstoneConsole --> AsyncTurnstoneConsole : wraps
|
||||
TurnstoneConsole --> _SyncRunner : uses
|
||||
AsyncTurnstoneServer ..> TurnResult : returns
|
||||
AsyncTurnstoneServer ..> WorkstreamHistoryResponse : renders before SSE
|
||||
AsyncTurnstoneServer ..> ServerEvent : yields
|
||||
AsyncTurnstoneConsole ..> ClusterEvent : yields
|
||||
}
|
||||
@@ -131,8 +122,7 @@ package "sdk/typescript/ (TypeScript)" {
|
||||
class "TurnstoneServer" as TSServer <<ts>> {
|
||||
+ listWorkstreams()
|
||||
+ send()
|
||||
+ getHistory() → WorkstreamHistoryResponse
|
||||
+ streamEvents(cursor?, token?)
|
||||
+ streamEvents()
|
||||
+ sendAndWait()
|
||||
...
|
||||
}
|
||||
@@ -164,10 +154,4 @@ note right of AsyncTurnstoneServer
|
||||
(no type duplication)
|
||||
end note
|
||||
|
||||
note bottom of ServerEvent
|
||||
history_resync is a typed repair signal.
|
||||
SDKs expose the REST cursor/token handshake but
|
||||
never refetch, render, or reconnect automatically.
|
||||
end note
|
||||
|
||||
@enduml
|
||||
|
||||
@@ -1,191 +1,170 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
title Turnstone — Storage, Deferred Create, Fork, and Checkpoint Architecture
|
||||
title Turnstone — Storage Architecture
|
||||
|
||||
skinparam class {
|
||||
BackgroundColor<<protocol>> #E8EAF6
|
||||
BackgroundColor<<sqlite>> #C8E6C9
|
||||
BackgroundColor<<postgres>> #B3E5FC
|
||||
BackgroundColor<<lifecycle>> #FFF9C4
|
||||
BackgroundColor<<facade>> #FFF9C4
|
||||
BackgroundColor<<migration>> #FFE0B2
|
||||
BackgroundColor<<schema>> #F3E5F5
|
||||
BackgroundColor<<helper>> #FFE0B2
|
||||
}
|
||||
|
||||
interface "StorageBackend" as Storage <<protocol>> {
|
||||
+ load_message_turns(ws_id, checkpointed=True) → list[Turn]
|
||||
+ save_message(ws_id, role, content, metadata...)
|
||||
+ clone_workstream(source, destination, principal, expected_session) → ForkCloneSnapshot
|
||||
--
|
||||
+ register_workstream(..., state, reservation_token) → bool
|
||||
+ ensure_workstream_incarnation_snapshot(ws_id) → row + token
|
||||
+ finalize_deferred_create(ws_id, token, config...) → bool
|
||||
+ publish_deferred_create(ws_id, token) → bool
|
||||
+ delete_workstream_if_fork_reserved(ws_id, token) → bool
|
||||
+ delete_stale_creating_reservations(...) → list[ws_id]
|
||||
+ update_workstream_state(ws_id, state)
|
||||
+ delete_workstream(ws_id) → bool
|
||||
--
|
||||
+ attachment / project / memory / auth / governance APIs
|
||||
' -- Protocol --
|
||||
interface "StorageBackend" as SB <<protocol>> {
|
||||
+save_message(ws_id, role, content, ...)
|
||||
+load_messages(ws_id) → list[dict]
|
||||
+register_workstream(ws_id, node_id, name, state)
|
||||
+update_workstream_state(ws_id, state)
|
||||
+update_workstream_name(ws_id, name)
|
||||
+set_workstream_alias(ws_id, alias) → bool
|
||||
+update_workstream_title(ws_id, title)
|
||||
+resolve_workstream(alias_or_id) → str | None
|
||||
+delete_workstream(ws_id) → bool
|
||||
+prune_workstreams(retention_days) → (int, int)
|
||||
+list_workstreams(node_id, limit, *, parent_ws_id, kind, user_id) → list
|
||||
+save_workstream_config(ws_id, config)
|
||||
+load_workstream_config(ws_id) → dict
|
||||
+kv_get(key) → str | None
|
||||
+kv_set(key, value) → str | None
|
||||
+kv_delete(key) → bool
|
||||
+kv_list() → list[(str, str)]
|
||||
+kv_search(query) → list[(str, str)]
|
||||
+search_history(query, limit) → list
|
||||
+search_history_recent(limit) → list
|
||||
+create_user(user_id, username, display_name, pw_hash)
|
||||
+get_user(user_id) / get_user_by_username(username)
|
||||
+list_users() / delete_user(user_id)
|
||||
+create_api_token(...) / get_api_token_by_hash(hash)
|
||||
+list_api_tokens(user_id) / delete_api_token(id)
|
||||
+close()
|
||||
}
|
||||
|
||||
' -- Backends --
|
||||
class "SQLiteBackend" as SQLite <<sqlite>> {
|
||||
- _engine: sa.Engine
|
||||
- _fts5_available: bool
|
||||
-_engine: sa.Engine
|
||||
-_fts5_available: bool
|
||||
+__init__(path: str)
|
||||
--
|
||||
Fork clone: BEGIN IMMEDIATE
|
||||
FTS5 refresh in same transaction
|
||||
FTS5 full-text search
|
||||
Default pool, check_same_thread=False
|
||||
}
|
||||
|
||||
class "PostgreSQLBackend" as PG <<postgres>> {
|
||||
- _engine: sa.Engine
|
||||
-_engine: sa.Engine
|
||||
+__init__(url: str, pool_size: int = 2,\n max_overflow: int = 3)
|
||||
--
|
||||
Fork clone: SERIALIZABLE + row locks
|
||||
Retry SQLSTATE 40001 / 40P01
|
||||
DML success uses RETURNING rows
|
||||
tsvector + ILIKE search
|
||||
Connection pooling (5 max per process)
|
||||
}
|
||||
|
||||
class "_utils.py" as Utils <<helper>> {
|
||||
+ reconstruct_turns(rows) → list[Turn]
|
||||
+ recover_trajectory(turns) → list[Turn]
|
||||
+ reconstruct_turns_checkpointed(...)
|
||||
+ retain_attachment_refs(conn, ids)
|
||||
+ release_attachment_refs(conn, ids)
|
||||
+ clone_workstream_transaction(...) → ForkCloneSnapshot
|
||||
}
|
||||
|
||||
class "ForkCloneExpectation" as Expectation <<lifecycle>> {
|
||||
+ persona_config
|
||||
+ project_id / name / writable
|
||||
+ source_reservation_token
|
||||
+ destination_reservation_token
|
||||
}
|
||||
|
||||
class "ForkCloneSnapshot" as Snapshot <<lifecycle>> {
|
||||
+ turns: tuple[Turn, ...]
|
||||
+ config: dict[str, str]
|
||||
+ project_id: str | None
|
||||
}
|
||||
|
||||
class "workstreams" as Workstreams <<schema>> {
|
||||
ws_id PK
|
||||
state: creating | live state | closed
|
||||
user_id, node_id, kind, parent_ws_id
|
||||
project_id, persona, alias, title
|
||||
}
|
||||
|
||||
class "conversations" as Conversations <<schema>> {
|
||||
canonical persisted Turn rows
|
||||
provider_data + tool_calls mirror
|
||||
event_id, source, is_error, meta
|
||||
attachment-id ref list
|
||||
' -- Schema --
|
||||
class "_schema.py" as Schema <<schema>> {
|
||||
+metadata: MetaData
|
||||
+memories: Table
|
||||
+conversations: Table
|
||||
+workstreams: Table (node_id, alias, title,\n state, skill_id)
|
||||
+workstream_config: Table
|
||||
+users: Table (username, password_hash)
|
||||
+api_tokens: Table (token_hash, scopes)
|
||||
+channel_users: Table (channel_type)
|
||||
+scheduled_tasks: Table (..., skill)
|
||||
--
|
||||
compaction marker:
|
||||
source="compaction"
|
||||
meta.watermark=<folded row id>
|
||||
SQLAlchemy Core
|
||||
Single source of truth
|
||||
}
|
||||
|
||||
class "workstream_config" as WorkstreamConfig <<schema>> {
|
||||
PK (ws_id, key)
|
||||
stamped persona/session config
|
||||
private durable incarnation fence:
|
||||
__fork_destination_reservation
|
||||
' -- Migration --
|
||||
class "_migrate.py" as Migrate <<migration>> {
|
||||
+run_migrations(storage, backend)
|
||||
-_bootstrap_existing_sqlite()
|
||||
--
|
||||
Programmatic Alembic
|
||||
Auto-bootstrap existing DBs
|
||||
}
|
||||
|
||||
class "workstream_attachments" as Attachments <<schema>> {
|
||||
content-addressed blob
|
||||
attachment_id, bytes, kind
|
||||
refcount
|
||||
class "migrations/" as Versions <<migration>> {
|
||||
001_initial_schema.py
|
||||
002_user_identity.py
|
||||
}
|
||||
|
||||
class "projects + project_members" as Projects <<schema>> {
|
||||
visibility / owner / membership
|
||||
active project-memory envelope
|
||||
' -- Registry --
|
||||
class "_registry.py" as Registry {
|
||||
-_storage: StorageBackend | None
|
||||
+init_storage(backend, path, url) → StorageBackend
|
||||
+get_storage() → StorageBackend
|
||||
+reset_storage()
|
||||
--
|
||||
Auto-initializes SQLite
|
||||
if not configured
|
||||
}
|
||||
|
||||
class "SessionManager" as Manager <<lifecycle>> {
|
||||
+ create(..., defer_emit_created)
|
||||
+ commit_create(ws)
|
||||
+ discard(ws)
|
||||
+ reap_stale_creating_reservations(max_age=2h)
|
||||
+ open / close / delete
|
||||
' -- Facade --
|
||||
class "memory.py" as Facade <<facade>> {
|
||||
+save_message()
|
||||
+load_messages()
|
||||
+register_workstream()
|
||||
+update_workstream_state()
|
||||
+save_workstream_config()
|
||||
+save_memory() / delete_memory()
|
||||
+search_memories()
|
||||
+... (all delegated functions)
|
||||
--
|
||||
Thin delegation to
|
||||
get_storage()
|
||||
Silent failure behavior
|
||||
}
|
||||
|
||||
class "ChatSession" as Session <<lifecycle>> {
|
||||
+ append canonical Turns
|
||||
+ compact / resume checkpoint
|
||||
+ fork_from_storage(...)
|
||||
' -- Consumers --
|
||||
class "session.py\nChatSession" as Session {
|
||||
}
|
||||
|
||||
SQLite ..|> Storage
|
||||
PG ..|> Storage
|
||||
SQLite --> Utils
|
||||
PG --> Utils
|
||||
class "server.py\nWeb UI" as Server {
|
||||
}
|
||||
|
||||
Storage --> Workstreams
|
||||
Storage --> Conversations
|
||||
Storage --> WorkstreamConfig
|
||||
Storage --> Attachments
|
||||
Storage --> Projects
|
||||
class "cli.py\nTerminal" as CLI {
|
||||
}
|
||||
|
||||
Manager --> Storage : lifecycle reservation + state
|
||||
Session --> Storage : turn durability + resume
|
||||
Session --> Expectation : construction witness
|
||||
Storage --> Snapshot : atomic clone result
|
||||
Expectation --> Utils : checked inside transaction
|
||||
Utils --> Snapshot : builds
|
||||
' -- Relationships --
|
||||
SQLite ..|> SB
|
||||
PG ..|> SB
|
||||
|
||||
note right of Manager
|
||||
**Deferred create publication**
|
||||
1. INSERT workstream as state="creating" and store a fresh
|
||||
private token in the same transaction.
|
||||
2. Construct UI/session and run attachment/fork gates while
|
||||
ordinary list/open/history reads exclude the row.
|
||||
3. finalize_deferred_create atomically applies config/alias.
|
||||
4. publish_deferred_create compare-and-swaps creating → idle.
|
||||
5. Only then emit ws_created.
|
||||
SQLite --> Schema : uses
|
||||
PG --> Schema : uses
|
||||
|
||||
Any normal prepublication failure immediately calls exact token-checked
|
||||
deletion. The token survives publication as the row's incarnation fence:
|
||||
rollback or later hard delete can never ABA-delete a replacement row.
|
||||
A legacy row acquires the same private token atomically when rehydrate,
|
||||
delete, or fork preflight takes its authoritative snapshot. Loaded hard
|
||||
delete drains admitted session durability before its token-checked delete.
|
||||
Registry --> SB : creates
|
||||
Registry --> Migrate : calls
|
||||
|
||||
Migrate --> Versions : applies
|
||||
Migrate --> Schema : references
|
||||
|
||||
Facade --> Registry : get_storage()
|
||||
|
||||
Session --> Facade : imports
|
||||
Server --> Facade : imports
|
||||
CLI --> Facade : imports
|
||||
|
||||
' -- Config --
|
||||
note right of Registry
|
||||
[database]
|
||||
backend = "sqlite" | "postgresql"
|
||||
url = "postgresql+psycopg://..."
|
||||
path = ".turnstone.db"
|
||||
pool_size = 2 (+ 3 overflow)
|
||||
end note
|
||||
|
||||
note left of Manager
|
||||
**Crash-abandoned hidden-create recovery**
|
||||
• Boot pass; long-lived processes repeat every 5 min,
|
||||
even when ordinary idle eviction is disabled.
|
||||
• Candidates remain state="creating", are >2h old,
|
||||
and are absent from the manager loaded/pending set.
|
||||
• Live remote owners are protected. The current stable
|
||||
node ID does not self-protect, enabling restart recovery.
|
||||
• Unknown liveness or storage failure deletes nothing.
|
||||
• One transaction rechecks state, age, and token, then
|
||||
hard-deletes dependents and releases attachment refs.
|
||||
• Tokenless legacy/corrupt rows use their locked durable
|
||||
row as the incarnation fence and log a warning.
|
||||
• Retention pruning excludes creating rows. Recovery never
|
||||
closes or publishes them as live WorkstreamState values.
|
||||
note bottom of SQLite
|
||||
Default backend.
|
||||
Zero-config for
|
||||
single-node / dev.
|
||||
end note
|
||||
|
||||
note bottom of Utils
|
||||
**Atomic fork clone**
|
||||
• Reject a provisional source; compare the source incarnation captured
|
||||
by canonical preflight; re-authorize project visibility and compare the
|
||||
live session envelope inside the transaction.
|
||||
• Require a same-owner, empty destination still in creating state
|
||||
with the exact reservation token.
|
||||
• Copy the checkpoint-bounded canonical trajectory and config;
|
||||
retain every referenced attachment or roll everything back.
|
||||
• Preserve/rebase a valid compaction checkpoint watermark and
|
||||
return the exact snapshot installed into the live destination.
|
||||
end note
|
||||
|
||||
note bottom of Conversations
|
||||
Full transcript rows are never deleted by compaction. Normal resume
|
||||
loads the latest valid [summary] + rows after its watermark; audit and
|
||||
export can request the full marker-free history.
|
||||
note bottom of PG
|
||||
Production backend.
|
||||
Multi-node / Docker default.
|
||||
Use PgBouncer (transaction mode)
|
||||
for clusters > 50 nodes.
|
||||
end note
|
||||
|
||||
@enduml
|
||||
|
||||
@@ -1,153 +1,190 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
title Turnstone — User Authentication and Model-Backend Credentials
|
||||
title Turnstone — Authentication Architecture
|
||||
|
||||
skinparam class {
|
||||
BackgroundColor<<core>> #E8EAF6
|
||||
BackgroundColor<<token>> #C8E6C9
|
||||
BackgroundColor<<jwt>> #C8E6C9
|
||||
BackgroundColor<<storage>> #B3E5FC
|
||||
BackgroundColor<<runtime>> #FFE0B2
|
||||
BackgroundColor<<model>> #F3E5F5
|
||||
BackgroundColor<<endpoint>> #FFE0B2
|
||||
BackgroundColor<<scope>> #F3E5F5
|
||||
}
|
||||
|
||||
package "Request identity" {
|
||||
class "AuthMiddleware / check_request()" as RequestAuth <<core>> {
|
||||
Extract bearer or HttpOnly cookie
|
||||
Validate audience + expiry
|
||||
Check scope / permission
|
||||
Publish AuthResult in request state
|
||||
}
|
||||
|
||||
class "AuthResult" as AuthResult <<core>> {
|
||||
+ user_id: str
|
||||
+ scopes: frozenset[str]
|
||||
+ permissions: frozenset[str]
|
||||
+ token_source: str
|
||||
}
|
||||
|
||||
class "JWT" as JWT <<token>> {
|
||||
HS256, sub, aud, iat, exp
|
||||
console proxy mints short-lived
|
||||
server-audience identity
|
||||
}
|
||||
|
||||
class "API / config token" as ApiToken <<token>> {
|
||||
ts_* token: SHA-256 DB lookup
|
||||
config token: constant-time compare
|
||||
}
|
||||
|
||||
class "users / roles / api_tokens" as UserTables <<storage>> {
|
||||
password hash + token hash
|
||||
role-derived permissions
|
||||
}
|
||||
' -- Core Auth --
|
||||
class "AuthConfig" as AC <<core>> {
|
||||
+enabled: bool
|
||||
+tokens: dict[str, str]
|
||||
+check(token) → role | None
|
||||
--
|
||||
Static config-file tokens
|
||||
hmac.compare_digest
|
||||
}
|
||||
|
||||
package "Immutable model binding" {
|
||||
class "ModelRegistry" as Registry <<model>> {
|
||||
+ resolve_binding(alias)
|
||||
+ generation: int
|
||||
--
|
||||
Atomically resolves client, provider,
|
||||
model, ModelConfig, generation.
|
||||
}
|
||||
|
||||
class "ModelConfig snapshot" as ModelConfig <<model>> {
|
||||
+ alias / provider / endpoint / static key
|
||||
+ auth_mode
|
||||
+ obo_audience
|
||||
+ obo_scopes
|
||||
--
|
||||
static | entra_obo | entra_app | rfc8693_obo
|
||||
}
|
||||
|
||||
class "ModelLane" as Lane <<model>> {
|
||||
+ client / provider / model / capabilities
|
||||
+ backend_auth_config: ModelConfig
|
||||
+ backend_auth_resolver: Callable
|
||||
}
|
||||
|
||||
class "Model definitions" as ModelTable <<storage>> {
|
||||
DB + config-file definitions
|
||||
encrypted protected fields
|
||||
}
|
||||
class "AuthResult" as AR <<core>> {
|
||||
+user_id: str
|
||||
+scopes: frozenset[str]
|
||||
+token_source: str
|
||||
+has_scope(scope) → bool
|
||||
}
|
||||
|
||||
package "Per-call credential resolution" {
|
||||
class "resolve_model_backend_auth_token()" as Resolver <<runtime>> {
|
||||
+ alias + pinned ModelConfig
|
||||
+ initiating principal_id
|
||||
+ ConfigStore + mint client
|
||||
→ dynamic token | None | fail closed
|
||||
}
|
||||
|
||||
class "Model mint client" as Mint <<runtime>> {
|
||||
+ mint_model_obo_token_sync(...)
|
||||
+ mint_app_token_sync(...)
|
||||
--
|
||||
Cached by alias / principal / grant leg;
|
||||
retains refusal cause for diagnostics.
|
||||
}
|
||||
|
||||
class "OIDC / OBO protected state" as OBOState <<storage>> {
|
||||
encrypted user refresh credential
|
||||
deployment Fernet key
|
||||
configured grant profile
|
||||
}
|
||||
|
||||
class "lane_call_client()" as CallClient <<runtime>> {
|
||||
cancel check before mint
|
||||
resolve once per plant call
|
||||
cancel check after mint
|
||||
client.with_options(api_key=token)
|
||||
}
|
||||
|
||||
class "Provider SDK request" as ProviderCall <<runtime>> {
|
||||
Anthropic: x-api-key
|
||||
OpenAI-style: Authorization Bearer
|
||||
}
|
||||
class "check_request()" as CR <<core>> {
|
||||
auth_config, method, path,
|
||||
auth_header, cookie_header,
|
||||
jwt_secret, storage
|
||||
→ (allowed, status, msg, AuthResult)
|
||||
--
|
||||
1. Auth disabled → allow
|
||||
2. Public path → allow
|
||||
3. Extract Bearer / cookie
|
||||
4. Detect token type
|
||||
5. Validate → AuthResult
|
||||
6. Check scope vs path
|
||||
}
|
||||
|
||||
RequestAuth --> JWT : validates
|
||||
RequestAuth --> ApiToken : validates
|
||||
RequestAuth --> UserTables : lookup + permissions
|
||||
RequestAuth --> AuthResult : returns
|
||||
' -- Token Types --
|
||||
class "JWT (HS256)" as JWT <<jwt>> {
|
||||
sub: user_id
|
||||
scopes: "read,write,approve"
|
||||
src: "password" | "database"
|
||||
iat, exp (24h default)
|
||||
--
|
||||
Detected by: contains "."
|
||||
Validated locally
|
||||
No DB call
|
||||
}
|
||||
|
||||
ModelTable --> Registry : load / hot reload
|
||||
Registry --> ModelConfig : immutable snapshot
|
||||
Registry --> Lane : coherent binding
|
||||
class "API Token" as AT <<jwt>> {
|
||||
Format: ts_ + 64 hex
|
||||
Stored: SHA-256 hash
|
||||
--
|
||||
Detected by: starts with "ts_"
|
||||
Lookup by hash in DB
|
||||
Expiry check
|
||||
}
|
||||
|
||||
AuthResult --> Resolver : initiating principal
|
||||
Lane --> Resolver : callable + pinned config
|
||||
Resolver --> Mint : dynamic modes only
|
||||
Mint --> OBOState : decrypt / grant policy
|
||||
CallClient --> Lane
|
||||
CallClient --> Resolver
|
||||
CallClient --> ProviderCall : cloned SDK client
|
||||
class "Config Token" as CT <<core>> {
|
||||
Raw value in memory
|
||||
Role: "read" | "full"
|
||||
--
|
||||
Detected by: fallback
|
||||
hmac.compare_digest
|
||||
No DB needed
|
||||
}
|
||||
|
||||
note right of Resolver
|
||||
**Mode policy**
|
||||
• static: return None; registry client's explicit key remains.
|
||||
• entra_obo / rfc8693_obo: require an effective principal. HTTP
|
||||
turns pin the authenticated initiator; single-user internal lanes
|
||||
may use their session owner. Never borrow another generation's identity.
|
||||
• entra_app: use deployment app identity, no user required.
|
||||
• rfc8693_obo alone sends obo_scopes; each dynamic mode is paired
|
||||
with its required Entra or RFC 8693 grant profile.
|
||||
' -- Scopes --
|
||||
class "Scope Hierarchy" as SH <<scope>> {
|
||||
read: {read}
|
||||
write: {read, write}
|
||||
approve: {read, write, approve}
|
||||
--
|
||||
GET → read
|
||||
POST write paths → write
|
||||
POST /api/workstreams/{ws_id}/approve → approve
|
||||
/api/admin/* → approve
|
||||
}
|
||||
|
||||
' -- Storage --
|
||||
class "users" as UT <<storage>> {
|
||||
user_id (PK)
|
||||
username (unique)
|
||||
display_name
|
||||
password_hash (bcrypt)
|
||||
created
|
||||
}
|
||||
|
||||
class "api_tokens" as TT <<storage>> {
|
||||
token_id (PK)
|
||||
token_hash (SHA-256, unique)
|
||||
token_prefix
|
||||
user_id → users
|
||||
name, scopes
|
||||
created, expires
|
||||
}
|
||||
|
||||
' -- Endpoints --
|
||||
class "POST /api/auth/login" as Login <<endpoint>> {
|
||||
{username, password}
|
||||
OR {token: "ts_xxx"}
|
||||
→ {jwt, role, scopes, user_id}
|
||||
--
|
||||
Sets HttpOnly cookie
|
||||
}
|
||||
|
||||
class "GET /api/auth/status" as Status <<endpoint>> {
|
||||
→ {auth_enabled, has_users,
|
||||
setup_required}
|
||||
--
|
||||
Public (no auth)
|
||||
Drives UI setup wizard
|
||||
}
|
||||
|
||||
class "POST /api/auth/setup" as Setup <<endpoint>> {
|
||||
{username, display_name, password}
|
||||
→ {jwt, user_id, scopes}
|
||||
--
|
||||
Public (no auth)
|
||||
Only when zero users exist
|
||||
Returns 409 if already set up
|
||||
}
|
||||
|
||||
class "Admin API (Console)" as Admin <<endpoint>> {
|
||||
POST/GET/DELETE users
|
||||
POST/GET tokens
|
||||
DELETE tokens/{id}
|
||||
--
|
||||
Requires approve scope
|
||||
}
|
||||
|
||||
' -- Relationships --
|
||||
CR --> AC : config tokens
|
||||
CR --> JWT : validate
|
||||
CR --> AT : hash lookup
|
||||
CR --> CT : hmac check
|
||||
CR --> AR : returns
|
||||
CR --> SH : checks
|
||||
|
||||
Login --> JWT : issues
|
||||
Login --> UT : verify password
|
||||
Login --> TT : verify API token
|
||||
|
||||
Setup --> UT : create first user
|
||||
Setup --> JWT : issues
|
||||
|
||||
AT --> TT : lookup by hash
|
||||
Admin --> UT : CRUD
|
||||
Admin --> TT : CRUD
|
||||
|
||||
AR --> SH : scopes from
|
||||
|
||||
JWT ..> AR : produces
|
||||
AT ..> AR : produces
|
||||
CT ..> AR : produces
|
||||
|
||||
note right of CR
|
||||
**Middleware Flow**
|
||||
AuthMiddleware on every request:
|
||||
1. Extract token from header/cookie
|
||||
2. Detect type (JWT / ts_ / config)
|
||||
3. Validate → AuthResult
|
||||
4. Set ctx_user_id for logging
|
||||
5. Store auth_result in scope state
|
||||
end note
|
||||
|
||||
note bottom of CallClient
|
||||
Dynamic credentials are minted at dispatch, not cached in the registry
|
||||
snapshot. Endpoint, audience, scopes, auth mode, and static-key presence stay
|
||||
pinned to the same ModelConfig generation as the SDK client. The global
|
||||
model.auth_fail_closed policy is read live on every mint. A Stop that wins
|
||||
before or during mint prevents model bytes from being sent afterward.
|
||||
note bottom of SH
|
||||
**Console** owns admin endpoints
|
||||
**Server** validates JWT + config only
|
||||
Both share JWT signing secret
|
||||
end note
|
||||
|
||||
note bottom of ProviderCall
|
||||
If minting fails, a configured fail-closed deployment or a keyless alias
|
||||
raises BackendAuthUnavailableError. A dynamic alias with an explicit static
|
||||
key may fall back only when policy allows. Authentication refusal is not a
|
||||
backend-health failure and does not walk to a static fallback model.
|
||||
note left of JWT
|
||||
**Console Proxy Token Minting**
|
||||
When proxying requests to server nodes:
|
||||
1. Console AuthMiddleware validates user JWT (aud: turnstone-console)
|
||||
2. Proxy mints new JWT (aud: turnstone-server)
|
||||
with real user_id, scopes, permissions
|
||||
3. src: "console-proxy" for audit traceability
|
||||
4. 5-minute expiry (fresh per request)
|
||||
5. Fallback: ServiceTokenManager if no user context
|
||||
end note
|
||||
|
||||
@enduml
|
||||
|
||||
@@ -82,12 +82,10 @@ class "DiscordBot" as Bot <<service>> {
|
||||
}
|
||||
|
||||
class "ChannelRouter" as Router <<service>> {
|
||||
+get_or_create_workstream(channel_type, channel_id)
|
||||
+_is_ws_live(ws_id)
|
||||
+send_message(ws_id, message)
|
||||
+send_approval(ws_id, ...)
|
||||
+lookup_ws_id(channel_type, channel_id)
|
||||
+resolve_user(channel_type, channel_user_id)
|
||||
+resolve_route(platform, channel_id)
|
||||
-> ws_id | None
|
||||
+register_route(channel_id, ws_id)
|
||||
+resolve_identity(platform, platform_user_id)
|
||||
-> user_id | None
|
||||
--
|
||||
Maps channels -> workstreams
|
||||
@@ -95,16 +93,6 @@ class "ChannelRouter" as Router <<service>> {
|
||||
Caches routes in memory
|
||||
}
|
||||
|
||||
class "turnstone-console router" as ConsoleRouter <<server>> {
|
||||
POST /v1/api/route/workstreams/new
|
||||
GET /v1/api/route/workstreams/{ws_id}/live
|
||||
POST /v1/api/route/workstreams/{ws_id}/send
|
||||
POST /v1/api/route/workstreams/{ws_id}/approve
|
||||
GET /v1/api/route?ws_id=...
|
||||
--
|
||||
Multi-node rendezvous + durable overrides
|
||||
}
|
||||
|
||||
' -- Server --
|
||||
class "turnstone-server" as Server <<server>> {
|
||||
POST /v1/api/workstreams/{ws_id}/send
|
||||
@@ -160,9 +148,7 @@ Bot --> Router : on_message\non_interaction
|
||||
Router --> CU : resolve identity
|
||||
Router --> CR : resolve / register route
|
||||
|
||||
Router --> Server : single-node/direct mode\ncreate + send + approve
|
||||
Router --> ConsoleRouter : multi-node mode\nroute create/live/send/approve/lookup
|
||||
ConsoleRouter --> Server : routed HTTP to owning node
|
||||
Router --> Server : POST /v1/api/workstreams/{ws_id}/send\nPOST /v1/api/workstreams/{ws_id}/approve\nPOST /v1/api/workstreams/new
|
||||
Bot --> Server : GET /v1/api/workstreams/{ws_id}/events\n(SSE via httpx-sse)
|
||||
Server --> Bot : SSE event stream
|
||||
|
||||
@@ -170,7 +156,7 @@ Bot --> Discord : reply / embed\nbutton callback
|
||||
|
||||
Slack --> SlackBot : socket-mode\nevents
|
||||
SlackBot --> Router : on_message / on_action
|
||||
SlackBot --> Server : owning-node SSE after route lookup
|
||||
SlackBot --> Server : POST /v1/api/workstreams/{ws_id}/send\nGET /v1/api/workstreams/{ws_id}/events
|
||||
SlackBot --> Slack : post / update\nBlock Kit button callbacks
|
||||
|
||||
Teams .[hidden]. Slack
|
||||
@@ -189,21 +175,19 @@ note right of Bot
|
||||
**Inbound Flow**
|
||||
1. Discord message arrives via gateway
|
||||
2. Bot.on_message() fires
|
||||
3. ChannelRouter gets or creates channel -> ws_id
|
||||
(direct server or multi-node console router)
|
||||
3. ChannelRouter resolves channel -> ws_id
|
||||
(or creates new workstream)
|
||||
4. ChannelRouter resolves platform user -> user_id
|
||||
via channel_users table
|
||||
5. Router sends through the configured server/console SDK
|
||||
5. Router sends POST /v1/api/workstreams/{ws_id}/send to server
|
||||
|
||||
**Stale-route recovery (evicted workstreams)**
|
||||
1. Route health check reports the old ws unavailable
|
||||
2. Existing ws_id becomes the fork source
|
||||
**Workstream Resume (evicted workstreams)**
|
||||
1. Stale route detected (no active SSE listener)
|
||||
2. Existing ws_id reused directly from route
|
||||
3. POST /v1/api/workstreams/new with
|
||||
resume_ws=<ws_id>
|
||||
4. Server atomically clones source history/config/
|
||||
persona/project/attachment refs into a new ws_id
|
||||
5. Router stores the new destination route; source is unchanged
|
||||
6. If the source was pruned, retry one fresh create
|
||||
4. Server resumes atomically during creation
|
||||
5. SSE emits WorkstreamResumedEvent -> thread
|
||||
end note
|
||||
|
||||
note right of Server
|
||||
|
||||
@@ -11,7 +11,7 @@ skinparam participant {
|
||||
|
||||
participant "ChatSession\n(session.py)" as Session <<session>>
|
||||
participant "WatchRunner\n(watch.py)" as Runner <<server>>
|
||||
participant "StorageBackend\n(SQLite / PostgreSQL)" as Storage <<storage>>
|
||||
participant "StorageBackend\n(SQLite)" as Storage <<storage>>
|
||||
participant "WebUI / SSE\n(server.py)" as UI <<ui>>
|
||||
|
||||
== Create Phase ==
|
||||
@@ -130,7 +130,7 @@ note right : action="cancel" (auto-approve)
|
||||
note over Runner, Storage
|
||||
**Startup:**
|
||||
1. WatchRunner created in main() with storage + node_id
|
||||
2. restore_fn closure captures SessionManager
|
||||
2. restore_fn closure captures WorkstreamManager
|
||||
3. Initial workstream: session.set_watch_runner(runner)
|
||||
4. _lifespan(): runner.start() — daemon thread begins
|
||||
|
||||
|
||||
@@ -1,126 +1,218 @@
|
||||
@startuml
|
||||
!theme plain
|
||||
title Turnstone — Intent Judge, Concurrent Approval Cycles, and Output Guard
|
||||
title Turnstone — Intent Validation (Judge) Architecture
|
||||
|
||||
skinparam sequenceArrowThickness 1.5
|
||||
skinparam sequenceLifeLineBackgroundColor #F5F5F5
|
||||
skinparam participant {
|
||||
BackgroundColor<<session>> #C8E6C9
|
||||
BackgroundColor<<judge>> #FFE0B2
|
||||
BackgroundColor<<storage>> #B3E5FC
|
||||
BackgroundColor<<ui>> #E8EAF6
|
||||
BackgroundColor<<fs>> #F5F5F5
|
||||
}
|
||||
|
||||
participant "ChatSession\ngeneration N" as Session
|
||||
participant "SessionUIBase" as UI
|
||||
participant "IntentJudge" as Judge
|
||||
participant "model_turn()\n(pinned ModelLane)" as Model
|
||||
participant "Operator / client" as Operator
|
||||
participant "OutputGuardJudge" as Guard
|
||||
database "StorageBackend" as Storage
|
||||
participant "ChatSession\n(session.py)" as Session <<session>>
|
||||
participant "IntentJudge\n(judge.py)" as Judge <<judge>>
|
||||
participant "LLM Provider\n(provider)" as LLM <<judge>>
|
||||
participant "StorageBackend\n(SQLite)" as Storage <<storage>>
|
||||
participant "WebUI / SSE\n(server.py)" as UI <<ui>>
|
||||
participant "Filesystem" as FS <<fs>>
|
||||
|
||||
== Intent assessment begins during preparation ==
|
||||
== Tool Call Requires Approval ==
|
||||
|
||||
Session -> Session : prepare each tool item independently\nattach principal + cancel witness
|
||||
Session -> Judge : evaluate(items, callback, cancel_ref)
|
||||
activate Judge
|
||||
Judge -> Judge : synchronous heuristic verdict\nfor each call (first matching rule)
|
||||
Judge --> Session : heuristic verdicts + daemon cancel event
|
||||
Session -> UI : cache / publish heuristic assessments
|
||||
Session -> Storage : persist heuristic intent verdicts
|
||||
|
||||
note over Judge, Model
|
||||
The judge owns an immutable resolved binding. Registry/config generations
|
||||
are freshness watermarks: an effective lane change replaces the judge for
|
||||
the next batch, while in-flight work keeps the lane it started with.
|
||||
Dynamic backend auth is resolved for this batch's initiating principal.
|
||||
parallel_evaluations (1-16) sets per-batch worker width; the model alias's
|
||||
admission gate remains the process-wide generation ceiling.
|
||||
Session -> Session : _prepare_tool_calls()
|
||||
note right
|
||||
Tool calls parsed from
|
||||
LLM response. Auto-approved
|
||||
tools dispatched immediately.
|
||||
Remaining items need approval.
|
||||
end note
|
||||
|
||||
par LLM judge daemon coordinator
|
||||
Judge -> Judge : start min(batch size, parallel_evaluations,\npositive alias capacity) workers
|
||||
loop each worker claims one independent call
|
||||
Judge -> Model : model_turn(judge lane, canonical Turns,\nread-only evidence tools, cancel_ref)
|
||||
Model --> Judge : ModelTurnResult
|
||||
alt evidence tool requested
|
||||
Judge -> Judge : execute bounded read_file / list_directory
|
||||
else verdict text
|
||||
Judge -> Judge : parse + arbitrate against heuristic
|
||||
Session -> Session : _evaluate_intent(pending_items)
|
||||
|
||||
== Tier 1: Heuristic (synchronous, sub-ms) ==
|
||||
|
||||
Session -> Judge : evaluate(items, messages, callback)
|
||||
|
||||
Judge -> Judge : evaluate_heuristic()\nfor each item
|
||||
note right
|
||||
**36 rules (first match wins):**
|
||||
Critical (0.90, deny): rm /, mkfs,
|
||||
dd, pipe-to-shell, chmod 777 /,
|
||||
write/edit /etc/ .ssh/,
|
||||
download-then-execute chains
|
||||
High (0.80, review): sudo, kill -9,
|
||||
destructive git, DROP TABLE,
|
||||
secrets, HTTP mutations, ssh/scp,
|
||||
browser+data-export, transitive
|
||||
install, control-plane mutation
|
||||
Medium (0.70, review): content
|
||||
ingestion, interpreter exec,
|
||||
cloud CLI mutations, pkg install,
|
||||
write_file, MCP tools, docker ops
|
||||
Low (0.85, approve): read_file,
|
||||
list_directory, search, recall,
|
||||
tool_search, read_resource,
|
||||
web_search, read-only bash
|
||||
Default: medium, 0.50, review
|
||||
end note
|
||||
|
||||
Judge --> Session : heuristic_verdicts[]
|
||||
|
||||
Session -> Session : attach _heuristic_verdict\nto each pending item
|
||||
|
||||
Session -> UI : SSE: approve_request\n{items: [{verdict: ...}],\n judge_pending: true}
|
||||
note right
|
||||
Heuristic verdict displayed
|
||||
immediately as risk badge.
|
||||
Spinner shown while LLM
|
||||
judge evaluates.
|
||||
end note
|
||||
|
||||
Session -> Storage : create_intent_verdict()\nfor each heuristic verdict
|
||||
|
||||
== Tier 2: LLM Judge (daemon thread, async) ==
|
||||
|
||||
Judge -> Judge : spawn daemon thread\n"intent-judge"
|
||||
|
||||
note over Judge, LLM
|
||||
**Context preparation:**
|
||||
1. FIFO-truncate conversation history
|
||||
to max_context_ratio of context window
|
||||
2. Append tool call details as user message
|
||||
3. System prompt defines judge role + JSON schema
|
||||
end note
|
||||
|
||||
loop up to 3 turns (timeout budget)
|
||||
|
||||
Judge -> LLM : create_completion(\nmodel, judge_messages,\ntools=[read_file, list_directory])
|
||||
LLM --> Judge : CompletionResult
|
||||
|
||||
alt tool_calls present (turn < 3)
|
||||
Judge -> Judge : _exec_read_only_tool()
|
||||
note right
|
||||
**Security hardening:**
|
||||
Blocked: /etc/, /root/,
|
||||
/proc/, /sys/, /dev/,
|
||||
.ssh, .gnupg, .aws,
|
||||
*.pem, *.key, *.p12
|
||||
File cap: 32KB
|
||||
Dir cap: 200 entries
|
||||
end note
|
||||
Judge -> FS : read_file / list_directory
|
||||
FS --> Judge : file contents
|
||||
Judge -> Judge : append tool result\nto judge_messages
|
||||
else text response (final verdict)
|
||||
Judge -> Judge : _parse_verdict()
|
||||
note right
|
||||
**4-stage JSON parsing:**
|
||||
1. Direct JSON.loads
|
||||
2. Markdown code block
|
||||
3. Brace-counting
|
||||
4. Regex field extraction
|
||||
end note
|
||||
end
|
||||
Judge --> UI : on_intent_verdict(verdict, judge generation)
|
||||
UI -> Storage : persist LLM verdict / audit update
|
||||
end
|
||||
else approval path continues
|
||||
Session -> UI : approve_tools(items) with one\nSmart Approval config snapshot
|
||||
|
||||
end
|
||||
|
||||
== Policy, Smart Approval, and human gate ==
|
||||
== Tier 3: Arbitration ==
|
||||
|
||||
UI -> UI : apply explicit policy / skill / always / blanket bypasses
|
||||
opt Smart Approvals enabled
|
||||
UI -> UI : wait within captured deadline for this batch's verdicts
|
||||
UI -> UI : auto-approve only recommendation=approve\nand confidence >= captured threshold
|
||||
UI -> Storage : persist auto-approval reason and decision
|
||||
end
|
||||
|
||||
alt human-gated items remain
|
||||
UI -> UI : acquire publication lease; register ApprovalCycle\n(cycle_id, call_ids, event, result, witnesses)
|
||||
UI -> Operator : approve_request with cycle_id + item verdicts
|
||||
Operator -> UI : approve / deny by cycle_id or call_id
|
||||
UI -> UI : atomically claim exactly one unresolved cycle
|
||||
UI -> Operator : approval_resolved
|
||||
UI --> Session : decision + optional feedback
|
||||
UI -> Storage : stamp tracked verdicts with operator decision
|
||||
else every item bypassed / auto-approved
|
||||
UI -> Operator : tool_info with exact auto_approve_reason
|
||||
UI --> Session : approved
|
||||
end
|
||||
|
||||
note right of UI
|
||||
Parallel task agents may register several ApprovalCycles. Each cycle owns
|
||||
its own Event and result slot. A legacy selector-less decision targets the
|
||||
oldest cycle; double resolution is a no-op. Cached LLM verdicts carry their
|
||||
judge generation, so reused provider call ids cannot satisfy a new cycle.
|
||||
Judge -> Judge : compare confidence:\nLLM vs heuristic
|
||||
note right
|
||||
Only deliver LLM verdict
|
||||
if confidence > heuristic.
|
||||
Otherwise heuristic stands.
|
||||
end note
|
||||
|
||||
== Cancellation boundary ==
|
||||
|
||||
opt Stop / close / force-successor
|
||||
Session -> Judge : abort all judge events owned by the cancelled operation
|
||||
Session -> UI : resolve_all_approvals(False, "cancelled")
|
||||
UI -> UI : block new admission leases; wait for admitted bundles;\nclaim only cycles whose cancellation witness is aborted
|
||||
UI -> Operator : one cancelled resolution per claimed cycle
|
||||
note over Session, UI
|
||||
A Stop can win before cycle registration, during publication, or while a
|
||||
click resolves. The witness + admission sweep makes exactly one terminal
|
||||
outcome visible; a successor generation's new cycle is not swept.
|
||||
end note
|
||||
alt LLM confidence > heuristic confidence
|
||||
Judge -> Session : callback(llm_verdict)
|
||||
Session -> UI : SSE: intent_verdict\n{tier: "llm", ...}
|
||||
note right
|
||||
UI replaces heuristic badge
|
||||
with LLM verdict. Spinner
|
||||
resolves to final assessment.
|
||||
end note
|
||||
Session -> Storage : create_intent_verdict()\nfor LLM verdict
|
||||
end
|
||||
|
||||
note over Judge
|
||||
Normal operator resolution does not necessarily cancel judge inference.
|
||||
With cancel_on_approval=false, the daemon finishes and late verdicts remain
|
||||
auditable. With it enabled, the batch event stops remaining judge work.
|
||||
== User Decision ==
|
||||
|
||||
UI -> Session : resolve_approval(\napproved, feedback)
|
||||
|
||||
Session -> Storage : update_intent_verdict(\nverdict_id, user_decision)
|
||||
note right
|
||||
All tracked verdicts
|
||||
(heuristic + LLM) updated
|
||||
with "approved" or "denied".
|
||||
Swap-and-clear avoids racing
|
||||
with daemon judge thread.
|
||||
end note
|
||||
|
||||
deactivate Judge
|
||||
== Tool Execution ==
|
||||
|
||||
== Tool output guard ==
|
||||
Session -> Session : _execute_tools()
|
||||
note right
|
||||
Tools execute with
|
||||
user approval.
|
||||
end note
|
||||
|
||||
Session -> Session : execute admitted tools; truncate each result
|
||||
Session -> Guard : evaluate(result, tool context, cancel event)
|
||||
activate Guard
|
||||
Guard -> Guard : heuristic checks first
|
||||
opt LLM guard enabled and time remains
|
||||
Guard -> Model : model_turn(output-guard lane, bounded prompt, cancel_ref)
|
||||
Model --> Guard : structured verdict
|
||||
== Output Guard (synchronous, time-budgeted) ==
|
||||
|
||||
Session -> Session : _evaluate_output()\nfor each tool result
|
||||
note right
|
||||
**Priority-ordered checks (5s budget):**
|
||||
P1: Prompt injection (role injection,
|
||||
override phrases, instruction tags)
|
||||
P2: Credential leakage (API keys,
|
||||
PEM blocks, connection strings)
|
||||
P3: Encoded payloads (data URIs,
|
||||
hex shellcode)
|
||||
P4: Adversarial URLs (cloud metadata,
|
||||
credential query params)
|
||||
P5: System info disclosure (private
|
||||
IPs, sensitive paths)
|
||||
|
||||
Annotates + optionally redacts.
|
||||
Does NOT gate.
|
||||
end note
|
||||
|
||||
alt output_warning flags detected
|
||||
Session -> UI : SSE: output_warning\n{call_id, risk_level, flags,\nfunc_name, redacted}
|
||||
note right
|
||||
Credential values replaced
|
||||
with [REDACTED:<type>] before
|
||||
output enters conversation.
|
||||
sanitized text excluded from
|
||||
SSE payload (defense in depth).
|
||||
end note
|
||||
UI -> Storage : record_output_assessment()\nfire-and-forget persistence
|
||||
note right
|
||||
Stored: flags, risk_level,
|
||||
annotations, output_length,
|
||||
redacted (bool). Raw tool
|
||||
output is never stored.
|
||||
end note
|
||||
end
|
||||
Guard --> Session : assessment / redaction / warning
|
||||
deactivate Guard
|
||||
Session -> Session : re-check generation N before folding result
|
||||
Session -> UI : output warning (no raw secret payload)
|
||||
Session -> Storage : persist assessment + guarded Tool Turn metadata
|
||||
|
||||
note over Guard, Storage
|
||||
Output-guard objects also pin model/config lanes. Replacement retires the
|
||||
old object but lets admitted evaluations drain before its private client is
|
||||
closed. A cancelled or superseded evaluation cannot fold into the successor
|
||||
trajectory. Raw pre-redaction secrets are never stored in assessment rows.
|
||||
== Lifecycle ==
|
||||
|
||||
note over Session, Judge
|
||||
**Lazy initialization:**
|
||||
IntentJudge created on first approval if judge_config.enabled.
|
||||
Re-uses session's provider/client by default (self-consistency).
|
||||
Cross-model: separate provider/client from [judge] config.
|
||||
|
||||
**Sub-agent exemption:**
|
||||
Task sub-agents skip intent validation entirely.
|
||||
|
||||
**Output guard:**
|
||||
Runs when judge_config.output_guard is true (default).
|
||||
Credential redaction when judge_config.redact_secrets is true.
|
||||
|
||||
**Storage:**
|
||||
intent_verdicts table (migration 012), output_assessments table
|
||||
(migration 022). Both queryable via admin API endpoints
|
||||
(requires admin.judge permission). Skills store risk_level,
|
||||
scan_report, scan_version for install-time risk assessment.
|
||||
end note
|
||||
|
||||
@enduml
|
||||
|
||||
@@ -13,68 +13,65 @@ skinparam participant {
|
||||
participant "ChatSession\n(session.py)" as Session <<session>>
|
||||
participant "MemoryFacade\n(memory.py)" as Facade <<facade>>
|
||||
participant "MemoryRelevance\n(memory_relevance.py)" as Relevance <<facade>>
|
||||
participant "StorageBackend\n(SQLite / PostgreSQL)" as Storage <<storage>>
|
||||
participant "StorageBackend\n(SQLite)" as Storage <<storage>>
|
||||
participant "Server API\n(server.py)" as API <<api>>
|
||||
participant "Console Admin\n(console/server.py)" as Admin <<api>>
|
||||
participant "SDK Client\n(sdk/)" as SDK <<sdk>>
|
||||
|
||||
== Phase 1: Tool Path (session.send) ==
|
||||
|
||||
Session -> Session : pin acting principal\nparse memory(action=...)
|
||||
Session -> Session : _prepare_tool_calls()\nparse memory(action=...)
|
||||
note right
|
||||
Tool schema: 5 actions
|
||||
save, get, search, delete, list
|
||||
Tool schema: 4 actions
|
||||
save, search, delete, list
|
||||
Auto-approved (no approval needed)
|
||||
end note
|
||||
|
||||
Session -> Session : resolve live project access\nselect exact/inherited scope
|
||||
|
||||
Session -> Session : _exec_memory(item)
|
||||
|
||||
alt action = save
|
||||
Session -> Session : require non-empty description
|
||||
Session -> Facade : save_structured_memory_strict(\n..., require_active_project)
|
||||
Session -> Facade : save_structured_memory(\nname, content, description,\nmem_type, scope, scope_id)
|
||||
Facade -> Facade : normalize_key(name)
|
||||
Facade -> Storage : guarded atomic upsert\nON CONFLICT ... RETURNING
|
||||
Storage --> Facade : (saved row, was_update)
|
||||
Facade --> Session : saved row
|
||||
Session -> Session : invalidate prefix/cache\naudit acting principal
|
||||
end
|
||||
|
||||
alt action = get
|
||||
Session -> Facade : get_structured_memory_by_name_strict()
|
||||
Facade -> Storage : exact scoped-name lookup
|
||||
Storage --> Session : full row / not found
|
||||
Facade -> Storage : create_structured_memory()
|
||||
alt unique constraint violation
|
||||
Storage --> Facade : IntegrityError
|
||||
Facade -> Storage : get_structured_memory_by_name()
|
||||
Storage --> Facade : existing row
|
||||
Facade -> Storage : update_structured_memory()
|
||||
end
|
||||
Storage --> Facade : memory_id
|
||||
Facade --> Session : (memory_id, old_content)
|
||||
Session -> Session : _init_system_messages()\nrefresh BM25 context
|
||||
end
|
||||
|
||||
alt action = search
|
||||
Session -> Storage : search exact scope or\nactor-visible scope union
|
||||
Session -> Facade : search_structured_memories(\nquery, mem_type, scope,\nscope_id, limit)
|
||||
Facade -> Storage : search_structured_memories()
|
||||
Storage --> Session : matched rows
|
||||
end
|
||||
|
||||
alt action = delete
|
||||
Session -> Facade : delete_structured_memory_returning_strict()
|
||||
Facade -> Storage : DELETE ... RETURNING
|
||||
Storage --> Session : deleted row / not found
|
||||
Session -> Session : invalidate + audit\nmark prefix dirty
|
||||
Session -> Facade : delete_structured_memory(\nname, scope, scope_id)
|
||||
Facade -> Storage : delete_structured_memory()
|
||||
Storage --> Session : bool (existed)
|
||||
Session -> Session : _init_system_messages()\nrefresh BM25 context
|
||||
end
|
||||
|
||||
== Phase 2: BM25 Relevance Injection ==
|
||||
|
||||
Session -> Session : _init_system_messages()\nevery conversation turn
|
||||
|
||||
Session -> Session : resolve acting principal\nand live project ACL
|
||||
Session -> Session : _list_visible_memories(\nlimit=fetch_limit)
|
||||
note right
|
||||
**Scope resolution:**
|
||||
Interactive: global + workstream
|
||||
+ acting user + readable project
|
||||
Coordinator: acting user's coordinator
|
||||
+ readable project
|
||||
1. global scope (always)
|
||||
2. workstream scope (ws_id)
|
||||
3. user scope (user_id, if auth)
|
||||
Combined and deduplicated.
|
||||
end note
|
||||
|
||||
Session -> Facade : list_visible_structured_memories()
|
||||
Facade -> Storage : one visibility-union query
|
||||
Session -> Facade : list_structured_memories()\nper scope
|
||||
Facade -> Storage : list_structured_memories()
|
||||
Storage --> Session : up to fetch_limit rows
|
||||
|
||||
Session -> Relevance : extract_recent_context(\nmessages, max_messages=3)
|
||||
@@ -106,31 +103,28 @@ Session -> Session : inject into\nsystem message
|
||||
|
||||
== Phase 3: Server API Path ==
|
||||
|
||||
SDK -> API : GET /v1/api/memories\n?type=general&limit=20
|
||||
API -> API : bind scope to caller\ndefault global + caller user
|
||||
API -> Storage : list visible rows
|
||||
SDK -> API : GET /v1/api/memories\n?type=project&limit=20
|
||||
API -> Facade : list_structured_memories()
|
||||
Facade -> Storage : list_structured_memories()
|
||||
Storage --> API : rows
|
||||
API --> SDK : {"memories": [...], "total": N}
|
||||
|
||||
SDK -> API : POST /v1/api/memories\n{name, content, description, ...}
|
||||
API -> API : validate type, scope,\nname/content/description
|
||||
API -> API : reject internal scopes\nowner-bind workstream scope
|
||||
API -> Facade : save_structured_memory_strict()
|
||||
Facade -> Storage : atomic upsert
|
||||
SDK -> API : POST /v1/api/memories\n{name, content, ...}
|
||||
API -> API : validate type, scope,\nname length, content length
|
||||
API -> Facade : save_structured_memory()
|
||||
Facade -> Storage : create / update
|
||||
Storage --> API : memory row
|
||||
API -> API : record_audit(actor)
|
||||
API --> SDK : 201 (created) / 200 (updated)
|
||||
|
||||
SDK -> API : POST /v1/api/memories/search\n{query, type, ...}
|
||||
API -> API : bind scope to caller
|
||||
API -> Storage : search visible rows
|
||||
API -> Facade : search_structured_memories()
|
||||
Facade -> Storage : search_structured_memories()
|
||||
Storage --> API : matched rows
|
||||
API --> SDK : {"memories": [...], "total": N}
|
||||
|
||||
SDK -> API : DELETE /v1/api/memories/{name}\n?scope=global
|
||||
API -> Facade : delete_structured_memory_returning_strict()
|
||||
Facade -> Storage : DELETE ... RETURNING
|
||||
API -> API : record_audit(actor)
|
||||
API -> Facade : delete_structured_memory()
|
||||
Facade -> Storage : delete row
|
||||
API --> SDK : {"status": "ok"}
|
||||
|
||||
== Phase 4: Console Admin Path ==
|
||||
@@ -147,7 +141,7 @@ Storage --> Admin : memory row
|
||||
Admin --> SDK : memory JSON
|
||||
|
||||
SDK -> Admin : DELETE /v1/api/admin/memories/{id}
|
||||
Admin -> Storage : delete_structured_memory_by_id_returning()
|
||||
Admin -> Storage : delete_structured_memory_by_id()
|
||||
Admin -> Admin : record_audit(\n"memory.delete")
|
||||
Admin --> SDK : {"status": "ok"}
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ skinparam participant {
|
||||
participant "Server\n(main)" as Server <<session>>
|
||||
participant "ConfigStore\n(config_store.py)" as Store <<config>>
|
||||
participant "SettingsRegistry\n(settings_registry.py)" as Registry <<config>>
|
||||
participant "StorageBackend\n(SQLite / PostgreSQL)" as Storage <<storage>>
|
||||
participant "StorageBackend\n(SQLite)" as Storage <<storage>>
|
||||
participant "Console Admin\n(console/server.py)" as Admin <<api>>
|
||||
participant "SDK Client\n(sdk/)" as SDK <<sdk>>
|
||||
participant "ChatSession\n(session.py)" as Session <<session>>
|
||||
@@ -57,10 +57,9 @@ else key not in cache
|
||||
Store --> Session : default value
|
||||
end
|
||||
note right of Session
|
||||
Most session settings are captured once
|
||||
at workstream creation. Documented live readers
|
||||
(including model.auth_fail_closed per mint)
|
||||
apply immediately.
|
||||
Settings are captured once
|
||||
at workstream creation.
|
||||
Not re-read on every turn.
|
||||
end note
|
||||
|
||||
== Phase 3: Admin API — List / Schema ==
|
||||
@@ -129,9 +128,8 @@ Store -> Storage : get_system_settings_bulk(node_id)
|
||||
Storage --> Store : all settings
|
||||
Store -> Store : rebuild cache,\nswap atomically,\nincrement _version
|
||||
note right
|
||||
Most existing-session settings are unchanged
|
||||
(frozen at creation time); documented
|
||||
live readers apply immediately.
|
||||
Existing sessions: unchanged
|
||||
(frozen at creation time).
|
||||
New sessions: pick up
|
||||
updated values immediately.
|
||||
end note
|
||||
|
||||
@@ -88,7 +88,7 @@
|
||||
<rect x="300" y="151" width="160" height="2" fill="#161b22"/>
|
||||
<text x="380" y="178" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Console</text>
|
||||
<line x1="318" y1="190" x2="442" y2="190" stroke="#30363d" stroke-width="1"/>
|
||||
<text x="380" y="208" text-anchor="middle" fill="#8b949e" font-size="9">FNV-1a rendezvous router</text>
|
||||
<text x="380" y="208" text-anchor="middle" fill="#8b949e" font-size="9">hash-ring router</text>
|
||||
<text x="380" y="223" text-anchor="middle" fill="#8b949e" font-size="9">cluster dashboard</text>
|
||||
<text x="380" y="238" text-anchor="middle" fill="#8b949e" font-size="9">reverse proxy</text>
|
||||
<line x1="318" y1="250" x2="442" y2="250" stroke="#30363d" stroke-width="1"/>
|
||||
@@ -115,7 +115,7 @@
|
||||
<rect x="608" y="162" width="184" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
|
||||
<text x="700" y="180" text-anchor="middle" fill="#8b949e" font-size="9">turnstone-server :8080</text>
|
||||
<!-- Tools label -->
|
||||
<text x="700" y="206" text-anchor="middle" fill="#484f58" font-size="8">model lanes + tools / MCP</text>
|
||||
<text x="700" y="206" text-anchor="middle" fill="#484f58" font-size="8">19 tools + MCP</text>
|
||||
</g>
|
||||
|
||||
<!-- Node B -->
|
||||
@@ -130,7 +130,7 @@
|
||||
<rect x="608" y="282" width="184" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
|
||||
<text x="700" y="300" text-anchor="middle" fill="#8b949e" font-size="9">turnstone-server :8080</text>
|
||||
<!-- Tools label -->
|
||||
<text x="700" y="326" text-anchor="middle" fill="#484f58" font-size="8">model lanes + tools / MCP</text>
|
||||
<text x="700" y="326" text-anchor="middle" fill="#484f58" font-size="8">19 tools + MCP</text>
|
||||
</g>
|
||||
|
||||
<!-- ==================== LLM PROVIDERS ==================== -->
|
||||
@@ -171,7 +171,7 @@
|
||||
<rect x="590" y="450" width="220" height="5" fill="#bc8cff"/>
|
||||
<rect x="590" y="453" width="220" height="2" fill="#161b22"/>
|
||||
<text x="700" y="476" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">PostgreSQL / SQLite</text>
|
||||
<text x="700" y="492" text-anchor="middle" fill="#8b949e" font-size="9">workstreams, turns, config, auth</text>
|
||||
<text x="700" y="492" text-anchor="middle" fill="#8b949e" font-size="9">conversations, memory, auth</text>
|
||||
</g>
|
||||
<text x="700" y="444" text-anchor="middle" fill="#bc8cff" font-size="9" font-weight="600" letter-spacing="2">STORAGE</text>
|
||||
|
||||
@@ -239,7 +239,7 @@
|
||||
<!-- Routing rules at bottom, left-aligned -->
|
||||
<text x="44" y="456" fill="#30363d" font-size="9" font-weight="600" letter-spacing="1">ROUTING</text>
|
||||
<circle cx="44" cy="474" r="3" fill="#3fb950" opacity="0.6"/>
|
||||
<text x="54" y="477" fill="#484f58" font-size="9">control plane: client → console → server node (FNV-1a rendezvous placement)</text>
|
||||
<text x="54" y="477" fill="#484f58" font-size="9">control plane: client → console → server node (hash-ring bucket lookup)</text>
|
||||
<circle cx="44" cy="494" r="3" fill="#58a6ff" opacity="0.6"/>
|
||||
<text x="54" y="497" fill="#484f58" font-size="9">data plane: client → server node (direct SSE, node_url from create response)</text>
|
||||
<circle cx="44" cy="514" r="3" fill="#f47067" opacity="0.6"/>
|
||||
|
||||
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 16 KiB |
@@ -1,3 +0,0 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:6e2bfdf968e96f3720ed58674103288e2f57e9c056f5c479a57f37a849f3e69c
|
||||
size 821878
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:b8c1460440784f07e30afea32d4ee17687627df46a24003d761ad79c2676a361
|
||||
size 169499
|
||||
oid sha256:881a8b9bce67b5af9a52d5e50deaa72351cd99c76f18aad5caeb2b61131ca1af
|
||||
size 119798
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:66847ccdf10ef2bd04e93bc0d3924a56ce28462ec9e76a383b53aee4500755e8
|
||||
size 631799
|
||||
oid sha256:95dd5ebc899a1261d516686a5aa3319a7f45015d411302825fa28afbfc82e1ce
|
||||
size 326766
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:c74e99c530c3a8af9ab35b1e4d8c4fef0ea35c0c04cc35da7cf3588e71382057
|
||||
size 661175
|
||||
oid sha256:9857db23fe3c4316d492073aac69c7e7558b1abe3b95ad7756d4a5933bd0ece7
|
||||
size 620214
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:6261604cc8b75878a8704308929ea64d121cf26547019543fbe1b21cbe700415
|
||||
size 189791
|
||||
oid sha256:d9c7769a600c38e6387390e6c42db8152e0f80c31d17b2218f7f636b71c7b868
|
||||
size 355459
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:1b3b7b745f6006ee73d4b31fa598faa0d71ffb74ce349ab08eb3ce09ded506c3
|
||||
size 266294
|
||||
oid sha256:23ca090b5656baaf70820cbe4ab6c27f0a3a02e18b4db0695614cf9489c23980
|
||||
size 281440
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:33dddd8cd8b53fa464cc8a4c899896fee32035d63e0669fe327969e3356349c7
|
||||
size 329815
|
||||
oid sha256:04d2069a9b5155ad1e7d842147fd78535ad9106d6856520439c33a9868a47499
|
||||
size 156694
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:16e3f3bfa0a6af637f7a9fb6765d594eb598428679c88a429c096c3dbae931e4
|
||||
size 181185
|
||||
oid sha256:a872556d111185f4531d1b68ee892b4ce5042d7ccf277e2cad08beb6932c9803
|
||||
size 191144
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:59f14b835665244f3d32981b6c1ac4c4380393a83cc519e271831622aa3f261a
|
||||
size 197433
|
||||
oid sha256:e7c3e40c10425d721f833390ae3531c09af501157fd3142531ba4eba86ff719d
|
||||
size 197112
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:1a510eeaabf4ed8dab3b268c8f6bb5b7fef629a664361f7fb5614a6b498db36e
|
||||
size 294415
|
||||
oid sha256:b047cdc318c505f0f0895a65e14c5cc7552716053055cca57fa0a77db150e618
|
||||
size 255458
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:ea86c6b6c68ed96f6fd18543d2e7a873f4715332cc3a7d4df167392f668a2de7
|
||||
size 232403
|
||||
oid sha256:af5ab3126bf685afe68e24bc4b0ed97371d0ebdb77bf4d76c0331ab120580cc0
|
||||
size 248809
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:edf02b97e1e1287ebba9e74b9858474dcda42e5542656e505ea133a5b2416f47
|
||||
size 402992
|
||||
oid sha256:ae4f79fb22600106f8cb0af4ba5586bb26ea5d57e27ef382fdc59b6549fdbd21
|
||||
size 415473
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:aa9ca9a367c79159a26d1ec544b20fc7118a49082d72f7ee0edbaa85608d49fc
|
||||
size 238991
|
||||
oid sha256:96176a09e65e90dadc32d5e9ed778423842be89204d2cf382225f53a90cfaf01
|
||||
size 258547
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:636a6b2fc1075e4863421e68b99efe7f6f6f62cedbcff36ef0934c055f39fd46
|
||||
size 281161
|
||||
oid sha256:79a690c466a5d6f6d4292d78a27b9474e9e9c1373fa80e17dfe37700238c8af8
|
||||
size 382508
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:137d6c91a34695c820d8b0a33fd753e79165604aa92bf2ac8480d3744b2ef844
|
||||
size 305199
|
||||
oid sha256:c89628ed917dfd576c1af75c68fe5fed9beadaaee9dcea7aa7a1643867c4f1b9
|
||||
size 344323
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:0455e0dec36ebb8bcfdadcf327a1dd24ddbdcdd8df211c08918180842497727e
|
||||
size 318681
|
||||
oid sha256:06fe076f0835a891e00afc804fd1805196ebde9fc0d34998c7873e87287f982b
|
||||
size 346887
|
||||
|
||||
+7
-63
@@ -102,26 +102,13 @@ the cluster runs mTLS; harmless otherwise), and `TURNSTONE_SEARXNG_URL` points
|
||||
are the dev-stack defaults — match whatever you set in `.env` if you changed them.
|
||||
|
||||
To let a server on a **different** machine join, start the stack with
|
||||
both `TURNSTONE_HOST_IP=<this host's LAN IP>` and
|
||||
`TURNSTONE_ACME_EXTERNAL_URL=http://<this host's LAN IP>:8090/acme`. The first
|
||||
binds PostgreSQL, the console ACME endpoint, and SearxNG to that interface; the
|
||||
second makes every URL in the ACME directory routable from the remote node (the
|
||||
full value must include the `/acme` mount). Set the same
|
||||
`TURNSTONE_ACME_EXTERNAL_URL` on the remote node so its authenticated ACME
|
||||
client can pin that credential destination. Set `TURNSTONE_CONSOLE_URL` and
|
||||
`TURNSTONE_SEARXNG_URL` to the compose host's IP, but set
|
||||
`TURNSTONE_ADVERTISE_URL=http://192.0.2.10:8080` to the **remote** box's own
|
||||
address. A resolvable DNS name works too. IPv6 literals must be bracketed in
|
||||
URLs, for example `http://[2001:db8::10]:8080`; Turnstone enrolls literal
|
||||
addresses as IP SANs rather than numeric DNS SANs.
|
||||
|
||||
Use a trusted LAN or VPN address and firewall `:8090` to enrolling nodes. ACME
|
||||
signing routes require a dedicated short-lived service JWT, but direct bootstrap
|
||||
is still plain HTTP/TOFU: a bearer token provides authentication, not transport
|
||||
confidentiality or protection from an active on-path attacker. **Set a strong
|
||||
`POSTGRES_PASSWORD` first** — `TURNSTONE_HOST_IP` also exposes the database (and
|
||||
every user account + API-token hash in it), the console API, and the
|
||||
unauthenticated SearxNG to your network.
|
||||
`TURNSTONE_HOST_IP=<this host's LAN IP>` — that binds PostgreSQL, the console
|
||||
ACME endpoint, and SearxNG to that interface. Then on the remote box set the
|
||||
three URLs above to that IP, and set `TURNSTONE_ADVERTISE_URL` to the **remote**
|
||||
box's own IP (the address the console dials back). **Set a strong
|
||||
`POSTGRES_PASSWORD` first** — `TURNSTONE_HOST_IP` exposes the database (and every
|
||||
user account + API-token hash in it), the console API, and the unauthenticated
|
||||
SearxNG to your network.
|
||||
|
||||
To run the bare-metal node as a hardened, persistent service instead of by hand,
|
||||
use the systemd units in [`deploy/systemd/`](../deploy/systemd/).
|
||||
@@ -161,11 +148,6 @@ certs via the console's ACME endpoint:
|
||||
docker compose -f turnstone/deploy/compose.yaml -f deploy/docker-compose.tls.yml up
|
||||
```
|
||||
|
||||
The overlay publishes the console's plain-HTTP bootstrap/API port on
|
||||
`TURNSTONE_CONSOLE_HTTP_BIND` (default `127.0.0.1`). For a cross-host node, set
|
||||
that to a trusted LAN/VPN address, set `TURNSTONE_ACME_EXTERNAL_URL` to the same
|
||||
address plus `/acme`, and firewall the port to enrolling nodes.
|
||||
|
||||
See [tls.md](tls.md) for details.
|
||||
|
||||
## Configuration
|
||||
@@ -204,12 +186,6 @@ overrides.
|
||||
> put [PgBouncer](pgbouncer.md) (transaction pooling) between turnstone and
|
||||
> PostgreSQL.
|
||||
|
||||
> **Lifecycle upgrade:** the release that introduces hidden deferred-create
|
||||
> reservations must be deployed as a coordinated cohort across every server
|
||||
> sharing PostgreSQL; older processes do not understand `state='creating'`.
|
||||
> Drain create traffic until the cohort is upgraded. See
|
||||
> [PgBouncer: deferred workstream creation](pgbouncer.md#upgrade-note-deferred-workstream-creation).
|
||||
|
||||
### Ports
|
||||
|
||||
Both stacks publish Caddy (dashboard) and PostgreSQL; the dev stack additionally
|
||||
@@ -224,8 +200,6 @@ Caddy or proxied by the console:
|
||||
| `POSTGRES_PORT` | `5432` | Host port for PostgreSQL (for bare-metal joins) |
|
||||
| `SEARXNG_API_PORT` | `8081` | Host port for the SearxNG API a bare-metal node's `web_search` dials (dev stack) |
|
||||
| `TURNSTONE_HOST_IP` | `127.0.0.1` | Interface PostgreSQL, the console ACME endpoint, and SearxNG bind on (dev stack). Set to this host's LAN IP so a bare-metal node on **another machine** can reach them — set a strong `POSTGRES_PASSWORD` first (it also exposes the DB and the unauthenticated SearxNG to your network). |
|
||||
| `TURNSTONE_CONSOLE_HTTP_BIND` | `127.0.0.1` | Production TLS-overlay interface for the console's plain-HTTP bootstrap/API listener. Use only a trusted LAN/VPN address and firewall it to enrolling nodes. |
|
||||
| `TURNSTONE_ACME_EXTERNAL_URL` | request-derived | Canonical externally reachable ACME responder base, including the final `/acme` mount (for example `http://192.0.2.1:8090/acme`). Set it on the console and clients for cross-host mTLS: the console advertises it, while clients pin it as an allowed enrollment-JWT destination. A reverse-proxy prefix is supported only when the proxy maps it to Turnstone's internal `/acme` mount. |
|
||||
| `POSTGRES_BIND` | `127.0.0.1` | Production stack (`turnstone/deploy/compose.yaml`) only: interface PostgreSQL binds on; set to the host's LAN IP for remote joins. |
|
||||
|
||||
### Channel gateway
|
||||
@@ -278,7 +252,6 @@ interface, or anyone who can reach it can search through your instance.
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `WORKSPACE_MOUNT` | empty volume | Host directory bind-mounted at `/workspace` for the model to read/write |
|
||||
| `TURNSTONE_WORKSPACE` | `/workspace` (image env) | Directory named as the user's workspace in the model's tool descriptions; informational only — see [Working directory](#working-directory) |
|
||||
| `SKIP_PERMISSIONS` | — | Set to any value to auto-approve all tool calls (dev only) |
|
||||
| `MCP_CONFIG` | — | Path to an MCP server config file |
|
||||
| `TURNSTONE_IMAGE_TAG` | `latest` | ghcr.io image tag — production stack |
|
||||
@@ -303,35 +276,6 @@ docker compose build --no-cache # rebuild from scratch
|
||||
| `workspace` | `/workspace` (unless `WORKSPACE_MOUNT` is set) |
|
||||
| `caddy-data` / `caddy-config` | Caddy's local CA and config (dev stack) |
|
||||
|
||||
## Working directory
|
||||
|
||||
Node processes run with `/data` as their working directory (the image's
|
||||
`WORKDIR`), and that is where the model's shell commands execute and
|
||||
relative file paths resolve — **not** `/workspace`. The shell and file
|
||||
tool descriptions state both paths (the working directory, and the
|
||||
workspace named by `TURNSTONE_WORKSPACE`), so the model knows to look in
|
||||
`/workspace` for your files without being told each session.
|
||||
|
||||
To make tools start inside the mount instead, override the working
|
||||
directory on the node services:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
turnstone-node:
|
||||
working_dir: /workspace
|
||||
```
|
||||
|
||||
Two caveats before overriding:
|
||||
|
||||
- **SQLite fallback**: when a node runs without PostgreSQL, its fallback
|
||||
database `.turnstone.db` is created in the process working directory.
|
||||
Changing `working_dir` on an existing SQLite-fallback deployment makes
|
||||
the node create a fresh database inside the mount and your prior state
|
||||
appears lost (it is still in the `turnstone-data` volume under `/data`).
|
||||
The stock compose stacks use PostgreSQL and are unaffected.
|
||||
- Migrations (`entrypoint.sh`) run in the same working directory, so the
|
||||
same SQLite caveat applies to them.
|
||||
|
||||
## Cleanup
|
||||
|
||||
```bash
|
||||
|
||||
+8
-11
@@ -177,8 +177,7 @@ Runs a complete multi-turn conversation:
|
||||
|
||||
1. Appends the user message.
|
||||
2. Checks `_cancelled` event — stops if set (timeout cleanup).
|
||||
3. Calls the model through the production streaming provider path and drains
|
||||
the result.
|
||||
3. Calls the model API (non-streaming).
|
||||
4. If tool calls are returned, executes them (with stdout suppressed) and
|
||||
logs each call to `self.tool_call_log`.
|
||||
5. Repeats up to `max_turns` or until the model responds without tool calls.
|
||||
@@ -191,15 +190,14 @@ Parallel tool calls are capped at 10 per turn to prevent degenerate repetition.
|
||||
|
||||
Each test runs in a `ThreadPoolExecutor(max_workers=1)` with a per-test
|
||||
timeout (`--test-timeout`). Each attempt gets its own `OpenAI` client with
|
||||
a matching per-read HTTP transport timeout. Because a trickling stream can
|
||||
continually reset that read timeout, three layers bound the harness and stop
|
||||
follow-on work:
|
||||
a matching httpx read timeout. On timeout, three layers of defense prevent
|
||||
zombie connections:
|
||||
|
||||
1. **Executor wall clock**: The harness stops waiting after `--test-timeout`.
|
||||
1. **httpx timeout**: Per-request read timeout aborts the HTTP call and
|
||||
releases the server slot.
|
||||
2. **`_cancelled` event**: Prevents the orphan thread from starting new turns.
|
||||
3. **`run_client.close()`**: Retires the connection pool and prevents reuse.
|
||||
HTTPX2 does not promise that cross-thread client closure immediately aborts
|
||||
an active body read; that read unwinds on its next wire event or read timeout.
|
||||
3. **`run_client.close()`**: Closes the connection pool to abort any
|
||||
in-flight request.
|
||||
|
||||
### Retry Logic
|
||||
|
||||
@@ -216,8 +214,7 @@ Each test case runs in isolation:
|
||||
1. A fresh temp directory is created.
|
||||
2. Setup files are written to the temp directory.
|
||||
3. The working directory is changed to the temp directory.
|
||||
4. A per-attempt `OpenAI` client is created with an HTTP transport timeout
|
||||
matching `--test-timeout`.
|
||||
4. A per-attempt `OpenAI` client is created with httpx timeout matching `--test-timeout`.
|
||||
5. A new `HeadlessSession` is created with the current developer prompt.
|
||||
6. `send_headless()` runs the user prompt through the conversation loop.
|
||||
7. The tool log is scored against expected actions.
|
||||
|
||||
+8
-14
@@ -16,18 +16,15 @@ The permission model has two layers:
|
||||
2. **Permissions** (granular) — named permission strings checked per-endpoint by
|
||||
`require_permission()`.
|
||||
|
||||
**Built-in roles** (seeded by migration 008 and extended by later feature
|
||||
migrations):
|
||||
**Built-in roles** (seeded by migration 008):
|
||||
|
||||
| Role | Permissions |
|
||||
|------|-------------|
|
||||
| admin | Admin-default baseline: ordinary admin, lifecycle, tool-approval, coordinator, project, and persona capabilities. Explicit opt-in capabilities such as `model.skills.write` remain ungranted. |
|
||||
| operator | read, write, workstreams.create, workstreams.close, conversation.modify |
|
||||
| admin | read, write, approve, admin.users, admin.roles, admin.orgs, admin.policies, admin.skills, admin.audit, admin.usage, admin.schedules, admin.watches, tools.approve, workstreams.create, workstreams.close |
|
||||
| operator | read, write, workstreams.create, workstreams.close |
|
||||
| viewer | read |
|
||||
|
||||
Custom roles can be created with any subset of the valid permissions. Built-in
|
||||
role permission overrides can grant or revoke individual capabilities, so the
|
||||
admin console is authoritative for the effective set on a deployment.
|
||||
Custom roles can be created with any subset of the valid permissions.
|
||||
The `persona.create` / `persona.read` / `persona.write` family gates
|
||||
persona administration; migration `063` seeds all three onto
|
||||
`builtin-admin`, and any role can be granted them through the standard
|
||||
@@ -70,7 +67,7 @@ etc.) since workstream templates were merged into the skills system in v0.8.0.
|
||||
workstreams, concatenated in alphabetical order by name. Use name prefixes
|
||||
(e.g. `01-safety`, `02-style`) to control ordering.
|
||||
- **Explicit selection**: `--skill <name>` CLI flag, `skill` field on
|
||||
`POST /v1/api/workstreams/new`, console launcher dropdown, scheduled task
|
||||
`POST /v1/api/workstreams/new`, console creation modal dropdown, scheduled task
|
||||
config, and channel adapter config. An explicit skill *replaces* defaults.
|
||||
- **Variables**: Three built-in placeholders resolved at load time:
|
||||
`{{model}}` (active model name), `{{ws_id}}` (workstream ID),
|
||||
@@ -134,12 +131,9 @@ Per-LLM-request token and tool call metrics:
|
||||
LLM response with prompt/completion tokens, cache tokens, tool call count,
|
||||
model, ws_id
|
||||
- **Prompt caching**: Anthropic automatic caching (`cache_control: ephemeral`)
|
||||
and OpenAI caching are enabled by default. Pre-5.6 GPT-5 models request
|
||||
`prompt_cache_retention: 24h`; GPT-5.6 uses
|
||||
`prompt_cache_options: {"ttl": "30m"}`. GPT-5.6 cache writes use the
|
||||
provider's 1.25× input-token rate. `cache_creation_tokens` and
|
||||
`cache_read_tokens` are tracked per request in `usage_events` and surfaced
|
||||
in the Usage admin tab
|
||||
and OpenAI extended retention (`prompt_cache_retention: 24h` for GPT-5.x)
|
||||
are enabled by default. `cache_creation_tokens` and `cache_read_tokens` are
|
||||
tracked per request in `usage_events` and surfaced in the Usage admin tab
|
||||
- **Querying**: `GET /v1/api/admin/usage` with `group_by` (day/hour/model/user)
|
||||
and time range filtering — includes cache token aggregates
|
||||
- **Prometheus**: `turnstone_tokens_total{type="cache_creation|cache_read"}`
|
||||
|
||||
+66
-111
@@ -17,9 +17,7 @@ evaluation:
|
||||
read-only tool access. Runs on a daemon thread and delivers its verdict
|
||||
progressively.
|
||||
|
||||
The verdict is advisory by default. The opt-in Smart Approvals mode can use a
|
||||
completed, high-confidence LLM `approve` verdict to make the decision
|
||||
automatically under the fail-closed rules below.
|
||||
The verdict is purely advisory -- the user always makes the final decision.
|
||||
|
||||
The heuristic verdict is attached to the `approve_request` SSE event immediately.
|
||||
The LLM verdict arrives later via an `intent_verdict` SSE event, allowing the
|
||||
@@ -30,77 +28,55 @@ persisted to the `intent_verdicts` table for audit and future calibration.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Server and console
|
||||
### config.toml
|
||||
|
||||
Server and console workstreams read database-backed `judge.*` settings from
|
||||
the settings registry. Edit them at **Admin → Judge** or through the admin
|
||||
settings API; changes take effect for the next judge batch without a restart.
|
||||
The principal settings are:
|
||||
|
||||
```text
|
||||
judge.enabled = true
|
||||
judge.model = "" # empty = same alias as the session
|
||||
judge.smart_approvals = false # opt-in automatic approval
|
||||
judge.confidence_threshold = 0.95 # Smart Approvals confidence bar
|
||||
judge.max_context_ratio = 0.5 # fraction of judge context used for history
|
||||
judge.timeout = 120.0 # per judge turn and Smart Approvals wait
|
||||
judge.parallel_evaluations = 1 # concurrent calls within one batch, 1-16
|
||||
judge.read_only_tools = true # permit read_file/list_directory evidence
|
||||
judge.cancel_on_approval = false # stop unfinished calls when the gate resolves
|
||||
```toml
|
||||
[judge]
|
||||
enabled = true
|
||||
model = "" # empty = same as session model
|
||||
provider = "" # empty = same as session provider
|
||||
base_url = ""
|
||||
api_key = ""
|
||||
smart_approvals = false # auto-approve high-confidence "approve" LLM verdicts (opt-in)
|
||||
confidence_threshold = 0.95 # Smart Approvals auto-approve bar (LLM recommendation=approve)
|
||||
max_context_ratio = 0.5 # max % of judge context window for history
|
||||
timeout = 120.0 # seconds (generous for local models)
|
||||
read_only_tools = true # judge can use read_file/list_directory
|
||||
cancel_on_approval = false # stop judging remaining tool calls once user decides
|
||||
```
|
||||
|
||||
`parallel_evaluations = 1` preserves serial evaluation. Raising it reduces the
|
||||
latency of wide tool-call batches. The selected judge model alias's
|
||||
`max_concurrency` remains the process-wide generation ceiling, so it can reduce
|
||||
the actual overlap across judge batches and other roles using that alias.
|
||||
|
||||
### Smart Approvals
|
||||
|
||||
With `smart_approvals = true` (off by default), a pending batch is approved
|
||||
automatically — no operator prompt — only when **every** call has a completed
|
||||
LLM verdict recommending `approve` at or above `confidence_threshold`. The
|
||||
decision is batch-atomic: one uncertain sibling sends the entire parallel batch
|
||||
to a human rather than executing the safe-looking subset piecemeal.
|
||||
With `smart_approvals = true` (off by default) a tool call is approved
|
||||
automatically — no operator prompt — when the intent judge's **LLM** verdict
|
||||
recommends `approve` with confidence at or above `confidence_threshold`. Every
|
||||
other outcome still reaches a human: `review` / `deny` recommendations,
|
||||
confidence below the threshold, judge errors or timeouts (`llm_fallback`), and
|
||||
any call the deterministic heuristic rules explicitly flagged `deny` or
|
||||
`critical`. That heuristic floor blocks only those explicit danger verdicts — it
|
||||
is **not** a general "never lower the heuristic" rule: the heuristic's default
|
||||
for an unmatched tool is `review`, and letting a confident LLM `approve` upgrade
|
||||
a `review` is exactly what Smart Approvals is for. Only `deny` / `critical`
|
||||
findings are off-limits to auto-approval. Requires the judge to be enabled;
|
||||
auto-approved calls are tagged `smart_approval` in the dashboard and audit trail.
|
||||
Smart Approvals applies to the web and coordinator surfaces, not the interactive
|
||||
CLI.
|
||||
|
||||
Every other outcome reaches a human: `review` / `deny` recommendations,
|
||||
confidence below the threshold, judge errors or timeouts (`llm_fallback`), a
|
||||
missing/duplicate call ID, an unjudged sibling, and any call the deterministic
|
||||
heuristic rules explicitly flagged `deny` or `critical`. That heuristic floor
|
||||
blocks only explicit danger verdicts — it is **not** a general "never lower the
|
||||
heuristic" rule. The heuristic's default for an unmatched tool is `review`, and
|
||||
letting a confident LLM upgrade that default is the feature's purpose.
|
||||
|
||||
The Smart Approvals enabled flag, threshold, and bounded verdict wait are
|
||||
captured as one immutable snapshot when each gate batch starts. A settings
|
||||
reload takes effect on the next batch, while concurrent main-loop and
|
||||
task-agent gates cannot mix fields from different reload generations. Stop
|
||||
wakes a batch still waiting for verdicts and is linearized against the final
|
||||
auto-approval commit: if Stop wins, no `smart_approval` decision or audit row
|
||||
is recorded for tools that did not cross the gate.
|
||||
|
||||
The verdict wait is capped by the snapshot's `judge.timeout`; the judge may
|
||||
continue evaluating advisory verdicts after that gate falls back to a human.
|
||||
|
||||
Requires the judge to be enabled. Auto-approved calls are tagged
|
||||
`smart_approval` in the dashboard and audit trail. Smart Approvals applies to
|
||||
the web and coordinator surfaces, not the interactive CLI.
|
||||
|
||||
The judge is enabled by default. Disable `judge.enabled` in the admin Judge
|
||||
settings, or use `--no-judge` in the interactive CLI.
|
||||
All fields are optional. The judge is enabled by default; use `enabled = false`
|
||||
(or `--no-judge` on the command line) to disable it.
|
||||
|
||||
### CLI flags
|
||||
|
||||
```
|
||||
--judge / --no-judge Enable/disable (default: enabled)
|
||||
--judge-model ALIAS Registered model alias for judge
|
||||
--judge-model MODEL Model for judge
|
||||
--judge-provider PROVIDER Provider for judge
|
||||
--judge-timeout SECONDS LLM judge timeout (default: 120)
|
||||
--judge-parallel-evaluations N Concurrent evaluations per batch, 1-16 (default: 1)
|
||||
--judge-confidence FLOAT Confidence threshold, 0-1 (default: 0.95)
|
||||
```
|
||||
|
||||
The same five values can be placed in the CLI's `config.toml` `[judge]`
|
||||
section. Smart Approvals is configured through the server/console admin Judge
|
||||
settings, not a CLI flag—the interactive CLI prompts for approval directly.
|
||||
(Smart Approvals is configured via `[judge] smart_approvals` / the admin Judge
|
||||
settings, not a CLI flag — the interactive CLI prompts for approval directly.)
|
||||
|
||||
CLI flags override `config.toml` values.
|
||||
|
||||
@@ -111,19 +87,20 @@ CLI flags override `config.toml` values.
|
||||
- **Default (self-consistency)**: When `model` is empty, the session model
|
||||
evaluates its own tool calls. Research shows self-consistency achieves
|
||||
comparable accuracy to multi-agent debate at a fraction of the cost.
|
||||
- **Cross-model**: Register the desired model in the Models tab, then set
|
||||
`judge.model` to that alias (or pass `--judge-model ALIAS` to the CLI).
|
||||
- **Cross-provider**: A model alias carries its provider, endpoint, and
|
||||
credential configuration together, so a judge alias may use a different
|
||||
provider from the session without separate judge connection settings.
|
||||
- **Google models**: The judge supports `google` aliases, including read-only
|
||||
evidence tools. Provider-native reasoning state such as Gemini
|
||||
`thought_signature` stays attached to the pinned model lane across evidence
|
||||
turns.
|
||||
- **Cross-model**: Use a different model for the judge (e.g. local model for
|
||||
the session, commercial model for the judge). Set `model` and `provider`
|
||||
in the `[judge]` config section, or use `--judge-model` / `--judge-provider`
|
||||
CLI flags.
|
||||
- **Cross-provider**: When both `model` and `provider` are set, the judge
|
||||
creates its own LLM client. You can optionally specify `base_url` and
|
||||
`api_key` for non-default endpoints.
|
||||
- **Google models**: The judge supports `google` as a provider. Note that
|
||||
read-only tools are disabled for Google models (the Gemini API requires
|
||||
`thought_signature` in tool call round-trips which the judge's normalized
|
||||
format does not preserve).
|
||||
|
||||
The judge creates one fresh HTTP client per active batch worker and closes each
|
||||
when that worker finishes, avoiding cross-thread client sharing and stale
|
||||
connections across runs.
|
||||
The judge creates a fresh HTTP client for each evaluation run and closes it
|
||||
when done, avoiding stale connection issues across runs.
|
||||
|
||||
If the LLM judge fails or returns no verdict, a fallback verdict with tier
|
||||
`llm_fallback` is delivered via the callback, ensuring the UI always receives
|
||||
@@ -255,48 +232,25 @@ calls for approval, it calls `_evaluate_intent()` which:
|
||||
4. Attaches each heuristic verdict to its item as `_heuristic_verdict`
|
||||
5. The daemon thread runs the LLM judge and delivers results via `ui.on_intent_verdict()`
|
||||
|
||||
The daemon coordinates up to `parallel_evaluations` independent workers for
|
||||
one batch. Completed verdicts stream to the UI as workers finish, and every call
|
||||
still receives exactly one LLM or `llm_fallback` verdict. The default of 1 keeps
|
||||
the historical serial behavior; a higher value collapses a wide batch toward
|
||||
`ceil(batch size / workers)` judge-call intervals. A smaller positive model
|
||||
alias capacity also bounds the worker count, avoiding surplus threads queued at
|
||||
the same admission gate.
|
||||
|
||||
With `cancel_on_approval = false` (the default) the daemon runs every item to
|
||||
completion: verdicts that land after the operator decided still stream to the
|
||||
UI and persist, stamped with the decision. A newer main-loop batch, session
|
||||
close, or explicit Stop retires the old generation; unfinished items degrade
|
||||
to `llm_fallback` verdicts. A judge/model binding or parallelism edit prevents
|
||||
reuse on the next batch, while already-started calls stay pinned to the binding
|
||||
and worker count they began with. With `cancel_on_approval = true`, an ordinary
|
||||
gate decision additionally aborts unfinished work, trading verdict completeness
|
||||
for inference savings—recommended when the judge shares a single local
|
||||
inference backend with the session model. Explicit Stop always cancels every
|
||||
live judge generation, regardless of this preference.
|
||||
The daemon evaluates items sequentially, so a large parallel batch can outlive
|
||||
its approval gate. With `cancel_on_approval = false` (the default) the daemon
|
||||
runs every item to completion: verdicts that land after the operator decided
|
||||
still stream to the UI and persist, stamped with the decision. The daemon is
|
||||
aborted only when the next tool batch supersedes it or the session closes —
|
||||
then each unfinished item degrades to an `llm_fallback` verdict. With
|
||||
`cancel_on_approval = true` the abort additionally fires the moment the gate
|
||||
resolves, trading verdict completeness for inference savings — recommended
|
||||
when the judge shares a single local inference backend with the session model,
|
||||
where a large batch's remaining judge calls would otherwise compete with the
|
||||
next turn's completion.
|
||||
|
||||
Verdicts that arrive after a *newer batch* has replaced the judge generation
|
||||
are withheld from the live surfaces (a reused call_id must never ride a stale
|
||||
`approve` into Smart Approvals) but still persist with
|
||||
`user_decision = "superseded"` so the audit trail records the judge's answer.
|
||||
|
||||
Sub-agent (task agent) tool calls are judge-gated too. Each runs the same
|
||||
intent pipeline as its own `agent_gate` generation, grounded in that sub-agent's
|
||||
own trajectory -- its task prompt is the delegation contract the operator
|
||||
approved, so "does this call serve the task" is the right local question.
|
||||
Agent-gate generations never occupy the main loop's supersede slot (parallel
|
||||
siblings would otherwise make each other's verdicts look stale); per-cycle
|
||||
generation checks enforce staleness instead, and `judge.cancel_on_approval`
|
||||
fires per gate exactly like the main loop.
|
||||
|
||||
Several parallel task agents can therefore leave several approval cycles live
|
||||
on one workstream. Each cycle owns its event, result, verdict set, and
|
||||
`cycle_id`; a decision targets exactly one cycle by `cycle_id` or member
|
||||
`call_id` (selector-less legacy clients resolve the oldest). Workstream Stop or
|
||||
close performs a workstream-wide denial sweep over all cycles belonging to the
|
||||
cancelled operation. A force-cancel successor's newly registered cycle carries
|
||||
a fresh operation witness and is not accidentally denied by the predecessor's
|
||||
late sweep.
|
||||
Sub-agents (plan agent, task agent) are exempt from intent validation -- they
|
||||
always get full tool visibility without judge evaluation.
|
||||
|
||||
---
|
||||
|
||||
@@ -455,12 +409,13 @@ Redaction types: `api_key`, `private_key`, `password`, `secret`.
|
||||
|
||||
### Configuration
|
||||
|
||||
```text
|
||||
judge.output_guard = true # enable output evaluation (default)
|
||||
judge.redact_secrets = true # auto-redact detected credentials (default)
|
||||
```toml
|
||||
[judge]
|
||||
output_guard = true # enable output evaluation (default)
|
||||
redact_secrets = true # auto-redact detected credentials (default)
|
||||
```
|
||||
|
||||
Configure both at runtime through the admin Judge settings.
|
||||
Configurable at runtime via the admin Settings tab.
|
||||
|
||||
### Merge semantics (heuristic + LLM judge)
|
||||
|
||||
|
||||
+4
-65
@@ -17,9 +17,8 @@ The MCP server admin form exposes three authorization modes ("Multitenant Author
|
||||
| `none` | No headers attached. Open MCP server (or one gated by network policy only). | Internal MCP servers on a trusted network. |
|
||||
| `static` | One static bearer token, configured per server, sent on every request from every user. | Service-to-service MCP servers where per-user attribution doesn't matter, or single-tenant deployments. |
|
||||
| `oauth_user` *(recommended for user-data servers)* | Each user authorizes separately via OAuth 2.1 + PKCE; Turnstone stores per-user tokens encrypted at rest. | MCP servers that expose user-specific data or that want per-user audit attribution. |
|
||||
| `oauth_obo` *(sign-in passthrough)* | Each user's Turnstone **org sign-in** (OIDC) mints a per-server access token on demand — no separate per-server consent. One captured credential per user covers every `oauth_obo` server. | Enterprise deployments where the identity provider governs access (Entra, Keycloak) and you want zero per-user connect clicks. See the dedicated section below. |
|
||||
|
||||
Switching `auth_type` away from `oauth_user` / `oauth_obo` **deletes** that server's per-user rows (consents / minted cache) — see the transition table below. Switching back later starts clean: users re-consent (or re-mint) on next use. The admin **bulk-revoke** / **flush cache** affordance clears rows without an auth-type change.
|
||||
Switching `auth_type` away from `oauth_user` orphans existing per-user tokens. Use the admin **bulk-revoke** affordance on the server row (Phase 9) to clear them, or let them expire naturally — they're inert without the matching `auth_type` value.
|
||||
|
||||
---
|
||||
|
||||
@@ -66,59 +65,6 @@ Keep this in `config.toml` rather than environment variables. An in-process LLM
|
||||
|
||||
---
|
||||
|
||||
## `auth_type=oauth_obo` — single-credential sign-in passthrough
|
||||
|
||||
Where `oauth_user` makes each user complete a **separate** browser consent per MCP server, `oauth_obo` reuses the user's Turnstone **org sign-in** (OIDC). Turnstone captures one refresh credential per user at login and, on each tool call, mints a short-lived access token scoped to that server's audience. There is no per-server connect step, and one credential covers every `oauth_obo` server. This is the right shape when your identity provider already governs who may reach each backend (an Entra tenant with Entra-protected MCP servers; a Keycloak realm with token exchange).
|
||||
|
||||
Access is governed **downstream** by the IdP: a user can only mint a token for a server their delegated permissions allow. Removing that grant at the IdP cuts the user off regardless of their Turnstone state.
|
||||
|
||||
### Deployment configuration (`[oidc]` in `config.toml`)
|
||||
|
||||
`oauth_obo` requires OIDC SSO to be configured (it is the credential source), plus:
|
||||
|
||||
```toml
|
||||
[oidc]
|
||||
# ... your existing issuer / client_id / client_secret ...
|
||||
capture_user_credential = true # persist the IdP refresh token at login
|
||||
obo_grant_profile = "entra" # "entra" | "rfc8693" — how tokens are minted
|
||||
```
|
||||
|
||||
- **`capture_user_credential`** (default `false`): when enabled, Turnstone appends `offline_access` to the login scopes and stores the returned refresh token, encrypted with the same `[security] mcp_token_encryption_key` as `oauth_user` tokens. **The encryption key is required** — Turnstone refuses to start with an `oauth_obo` row (or capture enabled) and no key.
|
||||
- **`obo_grant_profile`** picks the mint mechanism (the IdP determines which one is valid; this is deployment-wide, not per-server):
|
||||
- **`entra`** — redeems the user's refresh token directly for a token scoped to `<audience>/.default`. `oauth_scopes` on the server row is **not used** (the admin form rejects it under this profile).
|
||||
- **`rfc8693`** — a refresh grant for a subject token, then an RFC 8693 token exchange for the server audience. Per-server `oauth_scopes` **are** sent on the exchange (some IdPs require the audience scope explicitly).
|
||||
|
||||
### Adding an `oauth_obo` server
|
||||
|
||||
In the admin MCP form, choose **Sign-in passthrough** and set **Audience** (required — the downstream resource the token is minted for, e.g. `api://<app-id>` on Entra or the client id on Keycloak). The client-id / secret / registration fields do not apply and are hidden.
|
||||
|
||||
`oauth_obo` servers are accepted only when **OIDC sign-in is configured and enabled** and `[oidc] obo_grant_profile` is a valid profile — the write is rejected otherwise, since a row that can never mint would surface to users as a permanent "please retry" that never heals.
|
||||
|
||||
### Identity-provider setup
|
||||
|
||||
**Entra (`obo_grant_profile = "entra"`):**
|
||||
1. Turnstone's app registration must hold **delegated permissions** to each MCP server's exposed API, with **admin consent granted** (or the MCP app listed in Turnstone's `preAuthorizedApplications`).
|
||||
2. Set the server row's Audience to the MCP app's Application ID URI (`api://<guid>`).
|
||||
3. **Gotcha (verified):** admin-consent issued *immediately* after creating the app/service principal can silently skip a not-yet-propagated resource — the only symptom is `AADSTS65001` at mint time. Verify the delegated grant landed (`az ad app permission list-grants` / the portal's *API permissions* blade shows *Granted*), or grant it explicitly per resource. A missing grant surfaces in Turnstone as a re-login prompt on the affected server (same rail as a revoked credential), and the `mcp_server.oauth.obo_mint_rejected` log line carries the raw `AADSTS…` text.
|
||||
|
||||
**Keycloak / RFC 8693 (`obo_grant_profile = "rfc8693"`):**
|
||||
1. Enable **standard token exchange** on Turnstone's client.
|
||||
2. Grant the audience: add an audience client scope for each MCP client and attach it to Turnstone's client (optional scopes must be requested — set the server row's Scopes to that scope, or the exchange returns *"Requested audience not available"*).
|
||||
3. Set the server row's Audience to the downstream client id.
|
||||
|
||||
### Revocation & custody
|
||||
|
||||
The captured credential is a single per-user secret that can mint for every `oauth_obo` server, so treat it like any long-lived credential:
|
||||
|
||||
- **Cut off one user:** unlink their OIDC identity in the admin console (**Users → OIDC identities → delete**). This revokes the captured credential **and** purges their minted cache rows, so future mints fail and cached tokens are dropped. (Warmed in-memory sessions on server nodes self-expire at the access-token TTL; there is no cross-node per-user session-kill.) Removing the user's access at the IdP is the authoritative cut-off.
|
||||
- The same unlink also purges that user's synthetic `__model_obo__:` gateway-token rows and requests eviction from every registered host's in-process mint memo. Shared `entra_app` model tokens live under the `__app__` pseudo-user and are intentionally not user-deprovisioned; revoking the app credential prevents new mints, while a cached app bearer lasts until `expires_at`.
|
||||
- **Flush a server's minted tokens** (e.g. after narrowing its audience): the server row's **flush cache** action drops all users' cached tokens for that server. This is **not** a revocation — users re-mint on next use from their still-valid sign-in. It is surfaced honestly (audit `mcp_server.oauth.obo_cache_flushed`, response `effect: cache_flush_remints`) so it is never mistaken for cutting access.
|
||||
- Per-server revocation in the `oauth_user` sense does not exist for `oauth_obo` — the credential is issuer-scoped and IdP-governed. Revoke at the IdP.
|
||||
|
||||
> **Interim for Entra without OBO:** if you don't want host-side minting, admin consent + `preAuthorizedApplications` on each MCP app registration removes the second consent prompt for the plain `oauth_user` flow too (a tenant-config change, no Turnstone code). Tracked in issue #682. It does not remove the per-server connect clicks or per-(user, server) token custody — that is what `oauth_obo` is for.
|
||||
|
||||
---
|
||||
|
||||
## Lifecycle
|
||||
|
||||
1. **First tool call** for a user against an `oauth_user` MCP server: pool dispatch finds no stored token, returns `mcp_consent_required` to the agent. Dashboard renders an inline "Connect" action card.
|
||||
@@ -129,7 +75,7 @@ The captured credential is a single per-user secret that can mint for every `oau
|
||||
|
||||
4. **Step-up scope**: when a tool call hits `403` with `WWW-Authenticate: error="insufficient_scope"`, Turnstone emits `mcp_insufficient_scope` with the parsed scope set; the dashboard offers a "Connect with additional scopes" affordance that opens `/v1/api/mcp/oauth/start?server=<name>&scopes=<extra>` so the union of original + new scopes flows into the AS authorize request.
|
||||
|
||||
5. **User revoke** (settings modal): `DELETE /v1/api/mcp/oauth/connections/{server_name}` runs the authoritative local delete + best-effort RFC 7009 upstream revoke (fire-and-forget, capped at 256 concurrent in-flight tasks). `oauth_obo` servers and synthetic model-auth rows are excluded: their rows are mint caches, not consents — deleting one only forces a re-mint — so the connections list hides them and the endpoint refuses them with `409` (revocation for sign-in passthrough happens at the identity layer: unlink the identity or revoke at the IdP).
|
||||
5. **User revoke** (settings modal): `DELETE /v1/api/mcp/oauth/connections/{server_name}` runs the authoritative local delete + best-effort RFC 7009 upstream revoke (fire-and-forget, capped at 256 concurrent in-flight tasks).
|
||||
|
||||
6. **Admin bulk-revoke** (Phase 9): `POST /v1/api/admin/mcp-servers/{name}/bulk-revoke` drops every user's token for the server. Upstream RFC 7009 revoke is intentionally **not** attempted in bulk (avoids N upstream HTTP calls per admin click); tokens at the AS expire naturally. Use the per-user revoke endpoint if you need guaranteed upstream invalidation.
|
||||
|
||||
@@ -151,13 +97,10 @@ Additional indicators (circuit-breaker state, encryption-key mismatch) are expos
|
||||
| From | To | What happens |
|
||||
|---|---|---|
|
||||
| `none` / `static` → `oauth_user` | — | New code path activates for this server. Existing static headers (if any) are no longer sent. Users must authorize on first use. |
|
||||
| `oauth_user` → `none` / `static` | — | Existing `mcp_user_tokens` rows are **deleted**: the tokens are bound to the auth model + URL active at consent time, and rows left behind could silently rebind if a row with the old name/URL reappears. Switching back to `oauth_user` later starts clean — users re-consent on next use. This is **not reversible**; the AS-side grants are untouched (revoke upstream via the AS if needed). |
|
||||
| `oauth_user` → `none` / `static` | — | Existing `mcp_user_tokens` rows are **orphaned** — inert without a matching `auth_type`. Use admin bulk-revoke to drop them, or let them expire. Switching back to `oauth_user` later re-activates the orphaned rows if they haven't been deleted. |
|
||||
| OAuth `client_id` or `client_secret` rotated | — | Existing tokens may stop refreshing if the AS treats them as bound to the previous client. Bulk-revoke after rotation. |
|
||||
| `oauth_user` ↔ `oauth_obo` | — | The per-user rows are **deleted** on the flip (they mean different things: per-server AS refresh tokens vs. minted cache). `oauth_audience` and `oauth_scopes` mean different things in each model (a resource indicator vs. an IdP app identifier; AS-consent scopes vs. an rfc8693 exchange scope), so on a flip they **never carry** — each is taken from the request for the target model or set NULL. The admin console clears these fields when you change the auth type, so re-enter the correct values for the new mode; via the API, supply them explicitly (a flip into `oauth_obo` with no `oauth_audience` is rejected, and a non-empty `oauth_scopes` under the `entra` profile is rejected since that leg pins `<audience>/.default`). |
|
||||
| `oauth_obo` → `none` / `static` | — | Minted cache rows are deleted. |
|
||||
| `oauth_obo` **audience**, **URL**, or **`oauth_scopes`** changed | — | Minted cache rows are **deleted** (tokens are bound to the audience/URL/scopes at mint time), forcing a fresh mint — so an audience or scope narrowing takes effect immediately, not at token expiry. |
|
||||
|
||||
Every transition that changes what a stored row *means* deletes the rows outright — a stale consent or minted token must never be served under new semantics. There is no orphan-and-reactivate path.
|
||||
The orphan-by-default behavior is chosen so switching back to `oauth_user` is non-destructive. Bulk-revoke is the explicit cleanup path.
|
||||
|
||||
---
|
||||
|
||||
@@ -170,9 +113,5 @@ Every transition that changes what a stored row *means* deletes the rows outrigh
|
||||
| `mcp_oauth_url_insecure` | MCP server URL is `http://` (not `https://`) on a non-loopback host | Use `https://`. Per-user bearers must not transit cleartext. |
|
||||
| Tools fail in scheduled / Discord / Slack runs | OAuth-MCP requires browser-based consent | Users must pre-consent via the web UI. Phase 9 dashboard badge surfaces deferred consents from these runs on next login. |
|
||||
| Circuit breaker open repeatedly | Transport-level errors on the MCP server (DNS, TLS, 5xx) | Check the per-server error pill; auth errors do not trip the breaker. |
|
||||
| **`oauth_obo`**: every tool call fails, log shows `obo_misconfigured` | Server row has no Audience, or `obo_grant_profile` is unset/unknown | Set the Audience on the server row; set `[oidc] obo_grant_profile` to `entra` or `rfc8693`. |
|
||||
| **`oauth_obo`**: `obo_mint_rejected` with `AADSTS65001` | Turnstone's app lacks the (admin-consented) delegated grant to this MCP app — often admin consent that didn't propagate | Grant + admin-consent the delegated permission for this resource; verify it shows *Granted*. See the Entra gotcha above. |
|
||||
| **`oauth_obo`**: "Sign in to Turnstone again" on one server | Captured credential missing/rejected, or a Conditional Access challenge | User re-logs into Turnstone (re-captures the credential). If it persists, check the IdP grant / CA policy. |
|
||||
| **`oauth_obo`**: tools don't appear at all for a user | User has not signed in since `capture_user_credential` was enabled (no credential captured) | User logs out and back in via OIDC so the refresh credential is captured. |
|
||||
|
||||
See also: `docs/operations/mcp-oauth-headless.md` for the cron / channel-driven run caveat.
|
||||
|
||||
+42
-94
@@ -20,7 +20,7 @@ Each memory has three dimensions:
|
||||
| Type | Purpose |
|
||||
|-------------|------------------------------------------------------------|
|
||||
| `user` | User preferences, conventions, working style |
|
||||
| `general` | General knowledge, architecture, patterns |
|
||||
| `project` | Project-specific knowledge, architecture, patterns |
|
||||
| `feedback` | Corrections, lessons learned, things to avoid |
|
||||
| `reference` | Reference material, documentation, specifications |
|
||||
|
||||
@@ -31,37 +31,25 @@ Each memory has three dimensions:
|
||||
| `global` | Visible to all workstreams and users |
|
||||
| `workstream` | Visible only within the originating workstream |
|
||||
| `user` | Follows the authenticated user across workstreams |
|
||||
| `coordinator` | Coordinator sessions only; follows the acting user |
|
||||
| `project` | Shared by workstreams attached to one active project |
|
||||
| `coordinator` | Coordinator sessions only; follows the user across coordinators |
|
||||
|
||||
A memory's identity is the tuple `(name, scope, scope_id)`. Saving a memory
|
||||
with the same identity upserts -- updating content while preserving the ID.
|
||||
|
||||
### Inherited target and coordinator scope
|
||||
### Coordinator scope
|
||||
|
||||
Name-based operations use one inherited target when `scope` is omitted:
|
||||
|
||||
- An attached active project selects `project` for `save`, `get`, and
|
||||
`delete`.
|
||||
- Read-only project access permits `get`, but `save` and `delete` fail. They do
|
||||
not fall back to a broader namespace.
|
||||
- Without a project, interactive sessions select `global`; coordinator
|
||||
sessions select `coordinator`.
|
||||
|
||||
A valid explicit scope selects exactly that scope. `search` and `list` are the
|
||||
only actions that span every visible scope when `scope` is omitted.
|
||||
|
||||
Each coordinator's private `coordinator` namespace is keyed by the acting
|
||||
user's `user_id`. It is durable -- every coordinator session that user runs
|
||||
(including concurrent ones) shares one orchestration namespace, so procedures
|
||||
and lessons survive close/reopen.
|
||||
Coordinator sessions are isolated to a single scope: `coordinator`, keyed by
|
||||
the coordinator's creator `user_id`. It is durable -- every coordinator
|
||||
session the same user runs (including concurrent ones) shares one
|
||||
orchestration namespace, so procedures and lessons survive close/reopen.
|
||||
|
||||
Isolation is bidirectional and enforced by session kind, not by secrecy of
|
||||
the scope id:
|
||||
|
||||
- A coordinator session sees its acting user's `coordinator` scope and, when
|
||||
attached, the shared `project` scope. It never sees
|
||||
`global`/`workstream`/`user` memories.
|
||||
- A coordinator session can read and write **only** `coordinator`-scope rows.
|
||||
It never sees `global`/`workstream`/`user` memories, so content written by
|
||||
interactive sessions (which routinely ingest untrusted MCP/attachment
|
||||
output) cannot reach a coordinator's system message.
|
||||
- Interactive sessions -- including a coordinator's own children, which share
|
||||
its `user_id` -- are rejected from the `coordinator` scope on every memory
|
||||
action. Children cannot plant rows the parent coordinator would read.
|
||||
@@ -76,13 +64,12 @@ coordinator cannot be constructed, so the scope id is always a real user.
|
||||
|
||||
On every conversation turn, the system:
|
||||
|
||||
1. Resolves the acting principal and their live project access
|
||||
2. Fetches up to `fetch_limit` memories across that visibility envelope
|
||||
3. Extracts context from the last 3 user messages
|
||||
4. Scores memories against that context using a BM25 index
|
||||
5. Injects the top `relevance_k` memories into the system message as
|
||||
1. Fetches up to `fetch_limit` memories visible in the current scope
|
||||
2. Extracts context from the last 3 user messages
|
||||
3. Scores memories against that context using a BM25 index
|
||||
4. Injects the top `relevance_k` memories into the system message as
|
||||
`<memories>` XML tags
|
||||
6. Appends a hint telling the model how many memories are in scope
|
||||
5. Appends a hint telling the model how many memories are in scope
|
||||
|
||||
This means the model always has its most relevant memories available without
|
||||
explicit recall -- but can still use `memory(action='search')` for deeper
|
||||
@@ -120,23 +107,19 @@ All fields are optional. Defaults are shown above.
|
||||
|
||||
## Tool Usage
|
||||
|
||||
The `memory` tool supports five actions:
|
||||
The `memory` tool supports four actions:
|
||||
|
||||
### save
|
||||
|
||||
Store or update a memory.
|
||||
|
||||
Every save is a complete write for the relevance summary: `description` must
|
||||
be supplied and contain non-whitespace text on both creation and update.
|
||||
Content-only updates are rejected.
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "save",
|
||||
"name": "project_architecture",
|
||||
"content": "The project uses a hexagonal architecture with...",
|
||||
"description": "Core architecture patterns",
|
||||
"type": "general",
|
||||
"type": "project",
|
||||
"scope": "global"
|
||||
}
|
||||
```
|
||||
@@ -145,26 +128,9 @@ Content-only updates are rejected.
|
||||
|---------------|----------|-------------|------------------------------------------|
|
||||
| `name` | yes | -- | Snake_case identifier (max 256 chars) |
|
||||
| `content` | yes | -- | Memory content (max `max_content` chars) |
|
||||
| `description` | yes | -- | Non-empty relevance summary, required on create and update |
|
||||
| `type` | no | `"general"` | One of: user, general, feedback, reference |
|
||||
| `scope` | no | inherited | Kind-valid scope; see inherited target above |
|
||||
|
||||
### get
|
||||
|
||||
Retrieve the full content of one memory by name.
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "get",
|
||||
"name": "project_architecture",
|
||||
"scope": "project"
|
||||
}
|
||||
```
|
||||
|
||||
| Parameter | Required | Default | Description |
|
||||
|-----------|----------|-----------|----------------------------|
|
||||
| `name` | yes | -- | Memory name to retrieve |
|
||||
| `scope` | no | inherited | Exact scope to query |
|
||||
| `description` | no | `""` | Short description for relevance matching |
|
||||
| `type` | no | `"project"` | One of: user, project, feedback, reference |
|
||||
| `scope` | no | `"global"` | One of: global, workstream, user |
|
||||
|
||||
### search
|
||||
|
||||
@@ -174,7 +140,7 @@ Find memories by query (BM25 full-text search).
|
||||
{
|
||||
"action": "search",
|
||||
"query": "authentication patterns",
|
||||
"type": "general",
|
||||
"type": "project",
|
||||
"limit": 10
|
||||
}
|
||||
```
|
||||
@@ -201,7 +167,7 @@ Remove a memory by name.
|
||||
| Parameter | Required | Default | Description |
|
||||
|------------|----------|------------|--------------------------|
|
||||
| `name` | yes | -- | Memory name to delete |
|
||||
| `scope` | no | inherited | Exact scope to delete |
|
||||
| `scope` | no | `"global"` | Scope of the memory |
|
||||
|
||||
### list
|
||||
|
||||
@@ -231,12 +197,6 @@ Four endpoints on the server for programmatic memory access.
|
||||
|
||||
List memories with optional filters.
|
||||
|
||||
Without `scope`, the response is restricted to `global` plus the authenticated
|
||||
caller's `user` namespace. The public API accepts only `global`, `user`, and
|
||||
`workstream`; internal `project` and `coordinator` namespaces remain available
|
||||
through the session tool and admin API. Explicit `workstream` access requires
|
||||
its persisted owner (or a service token).
|
||||
|
||||
**Query parameters:**
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
@@ -244,10 +204,10 @@ its persisted owner (or a service token).
|
||||
| `type` | string | no | `""` | Filter by memory type |
|
||||
| `scope` | string | no | `""` | Filter by scope |
|
||||
| `scope_id` | string | no | `""` | Filter by scope ID |
|
||||
| `limit` | int | no | `100` | Max results (1-200) |
|
||||
| `limit` | int | no | `100` | Max results (capped at 200) |
|
||||
|
||||
When `scope=user`, the authenticated user's ID is used automatically and a
|
||||
different supplied ID is rejected. `scope=workstream` requires `scope_id`.
|
||||
When `scope=user` and `scope_id` is omitted, the authenticated user's ID is
|
||||
used automatically.
|
||||
|
||||
**Response:** `200`
|
||||
|
||||
@@ -258,7 +218,7 @@ different supplied ID is rejected. `scope=workstream` requires `scope_id`.
|
||||
"memory_id": "a1b2c3d4-e5f6-...",
|
||||
"name": "project_architecture",
|
||||
"description": "Core architecture patterns",
|
||||
"type": "general",
|
||||
"type": "project",
|
||||
"scope": "global",
|
||||
"scope_id": "",
|
||||
"content": "The project uses a hexagonal architecture...",
|
||||
@@ -276,9 +236,6 @@ different supplied ID is rejected. `scope=workstream` requires `scope_id`.
|
||||
|
||||
Save or upsert a structured memory.
|
||||
|
||||
`description` is mandatory for both creates and updates and must contain
|
||||
non-whitespace text. The API rejects content-only updates.
|
||||
|
||||
**Request body:**
|
||||
|
||||
```json
|
||||
@@ -286,7 +243,7 @@ non-whitespace text. The API rejects content-only updates.
|
||||
"name": "deployment_process",
|
||||
"content": "Deploy via GitHub Actions. Staging auto-deploys on push to main.",
|
||||
"description": "CI/CD deployment workflow",
|
||||
"type": "general",
|
||||
"type": "project",
|
||||
"scope": "global",
|
||||
"scope_id": ""
|
||||
}
|
||||
@@ -296,8 +253,8 @@ non-whitespace text. The API rejects content-only updates.
|
||||
|--------------|--------|----------|-------------|--------------------------------------|
|
||||
| `name` | string | yes | -- | Memory name (max 256 chars) |
|
||||
| `content` | string | yes | -- | Memory content (max 65536 chars) |
|
||||
| `description`| string | yes | -- | Non-empty relevance summary, required on create and update |
|
||||
| `type` | string | no | unset | user, general, feedback, or reference |
|
||||
| `description`| string | no | `""` | Short description for search ranking |
|
||||
| `type` | string | no | `"project"` | One of: user, project, feedback, reference |
|
||||
| `scope` | string | no | `"global"` | One of: global, workstream, user |
|
||||
| `scope_id` | string | no | `""` | Scope qualifier (auto-resolved for user scope) |
|
||||
|
||||
@@ -308,7 +265,7 @@ non-whitespace text. The API rejects content-only updates.
|
||||
"memory_id": "a1b2c3d4-e5f6-...",
|
||||
"name": "deployment_process",
|
||||
"description": "CI/CD deployment workflow",
|
||||
"type": "general",
|
||||
"type": "project",
|
||||
"scope": "global",
|
||||
"scope_id": "",
|
||||
"content": "Deploy via GitHub Actions...",
|
||||
@@ -324,10 +281,7 @@ same `(name, scope, scope_id)` already existed.
|
||||
|
||||
| Status | Condition |
|
||||
|--------|------------------------------------|
|
||||
| 400 | Invalid input, scope, scope ID, or limit |
|
||||
| 403 | Cross-user or non-owner workstream access |
|
||||
| 404 | Explicit workstream does not exist |
|
||||
| 500 | Storage mutation failed |
|
||||
| 400 | Missing name, empty content, invalid type/scope, content too long |
|
||||
|
||||
---
|
||||
|
||||
@@ -336,15 +290,12 @@ same `(name, scope, scope_id)` already existed.
|
||||
Search memories by query. Uses POST for the request body but is non-mutating
|
||||
(requires only `read` scope).
|
||||
|
||||
An omitted scope searches the same caller-bound `global` + `user` envelope as
|
||||
the list endpoint. It never means every row in the table.
|
||||
|
||||
**Request body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "authentication",
|
||||
"type": "general",
|
||||
"type": "project",
|
||||
"scope": "",
|
||||
"scope_id": "",
|
||||
"limit": 20
|
||||
@@ -357,7 +308,7 @@ the list endpoint. It never means every row in the table.
|
||||
| `type` | string | no | `""` | Filter by type |
|
||||
| `scope` | string | no | `""` | Filter by scope |
|
||||
| `scope_id` | string | no | `""` | Filter by scope ID |
|
||||
| `limit` | int | no | `20` | Max results (1-50) |
|
||||
| `limit` | int | no | `20` | Max results (capped at 50) |
|
||||
|
||||
**Response:** `200`
|
||||
|
||||
@@ -368,7 +319,7 @@ the list endpoint. It never means every row in the table.
|
||||
"memory_id": "a1b2c3d4-e5f6-...",
|
||||
"name": "auth_patterns",
|
||||
"description": "Authentication architecture",
|
||||
"type": "general",
|
||||
"type": "project",
|
||||
"scope": "global",
|
||||
"scope_id": "",
|
||||
"content": "JWT tokens with HS256...",
|
||||
@@ -386,9 +337,6 @@ the list endpoint. It never means every row in the table.
|
||||
|
||||
Delete a memory by name and scope.
|
||||
|
||||
Deletes are atomic: the row used for the success result and audit event is the
|
||||
row actually removed. A storage failure returns `500`, not a false `404`.
|
||||
|
||||
**Path parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
@@ -443,7 +391,7 @@ List memories across all scopes (no automatic scope resolution).
|
||||
"memory_id": "a1b2c3d4-e5f6-...",
|
||||
"name": "project_architecture",
|
||||
"description": "Core architecture patterns",
|
||||
"type": "general",
|
||||
"type": "project",
|
||||
"scope": "global",
|
||||
"scope_id": "",
|
||||
"content": "The project uses...",
|
||||
@@ -492,7 +440,7 @@ Get a single memory by ID.
|
||||
"memory_id": "a1b2c3d4-e5f6-...",
|
||||
"name": "project_architecture",
|
||||
"description": "Core architecture patterns",
|
||||
"type": "general",
|
||||
"type": "project",
|
||||
"scope": "global",
|
||||
"scope_id": "",
|
||||
"content": "The project uses...",
|
||||
@@ -549,13 +497,13 @@ with TurnstoneServer("http://localhost:8080", token="tok_xxx") as client:
|
||||
"api_conventions",
|
||||
"All endpoints use /v1/ prefix. JSON responses.",
|
||||
description="API design patterns",
|
||||
mem_type="general",
|
||||
mem_type="project",
|
||||
scope="global",
|
||||
)
|
||||
print(mem.memory_id)
|
||||
|
||||
# Search memories
|
||||
results = client.search_memories("authentication", mem_type="general", limit=10)
|
||||
results = client.search_memories("authentication", mem_type="project", limit=10)
|
||||
for m in results.memories:
|
||||
print(f"{m['name']}: {m['description']}")
|
||||
|
||||
@@ -576,7 +524,7 @@ with TurnstoneConsole("http://localhost:9090", token="tok_xxx") as admin:
|
||||
result = admin.list_memories(scope="global", limit=100)
|
||||
|
||||
# Search
|
||||
result = admin.search_memories("architecture", mem_type="general")
|
||||
result = admin.search_memories("architecture", mem_type="project")
|
||||
|
||||
# Get by ID
|
||||
mem = admin.get_memory("a1b2c3d4-e5f6-...")
|
||||
@@ -600,14 +548,14 @@ const mem = await client.saveMemory({
|
||||
name: "api_conventions",
|
||||
content: "All endpoints use /v1/ prefix. JSON responses.",
|
||||
description: "API design patterns",
|
||||
type: "general",
|
||||
type: "project",
|
||||
scope: "global",
|
||||
});
|
||||
|
||||
// Search memories
|
||||
const results = await client.searchMemories({
|
||||
query: "authentication",
|
||||
type: "general",
|
||||
type: "project",
|
||||
limit: 10,
|
||||
});
|
||||
|
||||
|
||||
+9
-108
@@ -41,7 +41,6 @@ are set.
|
||||
| `TURNSTONE_OIDC_PASSWORD_ENABLED` | No | `true` | Set to `false` to hide the password form and block all username/password logins (including admin). API tokens continue to work. |
|
||||
| `TURNSTONE_OIDC_REDIRECT_BASE` | Yes | — | Externally-reachable origin for the OIDC redirect URI (e.g. `https://app.example.com`). Without this, OIDC will refuse to start. The previous Host-header fallback was unsafe under permissive reverse proxies. |
|
||||
| `TURNSTONE_OIDC_TRUSTED_ENDPOINT_HOSTS` | No | — | Comma-separated list of additional hostnames whose endpoints the IdP discovery document is allowed to reference. See [Cross-host endpoints](#cross-host-endpoints). |
|
||||
| `TURNSTONE_OIDC_ALLOW_PRIVATE_NETWORK` | No | `false` | Allow the issuer (and its discovered endpoints) to resolve to private/internal addresses — needed for a self-hosted IdP on an internal network. See [Self-hosted and internal IdPs](#self-hosted-and-internal-idps). |
|
||||
|
||||
All four required fields — issuer, client ID, client secret, and
|
||||
`TURNSTONE_OIDC_REDIRECT_BASE` — must be set. If any are missing OIDC
|
||||
@@ -77,17 +76,17 @@ IdP from redirecting the token-exchange POST (which carries
|
||||
being aimed at internal services.
|
||||
|
||||
A few public IdPs legitimately split endpoints across hostnames. Google
|
||||
and Microsoft Entra ID are the canonical examples:
|
||||
is the canonical example:
|
||||
|
||||
| IdP | Issuer host | Cross-host endpoint(s) |
|
||||
|-----|-------------|------------------------|
|
||||
| Google | `accounts.google.com` | `oauth2.googleapis.com`, `www.googleapis.com`, `openidconnect.googleapis.com` |
|
||||
| Microsoft Entra | `login.microsoftonline.com` | `graph.microsoft.com` (userinfo) |
|
||||
| Field | Hostname |
|
||||
|-------|----------|
|
||||
| issuer | `accounts.google.com` |
|
||||
| token_endpoint | `oauth2.googleapis.com` |
|
||||
| jwks_uri | `www.googleapis.com` |
|
||||
| userinfo_endpoint | `openidconnect.googleapis.com` |
|
||||
|
||||
Both sets are built in — operators using `https://accounts.google.com` or
|
||||
`https://login.microsoftonline.com/<tenant>/v2.0` need no extra
|
||||
configuration. (Entra's discovery document advertises `userinfo_endpoint`
|
||||
on `graph.microsoft.com`, distinct from the issuer host.)
|
||||
Google's set is built in — operators using `https://accounts.google.com`
|
||||
need no extra configuration.
|
||||
|
||||
For other IdPs whose discovery document references a non-issuer host,
|
||||
extend the allow-list explicitly:
|
||||
@@ -100,102 +99,6 @@ The same scheme / no-userinfo / SSRF rules apply to allow-listed hosts —
|
||||
this knob only relaxes the same-origin check, not the security gates.
|
||||
Each entry is a hostname (no scheme, no path).
|
||||
|
||||
### Self-hosted and internal IdPs
|
||||
|
||||
By default Turnstone refuses an issuer whose hostname resolves to a
|
||||
private or internal address:
|
||||
|
||||
```
|
||||
OIDCError: endpoint URL resolves to non-public address (10.0.0.5): https://auth.example.site
|
||||
```
|
||||
|
||||
This is SSRF hardening, not a licensing or product restriction: the OIDC
|
||||
flow makes server-side HTTP requests (discovery, JWKS, token exchange),
|
||||
and refusing non-public destinations keeps a mistyped or maliciously
|
||||
steered issuer from aiming those fetches at internal services. For a
|
||||
self-hosted IdP (Keycloak, Authentik, Dex, …) on a private network,
|
||||
opt in explicitly in `config.toml`:
|
||||
|
||||
```toml
|
||||
[oidc]
|
||||
allow_private_network = true
|
||||
```
|
||||
|
||||
or via `TURNSTONE_OIDC_ALLOW_PRIVATE_NETWORK=true` (the env var wins
|
||||
when both are set).
|
||||
|
||||
The opt-in admits private-range (RFC 1918), unique-local, site-local,
|
||||
CGNAT (100.64/10, where overlay VPNs commonly assign hosts), and
|
||||
loopback addresses. Link-local, multicast, reserved ranges and known
|
||||
cloud-metadata endpoints stay refused even with the opt-in — no
|
||||
legitimate IdP lives there. An address is judged by what it actually
|
||||
reaches, so an IPv6 transition address (NAT64, 6to4, Teredo) wrapping
|
||||
an internal IPv4 is treated exactly as that IPv4 would be. The HTTPS
|
||||
requirement and the same-origin endpoint checks are unaffected.
|
||||
|
||||
This knob only affects the login-flow IdP configured here. OAuth
|
||||
endpoints advertised by remote MCP servers are untrusted input and are
|
||||
always held to the strict public-address rule.
|
||||
|
||||
### Model gateway credentials
|
||||
|
||||
The same OIDC registration can authenticate model gateways. A model definition
|
||||
with `auth_mode = "entra_obo"` (Entra grant profile) or `auth_mode =
|
||||
"rfc8693_obo"` (RFC 8693 token-exchange profile) redeems the driving user's
|
||||
captured credential for its exact `obo_audience`; `auth_mode = "entra_app"`
|
||||
uses the registration's client ID and secret with Entra client credentials.
|
||||
All three bind the result through the provider SDK's native credential option
|
||||
rather than injecting an override header. The grant mode is never inferred:
|
||||
missing user context or a failed OBO mint cannot switch a delegated definition
|
||||
to client credentials.
|
||||
|
||||
Each dynamic mode pairs with the grant profile whose dialect it names:
|
||||
`entra_obo` and `entra_app` require `obo_grant_profile = "entra"`;
|
||||
`rfc8693_obo` requires `obo_grant_profile = "rfc8693"`. The pairing is
|
||||
enforced when a write chooses a `(auth_mode, obo_audience)` pair — a same-pair
|
||||
edit of a row saved before the pairing rule keeps working — and at runtime a
|
||||
mismatched legacy row refuses to mint with `cause=grant_profile_mismatch` and
|
||||
no IdP traffic. RFC 8693 client-credentials is not implemented.
|
||||
|
||||
The delegated modes need the MCP encryption key, a credential captured for the
|
||||
driving user, and delegated/admin-consented permission to the audience.
|
||||
`rfc8693_obo` additionally carries `obo_scopes`, the space-separated scope
|
||||
list its exchange leg requests: exchange-capable IdPs that gate audiences
|
||||
behind optional scopes refuse the exchange without it ("Requested audience not
|
||||
available"), which is why the scope-less Entra-named mode could never mint on
|
||||
that profile (issue #955). Scopes are stored shape-checked only — whether a
|
||||
value satisfies the IdP stays the IdP's call at mint time. Turning
|
||||
`capture_user_credential` off later stops *new* captures but does not
|
||||
invalidate credentials already stored, so existing users keep minting.
|
||||
`entra_app` requires a confidential-client secret. Configure the permitted
|
||||
resource IDs in the runtime setting `model.auth_audience_allowlist` before
|
||||
saving dynamic model definitions. De-listing an audience later blocks every
|
||||
write that would arm or re-aim a definition at it, but does not stop aliases
|
||||
already configured from minting — disabling the row (the `admin.models` disarm
|
||||
lever) is what stops minting. See
|
||||
[Settings](settings.md#model-backend-authentication) for permissions, failure
|
||||
policy, and lane identity rules.
|
||||
|
||||
An unrecognised `obo_grant_profile` is warned about at startup and **rejected
|
||||
at the write choke points**: configuring an `oauth_obo` MCP server or a dynamic
|
||||
model alias returns a 400 that echoes the configured value, so the typo is the
|
||||
diagnosis. At runtime an unknown profile never mints — the mint legs resolve by
|
||||
exact name; the full cause detail is logged once per audience, and every
|
||||
affected call still logs its per-turn fallback or refusal naming the alias,
|
||||
the target audience, and the last recorded cause (`cause=` — for example
|
||||
`unsupported_grant_profile` or `oidc_not_enabled`) — so a pre-existing row
|
||||
degrades loudly, with the reason visible mid-incident even after the
|
||||
once-per-process line has rotated out of retained logs, rather than silently
|
||||
swapping per-user attribution for the shared static key.
|
||||
|
||||
The `[security]` token encryption key is deployment-wide, not per-host: rows are
|
||||
encrypted with `MultiFernet` and carry no key id, so every host that reads them
|
||||
needs the same keyring. That includes the console, which mints for
|
||||
coordinator-hosted sessions. A node that needs the key and lacks it refuses to
|
||||
start; the console starts but withholds its coordinator subsystem and shows
|
||||
the key requirement as the remediation error instead of failing silently at
|
||||
call time.
|
||||
|
||||
### config.toml alternative
|
||||
|
||||
```toml
|
||||
@@ -208,8 +111,6 @@ provider_name = "Google"
|
||||
role_claim = "groups"
|
||||
password_enabled = true
|
||||
redirect_base = "https://app.example.com"
|
||||
# Self-hosted IdP on an internal network (see "Self-hosted and internal IdPs")
|
||||
allow_private_network = false
|
||||
|
||||
[oidc.role_map]
|
||||
admin = "builtin-admin"
|
||||
|
||||
+6
-39
@@ -46,8 +46,8 @@ reads only the stamp:
|
||||
`creative_mode` set are converted by migration `063` into full
|
||||
`writer` stamps, so they resume as writing sessions rather than as
|
||||
legacy defaults.
|
||||
- Forking (`resume_ws` on create) clones the source's stamped persona into the
|
||||
new workstream; the fork does not re-resolve it.
|
||||
- Forking (`resume_ws` on create) resumes the source's stamped persona; the
|
||||
fork does not re-resolve.
|
||||
|
||||
## Seed personas
|
||||
|
||||
@@ -118,37 +118,9 @@ seeded):
|
||||
`persona` argument, validated when the coordinator prepares the spawn
|
||||
and re-checked by the node that creates the child (children are always
|
||||
interactive-kind). Omitted means the interactive **default** — a child
|
||||
never inherits its parent coordinator's persona.
|
||||
- **Sub-agents**: `task_agent` takes a `persona` argument setting the
|
||||
sub-agent's identity and capability envelope (resolved against
|
||||
interactive-kind personas, frozen into the task at prep). Omitted keeps
|
||||
the default autonomous task-agent identity — never the parent's persona.
|
||||
|
||||
## How agents discover personas
|
||||
|
||||
Agents are told, not expected to guess: the live persona list (enabled,
|
||||
interactive-kind — children and sub-agents are always interactive) is
|
||||
injected into the `persona` parameter description of `task_agent`,
|
||||
`spawn_workstream`, and `spawn_batch` whenever the session's tool surface
|
||||
is rendered — session start, MCP catalog change, model-registry reload.
|
||||
Each entry carries the name, the default marker, and the persona's
|
||||
one-line description so the model can pick by purpose (descriptions drop
|
||||
out past 25 personas; the name list always enumerates completely).
|
||||
|
||||
A persona created after that render is still reachable — pass its name.
|
||||
Every resolve failure enumerates the names currently valid for the kind,
|
||||
so a stale list (or a typo) self-corrects on the next attempt.
|
||||
|
||||
Resolution is forgiving on all surfaces (they share one rule):
|
||||
|
||||
- names match case-insensitively (`Writer` resolves `writer`);
|
||||
- an input that uniquely matches a persona's **display name**
|
||||
(case-insensitive, among the kind's enabled personas — display names are
|
||||
not unique, and a same-label persona of another kind neither blocks nor
|
||||
wins) resolves to that persona; an ambiguous match errors, listing the
|
||||
candidate slugs;
|
||||
- whatever variant matched, the stamped identity, approval chrome, and
|
||||
wire always carry the canonical `name` slug.
|
||||
never inherits its parent coordinator's persona. Sub-agents spawned via
|
||||
`task_agent` have no persona parameter at all; they keep their own
|
||||
identity and envelope.
|
||||
|
||||
## Authoring (console)
|
||||
|
||||
@@ -156,12 +128,7 @@ Personas are managed in the console's **Manage → Governance → Personas**
|
||||
tab. The admin shelf exposes exactly the four levers plus the kind
|
||||
list, the default marker, and archive. Rules:
|
||||
|
||||
- `name` is an immutable lowercase slug — and the identifier agents and
|
||||
the CLI launch the persona by (`persona=` on the spawn tools,
|
||||
`--persona` on the CLI); the create shelf says so under **Name**.
|
||||
`display_name` is a list label, editable any time, and deliberately
|
||||
not an identifier (a unique display name happens to resolve, as a
|
||||
forgiveness fallback — don't design workflows around it).
|
||||
- `name` is an immutable lowercase slug; edit `display_name` instead.
|
||||
- Exactly one default per kind, storage-enforced: flipping the flag on a
|
||||
successor demotes the incumbent atomically, defaults are single-kind,
|
||||
and a default cannot be archived.
|
||||
|
||||
+8
-44
@@ -15,19 +15,11 @@ down to a small number of real database connections.
|
||||
|
||||
## Why PgBouncer works well with turnstone
|
||||
|
||||
Most turnstone database operations are short-burst queries: acquire a
|
||||
connection, execute a small transaction, commit, release. Workstream forks are
|
||||
the deliberate exception: they clone the source's checkpoint-bounded history
|
||||
and configuration and retain its attachment references in one transaction.
|
||||
PostgreSQL runs that clone at `SERIALIZABLE` isolation and retries serialization
|
||||
or deadlock conflicts as a whole. A large fork can therefore hold its assigned
|
||||
server connection longer than an ordinary message write.
|
||||
|
||||
This still makes **transaction pooling mode** the right fit — no operation
|
||||
depends on server-session state, and PgBouncer returns the connection as soon
|
||||
as the transaction finishes. Size and monitor the server pool with concurrent
|
||||
fork traffic in mind rather than assuming every transaction completes in a few
|
||||
milliseconds.
|
||||
All turnstone database operations are short-burst queries: acquire a
|
||||
connection, execute 1–3 statements, commit, release. No operation holds
|
||||
a connection for more than a few milliseconds. This makes **transaction
|
||||
pooling mode** ideal — PgBouncer assigns a real connection only for the
|
||||
duration of each transaction, then returns it to the pool.
|
||||
|
||||
| Cluster size | Client connections (max) | PgBouncer server connections needed |
|
||||
|--------------|------------------------|-------------------------------------|
|
||||
@@ -151,11 +143,9 @@ PgBouncer (which then multiplexes to PostgreSQL):
|
||||
| `TURNSTONE_DB_URL` | — | Connection URL (point at PgBouncer, not PostgreSQL directly) |
|
||||
|
||||
The default pool of 2 + 3 overflow = 5 connections per process is
|
||||
intentionally small to support large clusters. Most deployments should not
|
||||
need to increase it. If operators create many large forks concurrently, watch
|
||||
PgBouncer's `cl_waiting` and PostgreSQL transaction latency before changing
|
||||
the per-process pool; adding client-side connections cannot help once the
|
||||
PgBouncer server pool is saturated.
|
||||
intentionally small to support large clusters. You should not need to
|
||||
increase this — turnstone's database operations are all short-burst
|
||||
context-managed queries that hold connections for milliseconds.
|
||||
|
||||
SQLAlchemy `pool_pre_ping` is enabled, so stale connections (e.g. after
|
||||
PgBouncer restarts) are automatically detected and replaced.
|
||||
@@ -187,32 +177,6 @@ Key metrics to watch:
|
||||
- **`sv_active`** — active server (PostgreSQL) connections. Should stay
|
||||
below PostgreSQL `max_connections`.
|
||||
|
||||
Short `cl_waiting` spikes during large workstream forks can be normal. Sustained
|
||||
waiters accompanied by long serializable transactions indicate fork/storage
|
||||
load, not an SSE or HTTP client-pool problem.
|
||||
|
||||
---
|
||||
|
||||
## Upgrade note: deferred workstream creation
|
||||
|
||||
The workstream lifecycle now uses durable, hidden `state='creating'`
|
||||
reservations while session construction, upload validation, and optional fork
|
||||
cloning complete. Older server processes do not understand that private state:
|
||||
against the same database they may resolve, list, open, or prune a reservation
|
||||
before its new owner publishes it.
|
||||
|
||||
For the upgrade that introduces deferred creation, drain create traffic and
|
||||
upgrade all server processes sharing the database as one cohort. Do not resume
|
||||
creates until no older server process remains. The change needs no manual
|
||||
schema migration, but it is not safe to treat mixed lifecycle implementations
|
||||
as an ordinary rolling-upgrade state.
|
||||
|
||||
A `creating` row should be transient and absent from normal APIs and cluster
|
||||
events. If one persists after a process crash, inspect the corresponding
|
||||
`ws.create.*` and `session_mgr.commit_create.*` logs before cleanup. Do not
|
||||
promote it to `idle` manually: its history, configuration, attachment
|
||||
references, or lifecycle publication may be incomplete.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
+29
-138
@@ -50,7 +50,6 @@ with TurnstoneServer("http://localhost:8080") as client:
|
||||
import asyncio
|
||||
from turnstone.sdk import AsyncTurnstoneServer
|
||||
|
||||
|
||||
async def main():
|
||||
async with AsyncTurnstoneServer("http://localhost:8080") as client:
|
||||
await client.login(username="alice", password="s3cret")
|
||||
@@ -59,7 +58,6 @@ async def main():
|
||||
if event.type == "content":
|
||||
print(event.text, end="", flush=True)
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
@@ -71,18 +69,17 @@ Both `TurnstoneServer` (sync) and `AsyncTurnstoneServer` (async) expose:
|
||||
|----------|--------|---------|
|
||||
| **Workstreams** | `list_workstreams()` | `ListWorkstreamsResponse` |
|
||||
| | `dashboard()` | `DashboardResponse` |
|
||||
| | `create_workstream(*, name, model, auto_approve, resume_ws, skill, persona, initial_message, project_id, attachments, ...)` | `CreateWorkstreamResponse` |
|
||||
| | `create_workstream(*, name, model, auto_approve, skill, persona, initial_message, attachments)` | `CreateWorkstreamResponse` |
|
||||
| | `close_workstream(ws_id)` | `StatusResponse` |
|
||||
| **Attachments** | `upload_attachment(ws_id, filename, data, *, mime_type=...)` | `UploadAttachmentResponse` |
|
||||
| | `list_attachments(ws_id)` | `ListAttachmentsResponse` |
|
||||
| | `get_attachment_content(ws_id, attachment_id)` | `bytes` |
|
||||
| | `delete_attachment(ws_id, attachment_id)` | `StatusResponse` |
|
||||
| **Chat** | `send(message, ws_id, *, attachment_ids=None, client_send_id=None)` | `SendResponse` |
|
||||
| | `approve(*, ws_id, approved, feedback, always, cycle_id, call_id)` | `ApproveResponse` |
|
||||
| **Chat** | `send(message, ws_id)` | `SendResponse` |
|
||||
| | `approve(*, ws_id, approved, feedback, always)` | `StatusResponse` |
|
||||
| | `command(*, ws_id, command)` | `StatusResponse` |
|
||||
| | `cancel(ws_id, *, force=False)` | `CancelResponse` |
|
||||
| **History** | `get_history(ws_id, *, limit=100)` | `WorkstreamHistoryResponse` |
|
||||
| **Streaming** | `stream_events(ws_id, *, last_event_id=None, history_token=None)` | `Iterator[ServerEvent]` |
|
||||
| | `cancel(ws_id, *, force=False)` | `StatusResponse` |
|
||||
| **Streaming** | `stream_events(ws_id)` | `Iterator[ServerEvent]` |
|
||||
| | `stream_global_events()` | `Iterator[ServerEvent]` |
|
||||
| **High-level** | `send_and_wait(message, ws_id, *, timeout, on_event)` | `TurnResult` |
|
||||
| **Saved** | `list_saved_workstreams()` | `ListSavedWorkstreamsResponse` |
|
||||
@@ -103,7 +100,7 @@ Both `TurnstoneConsole` (sync) and `AsyncTurnstoneConsole` (async) expose:
|
||||
| | `workstreams(*, state, node, search, sort, page, per_page)` | `ClusterWorkstreamsResponse` |
|
||||
| | `node_detail(node_id)` | `NodeDetailResponse` |
|
||||
| | `snapshot()` | `ClusterSnapshotResponse` |
|
||||
| | `create_workstream(*, node_id, name, model, initial_message, skill, persona, resume_ws)` | `ConsoleCreateWsResponse` |
|
||||
| | `create_workstream(*, node_id, name, model, initial_message, skill, persona)` | `ConsoleCreateWsResponse` |
|
||||
| **Schedules** | `list_schedules()` | `ListSchedulesResponse` |
|
||||
| | `create_schedule(*, name, schedule_type, initial_message, ...)` | `ScheduleInfo` |
|
||||
| | `get_schedule(task_id)` | `ScheduleInfo` |
|
||||
@@ -128,12 +125,12 @@ SSE events are deserialized into typed dataclasses. Use `event.type` to discrimi
|
||||
| Type | Class | Key Fields |
|
||||
|------|-------|------------|
|
||||
| `connected` | `ConnectedEvent` | `model`, `model_alias`, `skip_permissions` |
|
||||
| `user_turn` | `UserTurnEvent` | `ws_id`, `content`, `attachments`, `sender`, `source`, `client_send_ids`, `_event_id` |
|
||||
| `history` | `HistoryEvent` | `messages` |
|
||||
| `content` | `ContentEvent` | `text` |
|
||||
| `reasoning` | `ReasoningEvent` | `text` |
|
||||
| `tool_info` | `ToolInfoEvent` | `items` |
|
||||
| `approve_request` | `ApproveRequestEvent` | `cycle_id`, `items` |
|
||||
| `tool_result` | `ToolResultEvent` | `call_id`, `name`, `output`, `is_error`, `preview`, `accepted`, `effect_status`, `_event_id` |
|
||||
| `approve_request` | `ApproveRequestEvent` | `items` |
|
||||
| `tool_result` | `ToolResultEvent` | `call_id`, `name`, `output`, `is_error` |
|
||||
| `tool_output_chunk` | `ToolOutputChunkEvent` | `call_id`, `chunk` |
|
||||
| `status` | `StatusEvent` | `prompt_tokens`, `total_tokens`, `pct`, `effort`, `cache_creation_tokens`, `cache_read_tokens` |
|
||||
| `error` | `ErrorEvent` | `message` |
|
||||
@@ -141,92 +138,14 @@ SSE events are deserialized into typed dataclasses. Use `event.type` to discrimi
|
||||
| `stream_end` | `StreamEndEvent` | — |
|
||||
| `state_change` | `StateChangeEvent` | `state` ∈ `running`/`thinking`/`attention`/`idle`/`error` |
|
||||
| `in_progress_snapshot` | `InProgressSnapshotEvent` | `content`, `reasoning` (one-shot mid-stream refresh resume) |
|
||||
| `approval_resolved` | `ApprovalResolvedEvent` | `cycle_id`, `call_ids`, `approved`, `feedback`, `always` |
|
||||
| `approval_resolved` | `ApprovalResolvedEvent` | `approved`, `feedback` |
|
||||
| `cancelled` | `CancelledEvent` | — |
|
||||
| `history_resync` | `HistoryResyncEvent` | `reason`, optional `ws_id` |
|
||||
|
||||
The Python server `send()` and console `coordinator_send()` methods accept an
|
||||
optional `client_send_id`; TypeScript `send()` accepts the equivalent
|
||||
`options.clientSendId`. Values match `[A-Za-z0-9_-]{1,128}`. The value is an
|
||||
opaque optimistic-UI correlation token, not an idempotency key: reusing it
|
||||
still creates distinct accepted turns and events.
|
||||
Every upgraded listener on the shared workstream receives `UserTurnEvent`.
|
||||
Originating panes use `client_send_ids` only to settle the exact optimistic
|
||||
bubble, while peers render the accepted row once by `_event_id`. A
|
||||
`message_queued` event carrying the token can establish acceptance even if the
|
||||
POST acknowledgement is lost. History projects the same correlation alongside
|
||||
the accepted user row. These tokens are not credentials: when sender and viewer
|
||||
identities are both known, only a matching sender may settle local optimistic
|
||||
state; a peer event still renders its canonical row.
|
||||
|
||||
The typed projection is negotiated with `?user_turn=1` on the per-workstream
|
||||
SSE URL. Python `stream_events()` / `send_and_wait()` and TypeScript
|
||||
`streamEvents()` / `sendAndWait()` set it automatically. Raw consumers that
|
||||
omit it receive a backward-compatible `replay_truncated` repair signal instead
|
||||
of the user row and must rebuild from `/history`; its pre-row cursor keeps the
|
||||
repair retryable if that history request fails.
|
||||
|
||||
The browser-only final-tool upsert capability is `?tool_turn=1`. The bundled
|
||||
Python and TypeScript SDK streaming helpers and channel adapters intentionally
|
||||
do not negotiate it yet: they retain the executor-receipt `tool_result`
|
||||
contract and do not own a transcript reducer. `ToolResultEvent` can deserialize
|
||||
the accepted fields for direct/custom capable clients. Raw capable clients must
|
||||
deduplicate `_event_id` and replace the newest matching call occurrence; raw
|
||||
incapable clients receive the pre-row `tool_turn_projection_unsupported` repair
|
||||
frame and rebuild from history. That staging deliberately prices in two costs
|
||||
for incapable consumers. A raw client that treats every `replay_truncated`
|
||||
frame as a rebuild trigger refetches `/history` once per accepted tool row —
|
||||
one fetch per tool call on a long agentic turn; a client that wants tool
|
||||
results incrementally should negotiate `tool_turn=1` and reduce, and the
|
||||
bundled helpers (which ignore the frame rather than rebuild) stay correct
|
||||
because their receipt-only view never depends on the accepted projection.
|
||||
Second, only the accepted event carries post-execution output transforms, so a
|
||||
receipt-rendering consumer (for example, a channel adapter posting the
|
||||
executor receipt into a thread) keeps the pre-transform text; the accepted
|
||||
projection is a transcript-consistency mechanism, not a wire confidentiality
|
||||
boundary — see the API reference note on the preliminary `tool_result`.
|
||||
|
||||
Current servers bootstrap conversation history through
|
||||
`GET /v1/api/workstreams/{ws_id}/history` before the SSE stream; they do not
|
||||
emit a `history` event. `HistoryEvent` remains deserializable only for
|
||||
compatibility with older servers. `get_history()` exposes the current REST
|
||||
bootstrap response, including its optional cursor and one-shot handoff token.
|
||||
|
||||
### Caller-managed history handoff
|
||||
|
||||
The SDK supplies typed handshake primitives but intentionally does not own a
|
||||
transcript renderer or reconnect policy. After rendering a successful history
|
||||
response, pass its cursor and token to exactly one initial stream:
|
||||
|
||||
```python
|
||||
from turnstone.sdk import HistoryResyncEvent
|
||||
|
||||
history = client.get_history(ws_id)
|
||||
render(history.messages)
|
||||
|
||||
for event in client.stream_events(
|
||||
ws_id,
|
||||
last_event_id=history.cursor,
|
||||
history_token=history.handoff_token,
|
||||
):
|
||||
if isinstance(event, HistoryResyncEvent):
|
||||
# Stop this stream. The caller chooses when to fetch, render, and
|
||||
# reconnect with a new history response.
|
||||
break
|
||||
apply_live_event(event)
|
||||
```
|
||||
|
||||
`history_resync` means numeric replay cannot prove that the rendered limited
|
||||
tail came from the same total accepted conversation-row prefix. Stop the
|
||||
stream, fetch and render history again, and use only the new cursor/token pair.
|
||||
A 503 history response raises `TurnstoneAPIError`; it is not authoritative, so
|
||||
retain any existing transcript and do not open a tokenless replacement stream.
|
||||
|
||||
**Global events** (from `stream_global_events()`):
|
||||
|
||||
| Type | Class | Key Fields |
|
||||
|------|-------|------------|
|
||||
| `ws_state` | `WsStateEvent` | `ws_id`, `state`, `tokens`, `activity`, `persistence_state` |
|
||||
| `ws_state` | `WsStateEvent` | `ws_id`, `state`, `tokens`, `activity` |
|
||||
| `ws_activity` | `WsActivityEvent` | `ws_id`, `activity`, `activity_state` |
|
||||
| `ws_rename` | `WsRenameEvent` | `ws_id`, `name` |
|
||||
| `ws_closed` | `WsClosedEvent` | `ws_id` |
|
||||
@@ -237,30 +156,24 @@ retain any existing transcript and do not open a tokenless replacement stream.
|
||||
|------|-------|------------|
|
||||
| `node_joined` | `NodeJoinedEvent` | `node_id` |
|
||||
| `node_lost` | `NodeLostEvent` | `node_id` |
|
||||
| `cluster_state` | `ClusterStateEvent` | `ws_id`, `node_id`, `state`, `tokens`, `persistence_state` |
|
||||
| `ws_created` | `ClusterWsCreatedEvent` | `ws_id`, `node_id`, `name`, `persistence_state` |
|
||||
| `cluster_state` | `ClusterStateEvent` | `ws_id`, `node_id`, `state`, `tokens` |
|
||||
| `ws_created` | `ClusterWsCreatedEvent` | `ws_id`, `node_id`, `name` |
|
||||
| `ws_closed` | `ClusterWsClosedEvent` | `ws_id` |
|
||||
| `ws_rename` | `ClusterWsRenameEvent` | `ws_id`, `name` |
|
||||
| `snapshot` | `ClusterSnapshotEvent` | `nodes`, `overview`, `timestamp` |
|
||||
|
||||
Operator-facing workstream rows and rich state events expose only the sanitized
|
||||
`persistence_state`: `healthy`, `pending`, `retrying`, or `conflict`. SDK types
|
||||
treat it as optional for compatibility with older nodes; an omitted value means
|
||||
`healthy`. Retry counts, storage errors, commit keys, and conversation content
|
||||
are never part of this status surface.
|
||||
|
||||
### TurnResult
|
||||
|
||||
The `send_and_wait()` method returns a `TurnResult` that aggregates the full response:
|
||||
|
||||
```python
|
||||
result = client.send_and_wait("Hello", ws_id, timeout=60)
|
||||
result.content # Full text response
|
||||
result.reasoning # Chain-of-thought (if shown)
|
||||
result.tool_results # List of (tool_name, output) tuples
|
||||
result.errors # Any error messages
|
||||
result.ok # True if no errors and not timed out
|
||||
result.timed_out # True if timeout expired
|
||||
result.content # Full text response
|
||||
result.reasoning # Chain-of-thought (if shown)
|
||||
result.tool_results # List of (tool_name, output) tuples
|
||||
result.errors # Any error messages
|
||||
result.ok # True if no errors and not timed out
|
||||
result.timed_out # True if timeout expired
|
||||
```
|
||||
|
||||
### Attachments
|
||||
@@ -270,7 +183,9 @@ Upload files to a workstream and attach them to the next user turn:
|
||||
```python
|
||||
# Upload separately, then send a message — attachments auto-attach
|
||||
with open("screenshot.png", "rb") as f:
|
||||
att = client.upload_attachment(ws.ws_id, "screenshot.png", f.read(), mime_type="image/png")
|
||||
att = client.upload_attachment(ws.ws_id, "screenshot.png",
|
||||
f.read(),
|
||||
mime_type="image/png")
|
||||
client.send("What's wrong in this screenshot?", ws.ws_id)
|
||||
|
||||
# Or attach at workstream-creation time (multipart upload)
|
||||
@@ -280,7 +195,9 @@ with open("notes.txt", "rb") as f:
|
||||
ws = client.create_workstream(
|
||||
name="triage",
|
||||
initial_message="Summarize the notes",
|
||||
attachments=[AttachmentUpload(data=f.read(), filename="notes.txt", mime_type="text/plain")],
|
||||
attachments=[AttachmentUpload(data=f.read(),
|
||||
filename="notes.txt",
|
||||
mime_type="text/plain")],
|
||||
)
|
||||
```
|
||||
|
||||
@@ -289,26 +206,6 @@ Limits: images ≤ 4 MiB (png/jpeg/gif/webp), text ≤ 512 KiB (UTF-8),
|
||||
client so cluster-routed callers bind attachments to the owning node
|
||||
before the request lands.
|
||||
|
||||
### Forking a workstream
|
||||
|
||||
`resume_ws` is the API's compatibility name for an atomic fork. It creates a
|
||||
new workstream ID while the source remains unchanged:
|
||||
|
||||
```python
|
||||
fork = client.create_workstream(
|
||||
resume_ws=ws.ws_id,
|
||||
name="analysis-branch",
|
||||
initial_message="Try the alternative plan.",
|
||||
)
|
||||
assert fork.resumed
|
||||
```
|
||||
|
||||
The server transaction clones the source's checkpoint-bounded history, saved
|
||||
session configuration, persona, project, and attachment references. Do not
|
||||
combine `resume_ws` with `attachments`; fork first, then upload to the new ID.
|
||||
To rehydrate the original ID rather than branch it, call the server's
|
||||
`POST /v1/api/workstreams/{ws_id}/open` endpoint.
|
||||
|
||||
### Error Handling
|
||||
|
||||
Non-2xx responses raise `TurnstoneAPIError`:
|
||||
@@ -320,7 +217,7 @@ try:
|
||||
client.send("hi", "bad_ws_id")
|
||||
except TurnstoneAPIError as e:
|
||||
print(e.status_code) # 404
|
||||
print(e.message) # "Unknown workstream"
|
||||
print(e.message) # "Unknown workstream"
|
||||
```
|
||||
|
||||
---
|
||||
@@ -345,14 +242,8 @@ const ws = await client.createWorkstream({ name: "demo" });
|
||||
const result = await client.sendAndWait("Hello!", ws.ws_id);
|
||||
console.log(result.content);
|
||||
|
||||
// Render history, then use its one-shot hints on the initial stream.
|
||||
const history = await client.getHistory(ws.ws_id);
|
||||
render(history.messages);
|
||||
for await (const event of client.streamEvents(ws.ws_id, {
|
||||
lastEventId: history.cursor ?? undefined,
|
||||
historyToken: history.handoff_token ?? undefined,
|
||||
})) {
|
||||
if (event.type === "history_resync") break; // caller refetches and reconnects
|
||||
// Stream events
|
||||
for await (const event of client.streamEvents(ws.ws_id)) {
|
||||
if (event.type === "content") {
|
||||
process.stdout.write(event.text);
|
||||
}
|
||||
@@ -428,7 +319,7 @@ turnstone/sdk/ Python SDK (sub-package)
|
||||
_base.py Shared httpx async client, auth, error handling
|
||||
_sync.py Background event loop for sync wrappers
|
||||
_types.py TurnResult + TurnstoneAPIError
|
||||
events.py Typed SSE event dataclasses with type registry
|
||||
events.py 38 SSE event dataclasses with type registry
|
||||
server.py AsyncTurnstoneServer + TurnstoneServer
|
||||
console.py AsyncTurnstoneConsole + TurnstoneConsole
|
||||
|
||||
|
||||
+20
-53
@@ -64,17 +64,15 @@ Scopes are hierarchical — higher scopes imply all lower ones.
|
||||
|
||||
### Path-to-scope mapping
|
||||
|
||||
| Method | Path pattern | Required scope | Additional RBAC gate |
|
||||
|--------|-------------|----------------|----------------------|
|
||||
| GET | Any protected path | `read` | Endpoint-specific where documented |
|
||||
| POST | `/api/command` | `write` | Project tenancy on the target workstream |
|
||||
| POST | `/api/workstreams/new`, `/api/cluster/workstreams/new` | `write` | `workstreams.create` or `admin.coordinator` |
|
||||
| POST | `/api/workstreams/{ws_id}/close` | `write` | `workstreams.close` or `admin.coordinator` |
|
||||
| POST | `/api/workstreams/{ws_id}/approve` | `approve` | `tools.approve` or `admin.coordinator` |
|
||||
| POST | `/api/workstreams/{ws_id}/{rewind,retry}` | `write` | `conversation.modify` |
|
||||
| POST | Other `/api/workstreams/{ws_id}/...` mutation endpoints | `write` | Project tenancy and endpoint-specific gates |
|
||||
| DELETE | `/api/workstreams/{ws_id}/send` (dequeue), `/api/workstreams/{ws_id}/attachments/{attachment_id}` | `write` | Project tenancy on the target workstream |
|
||||
| Any | `/api/admin/*` | `approve` | Matching `admin.*` permission |
|
||||
| Method | Path pattern | Required scope |
|
||||
|--------|-------------|----------------|
|
||||
| GET | Any protected path | `read` |
|
||||
| POST | `/api/command` | `write` |
|
||||
| POST | `/api/workstreams/new`, `/api/cluster/workstreams/new` | `write` |
|
||||
| POST | `/api/workstreams/{ws_id}/{send,cancel,close,delete,open,refresh-title,title,attachments}` | `write` |
|
||||
| DELETE | `/api/workstreams/{ws_id}/send` (dequeue), `/api/workstreams/{ws_id}/attachments/{attachment_id}` | `write` |
|
||||
| POST | `/api/workstreams/{ws_id}/approve` | `approve` |
|
||||
| Any | `/api/admin/*` | `approve` |
|
||||
|
||||
Public paths bypass authentication entirely: `/`, `/health`, `/metrics`,
|
||||
`/static/*`, `/shared/*`, `/docs`, `/openapi.json`, `/api/auth/login`,
|
||||
@@ -86,7 +84,7 @@ Public paths bypass authentication entirely: `/`, `/health`, `/metrics`,
|
||||
> See also: [Governance documentation](governance.md)
|
||||
|
||||
Scopes provide coarse endpoint-level access control. For finer-grained
|
||||
enforcement, the governance layer adds named permissions checked
|
||||
enforcement, the governance layer adds 15 named permissions checked
|
||||
per-endpoint by `require_permission()`. Permissions are bundled into
|
||||
roles; users are assigned roles via the `user_roles` join table.
|
||||
|
||||
@@ -100,8 +98,8 @@ Three built-in roles are seeded by migration 008:
|
||||
|
||||
| Role | Permissions |
|
||||
|------|-------------|
|
||||
| admin | Admin-default baseline (all ordinary admin and lifecycle permissions; explicitly opt-in capabilities remain ungranted) |
|
||||
| operator | read, write, workstreams.create, workstreams.close, conversation.modify |
|
||||
| admin | All 15 permissions |
|
||||
| operator | read, write, workstreams.create, workstreams.close |
|
||||
| viewer | read |
|
||||
|
||||
Custom roles can be created with any subset of the valid permissions.
|
||||
@@ -109,34 +107,6 @@ Role creation and update validate permissions against a static allowlist.
|
||||
Self-assignment is blocked, and assigning a role requires the caller to
|
||||
hold a superset of the target role's permissions.
|
||||
|
||||
### Workstream lifecycle and project boundaries
|
||||
|
||||
The remote `/api/command` endpoint is conversation-local. It refuses
|
||||
`/new`, `/workstreams`, `/resume`, and `/delete` because those local-CLI
|
||||
helpers enumerate or mutate storage outside the HTTP resource gates. Remote
|
||||
clients use the dedicated create, open, close, and delete endpoints instead;
|
||||
`/rewind` and `/retry` have their own path-keyed, `conversation.modify`-gated
|
||||
endpoints.
|
||||
|
||||
Passing `resume_ws` to create is an atomic **fork**, not an in-place resume.
|
||||
It requires the ordinary create capability and source visibility. A private
|
||||
project source is visible only to its workstream creator, project owner/member,
|
||||
or authorized service-to-service cluster plumbing; denials use a not-found
|
||||
response so guessed IDs do not become an existence oracle. The caller must also
|
||||
be allowed to attach a new workstream to the source's current project. The
|
||||
destination always inherits that effective project — a caller-supplied
|
||||
`project_id` cannot re-file or declassify the conversation.
|
||||
|
||||
The canonical preflight atomically captures (and, for a legacy row, installs) a
|
||||
private source-incarnation fence. The storage transaction compares that source
|
||||
fence, rejects provisional sources, repeats the ACL/project check, and verifies
|
||||
the persona/project construction snapshot, destination ownership and
|
||||
incarnation, emptiness, and every referenced attachment before committing. A
|
||||
source replacement, membership, project, persona, or destination-incarnation
|
||||
race aborts the whole fork. Concurrent source-history writes serialize wholly
|
||||
before or after the snapshot; no mixed or partially authorized history or
|
||||
attachment reference becomes visible.
|
||||
|
||||
---
|
||||
|
||||
## Login Flows
|
||||
@@ -471,15 +441,12 @@ Each proxied request gets a fresh JWT (5-minute expiry). This ensures:
|
||||
- **Permission forwarding** — granular RBAC permissions from the
|
||||
console JWT are carried through to the server.
|
||||
|
||||
For ordinary users the JWT `src` claim is set to `"console-proxy"`, allowing
|
||||
servers to distinguish proxied requests from direct logins in audit logs.
|
||||
Coordinator tokens retain `src="coordinator"` and their signed `coord_ws_id`;
|
||||
the console service identity retains `src="console"` only when its validated
|
||||
token also carries the unassignable `service` scope.
|
||||
The JWT `src` claim is set to `"console-proxy"`, allowing servers to
|
||||
distinguish proxied requests from direct logins in audit logs.
|
||||
|
||||
When no user context is available (auth disabled, or internal requests),
|
||||
the proxy falls back to a `ServiceTokenManager` with identity `console-proxy`,
|
||||
`src="console"`, and `{read, write, approve, service}` scopes.
|
||||
the proxy falls back to a `ServiceTokenManager` with service identity
|
||||
`console-proxy` and full scopes.
|
||||
|
||||
### Service-to-service authentication
|
||||
|
||||
@@ -488,8 +455,8 @@ JWTs when communicating with server nodes:
|
||||
|
||||
| Service | Identity | Scope | Audience | Purpose |
|
||||
|---------|----------|-------|----------|---------|
|
||||
| Console collector | `console-collector` | `read`, `service` | `turnstone-server` | Node health polling and global event collection |
|
||||
| Console proxy (fallback) | `console-proxy` | `read`, `write`, `approve`, `service` | `turnstone-server` | Proxied API calls when no user context |
|
||||
| Console collector | `console-collector` | `read` | `turnstone-server` | Node health polling |
|
||||
| Console proxy (fallback) | `console-proxy` | `approve` | `turnstone-server` | Proxied API calls when no user context |
|
||||
| Channel notify | `system` | `write` | `turnstone-channel` | Notification delivery to channel gateway |
|
||||
|
||||
Service tokens use 1-hour expiry with automatic refresh via
|
||||
@@ -501,8 +468,8 @@ When the console creates a workstream (the normal path), the
|
||||
authenticated user's `user_id` is forwarded in the HTTP payload when
|
||||
calling the server's `POST /v1/api/workstreams/new`. The server
|
||||
accepts a `user_id` from the request body **only when the caller is a
|
||||
trusted service** — identified by `token_source="console"` together with the
|
||||
unassignable `service` scope. `console-proxy`, coordinator, and regular API callers cannot
|
||||
trusted service** — identified by `token_source` matching
|
||||
`console-proxy` or `console`. Regular API callers cannot
|
||||
override `user_id`; the server always uses their JWT identity.
|
||||
|
||||
Note that the channel gateway uses a distinct JWT audience
|
||||
|
||||
+11
-182
@@ -54,149 +54,6 @@ When a per-model override is `NULL` (empty in the UI), the global default is
|
||||
used. Switching models via `/model <alias>` re-resolves sampling parameters
|
||||
from the new model's overrides or global defaults.
|
||||
|
||||
### Per-model concurrency
|
||||
|
||||
Each model definition may set `max_concurrency` to limit simultaneous model
|
||||
generations for that alias in one Turnstone process. `0` or an omitted value
|
||||
means unlimited. The gate is shared by every role using the alias—interactive
|
||||
turns, coordinators, task agents, judges, output guards, perception, compaction,
|
||||
and title generation—and a streaming generation holds its slot until the
|
||||
stream is fully drained or closed.
|
||||
|
||||
Admission is strictly per alias. Two aliases remain independent even when they
|
||||
point to the same URL; Turnstone does not infer shared capacity from endpoint
|
||||
text. Queue time is excluded from judge/output-guard deadline accounting, and
|
||||
each retry releases its slot before backoff and reacquires for the next wire
|
||||
attempt. The cap is local to each process, not cluster-wide; account for the
|
||||
number of nodes targeting the same inference server. Direct STT/TTS protocol
|
||||
calls and Cohere/Jina reranking do not currently consume this generation cap.
|
||||
|
||||
### Judge batch parallelism
|
||||
|
||||
`judge.parallel_evaluations` controls how many independent tool calls from one
|
||||
approval batch the intent judge evaluates concurrently. It is an integer from
|
||||
1 through 16 and defaults to 1, preserving serial evaluation until an operator
|
||||
opts into wider fan-out. Changes are hot-read at the next batch; work already
|
||||
in flight keeps its captured worker count.
|
||||
|
||||
This is a per-batch fan-out setting, not another backend capacity limit. The
|
||||
judge model alias's `max_concurrency` gate still caps total generations across
|
||||
all judge batches and every other role using that alias. Actual overlap is
|
||||
therefore bounded by the batch size, `judge.parallel_evaluations`, and available
|
||||
alias admission slots. A smaller positive alias cap also narrows the batch's
|
||||
worker pool so excess judge threads do not queue ahead of later alias traffic.
|
||||
|
||||
### Model backend authentication
|
||||
|
||||
Model definitions support four backend credential modes:
|
||||
|
||||
| `auth_mode` | Identity sent to the model gateway |
|
||||
|-------------|------------------------------------|
|
||||
| `static` | The definition's stored `api_key`. |
|
||||
| `entra_obo` | A caller-delegated Entra access token minted from that user's captured OIDC credential. |
|
||||
| `entra_app` | A shared app-identity token minted with Turnstone's OIDC client credentials. |
|
||||
| `rfc8693_obo` | A caller-delegated access token minted from the captured credential via RFC 8693 token exchange, requesting the definition's `obo_scopes`. |
|
||||
|
||||
Dynamic modes require an exact `obo_audience` resource identifier. Before an
|
||||
admin can save one, an operator must add that literal audience to
|
||||
`model.auth_audience_allowlist` (comma- or newline-separated). Wildcards and
|
||||
base-URL host matching are intentionally unsupported, and a row whose
|
||||
effective mode is `static` refuses to store a new non-empty `obo_audience` on
|
||||
either create or update — an audience cannot be staged for a later flip
|
||||
(clearing a stale value, or re-saving it unchanged, stays allowed).
|
||||
`obo_scopes` follows the same staging rule with the mode set inverted: only
|
||||
`rfc8693_obo` reads it, so every other effective mode refuses to store a new
|
||||
non-empty value, while clearing or re-saving one unchanged stays open. The
|
||||
value itself is optional and shape-checked only — whether it satisfies the
|
||||
IdP is decided at mint time. On a row that is (or becomes) dynamic, every
|
||||
change except the tuning fields — context window, temperature, max tokens,
|
||||
reasoning effort, and the two reasoning-persistence toggles — also requires
|
||||
`admin.mcp`; service tokens do not bypass this capability-escalation gate.
|
||||
The one exception is de-escalation: a save whose only gated change is
|
||||
switching `enabled` off is a pure disable, needs only `admin.models`, and
|
||||
skips validation — a de-listed audience must never block disarming its own
|
||||
row. The gate is deny-by-default: a field counts as auth-relevant unless it
|
||||
is provably neutral, so re-enabling a disabled dynamic row, re-pointing its
|
||||
`base_url`, or swapping its provider or alias all escalate.
|
||||
|
||||
Validation runs in two tiers, matching the MCP `oauth_obo` write rules. Row
|
||||
validity — the audience is allow-listed — applies to every gated write that
|
||||
touches a dynamic configuration, so a revoked audience can be neither silently
|
||||
re-pointed at a new `base_url` nor re-armed by an enable flip. Deployment
|
||||
posture — the token encryption key installed, single sign-on configured, and
|
||||
the grant profile valid and able to carry the mode — is checked when a write
|
||||
*chooses* the mode/audience pair and when it re-enables a disabled dynamic
|
||||
row (arming is the flip that resumes minting, so it must meet what minting
|
||||
needs); other edits to an existing row stay open if the deployment's posture
|
||||
changed after it was saved (its mints warn at runtime instead). Refusals name
|
||||
their cause and echo the configured value.
|
||||
|
||||
One asymmetry to be aware of: the write path counts a transient discovery
|
||||
outage (`enabled=false`, retryable) as configured, but the mints themselves
|
||||
require discovery to have completed — a config saved during an outage starts
|
||||
minting only once any authenticated request heals discovery. Until then calls
|
||||
warn and follow the fail-open/fail-closed policy above.
|
||||
|
||||
Every dynamic mode pairs with exactly one grant profile: `entra_obo` and
|
||||
`entra_app` require `[oidc] obo_grant_profile = "entra"`, and `rfc8693_obo`
|
||||
requires `"rfc8693"`. The pairing is enforced at the posture tier, so a row
|
||||
saved before the rule existed keeps accepting same-pair edits; its mints
|
||||
refuse at runtime with `cause=grant_profile_mismatch` and no IdP traffic.
|
||||
Judge, output-guard, perception, utility, and sub-agent lanes inherit the
|
||||
session's effective user for the delegated modes. The perception memo is
|
||||
partitioned by that principal as well as alias and content hash, so a result
|
||||
authorized as one user cannot be served to another. Scheduled and wake-driven
|
||||
work retains the workstream owner even when no user is connected. Eval and
|
||||
optimizer lanes are registry-less development tools and therefore do not use
|
||||
dynamic model authentication.
|
||||
|
||||
`entra_app` is an explicit model-definition choice; Turnstone never changes a
|
||||
failed or ownerless delegated call into a client-credentials grant. A
|
||||
delegated-mode call with no effective user always refuses. A dynamic alias
|
||||
without a real static key also always refuses instead of issuing its
|
||||
SDK-construction placeholder. When a real static key is explicitly configured,
|
||||
mint failures may use it by default; set `model.auth_fail_closed = true` to
|
||||
prohibit even that fallback. A refusal is not routed through the model
|
||||
fallback chain.
|
||||
|
||||
Dynamic token caches are encrypted in `mcp_user_tokens`, shared across nodes,
|
||||
and memoized on each host. Unlinking a user's OIDC identity purges their
|
||||
delegated-mode rows and memo entries. `entra_app` rows belong to the shared
|
||||
`__app__` identity and are not user-deprovisioned; after client-credential
|
||||
revocation, an already-minted app bearer remains usable until its recorded
|
||||
expiry.
|
||||
|
||||
Each model call resolves its dynamic credential against the immutable model
|
||||
definition snapshot that supplied that call's provider, client, endpoint, and
|
||||
model ID. An admin edit can therefore never pair an old `base_url` with a new
|
||||
audience, grant mode, or static-key fallback input. The principal and token
|
||||
remain per-call/live; the connection and model-owned auth configuration move
|
||||
together as one binding on the next operation. The deployment-wide
|
||||
`model.auth_fail_closed` switch is intentionally read live on every mint, so an
|
||||
operator can tighten fallback policy immediately without rebuilding sessions.
|
||||
|
||||
`obo_audience` and `obo_scopes` are literal and capped at 2048 characters
|
||||
each. Environment-variable expansion is deliberately not applied, so the
|
||||
allow-list decision cannot vary by node or expand beyond the persisted
|
||||
boundary.
|
||||
|
||||
### Responses output controls (per-model)
|
||||
|
||||
Models whose capability table declares Responses output controls expose two
|
||||
additional fields in the Models create/edit shelf:
|
||||
|
||||
| Field | Stored capability | Values | Effect |
|
||||
|-------|-------------------|--------|--------|
|
||||
| Output verbosity | `verbosity` | `low`, `medium`, `high` | Controls answer length independently of reasoning effort. |
|
||||
| Reasoning mode | `reasoning_mode` | `standard`, `pro` | Selects standard or higher-compute Pro execution without changing the model ID. |
|
||||
|
||||
An empty selection means provider default and omits the capability key. Known
|
||||
GPT-5.6 models inherit support from the built-in table without persisting
|
||||
redundant support flags. An OpenAI-compatible model pinned to the Responses API
|
||||
can opt in with the `supports_verbosity` and `supports_pro_mode` capability
|
||||
tiles. Chat Completions and non-Responses providers do not surface or submit
|
||||
these controls.
|
||||
|
||||
**Removed settings:** `model.name` and `model.context_window` have been removed
|
||||
from ConfigStore. Model names and context windows are now configured per-model
|
||||
in the Models tab. A startup warning is logged if these keys appear in
|
||||
@@ -250,7 +107,7 @@ initialization:
|
||||
|
||||
| Section | Settings |
|
||||
|---------|----------|
|
||||
| `model` | default_alias, auth_audience_allowlist, auth_fail_closed, temperature, max_tokens, reasoning_effort, task_alias, task_effort |
|
||||
| `model` | default_alias, temperature, max_tokens, reasoning_effort, task_alias, task_effort |
|
||||
| `session` | instructions, retention_days, compact_max_tokens, auto_compact_pct |
|
||||
| `tools` | timeout, truncation, agent_max_turns, skip_permissions, search, search_threshold, search_max_results |
|
||||
| `server` | workstream_idle_timeout, max_workstreams |
|
||||
@@ -258,7 +115,7 @@ initialization:
|
||||
| `mcp` | config_path, registry_url |
|
||||
| `ratelimit` | enabled, requests_per_second, burst, trusted_proxies |
|
||||
| `health` | backend_probe_interval, backend_probe_timeout, circuit_breaker_threshold, circuit_breaker_cooldown |
|
||||
| `judge` | enabled, model, smart_approvals, confidence_threshold, max_context_ratio, timeout, parallel_evaluations, read_only_tools, output_guard, output_guard_budget_seconds, output_guard_llm, output_guard_model, output_guard_llm_timeout, redact_secrets, cancel_on_approval |
|
||||
| `judge` | enabled, model, provider, base_url, api_key, confidence_threshold, max_context_ratio, timeout, read_only_tools, output_guard, redact_secrets, cancel_on_approval |
|
||||
| `interface` | close_tab_action, theme |
|
||||
| `skills` | discovery_url |
|
||||
| `memory` | relevance_k, fetch_limit, max_content, nudge_cooldown, nudges |
|
||||
@@ -435,11 +292,13 @@ Reset a setting to its registry default by removing it from storage.
|
||||
|
||||
## Secret Settings
|
||||
|
||||
The registry currently defines no production secret system setting. The generic
|
||||
machinery nevertheless treats any future `is_secret=True` entry as write-only:
|
||||
list and write responses return `"***"`, and submitting that sentinel preserves
|
||||
the stored value. Model API keys are fields on model definitions—not
|
||||
`judge.*` system settings—and use the Models tab's separate write-only flow.
|
||||
Settings with `is_secret=True` (currently only `judge.api_key`) are blocked
|
||||
from the write API with a `403` response. This prevents accidental exposure
|
||||
through the admin UI or audit logs. Secret settings must be configured via
|
||||
`config.toml` or environment variables.
|
||||
|
||||
The list endpoint masks secret values: stored secrets appear as `"***"`
|
||||
rather than their actual value.
|
||||
|
||||
---
|
||||
|
||||
@@ -460,40 +319,10 @@ reload.
|
||||
**Behavior after reload:**
|
||||
|
||||
- New workstreams pick up updated values immediately (via `session_factory`)
|
||||
- Most workstream/session settings remain the snapshot captured at creation or
|
||||
resume. Component docs call out deliberate live-read exceptions; for
|
||||
example, Smart Approval settings are snapshotted coherently at the start of
|
||||
each approval batch.
|
||||
- Existing sessions keep their frozen configuration (settings are captured at
|
||||
workstream creation time, not read on every turn)
|
||||
- Settings marked `restart_required=True` need a server restart to take effect
|
||||
|
||||
### Model-definition reloads
|
||||
|
||||
The Models tab has a separate live-reload contract from ordinary ConfigStore
|
||||
settings. Existing sessions remember the concrete registry generation that
|
||||
supplied their active alias and re-resolve that alias at the start of the next
|
||||
send. Endpoint, provider, backend model ID, capabilities, extra parameters, and
|
||||
backend-auth configuration are replaced as one immutable binding. In-flight
|
||||
turns, judges, and task agents finish or cancel against the binding they
|
||||
started with; an admin edit never tears one request across two definitions.
|
||||
The alias's admission gate is retained and resized in place, so a concurrency
|
||||
edit preserves in-flight accounting and does not reset cached judges or the
|
||||
output-guard rate limiter.
|
||||
|
||||
Sampling and other saved workstream configuration remain workstream state. A
|
||||
model-definition edit does not silently rewrite a live workstream's chosen
|
||||
temperature, reasoning effort, max tokens, skill, or persona. Use
|
||||
`/model <alias>` (or create/fork a workstream) when an explicit session-level
|
||||
model switch is intended.
|
||||
|
||||
If a live workstream's alias is deleted, its next send first attempts the
|
||||
configured fallback chain. Without a usable fallback, the operator-facing
|
||||
error names the removed alias and points interactive users to `/model`; adding
|
||||
the alias back causes the next send to rebind without a process restart. If a
|
||||
replacement client cannot be constructed, Turnstone logs one
|
||||
`session.model_refresh_client_construction_failed` warning per registry
|
||||
generation and retries only after another model reload, avoiding a rebuild
|
||||
storm on every send.
|
||||
|
||||
---
|
||||
|
||||
## Migration from config.toml
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: import-conversation-history
|
||||
description: Use this skill when the user wants to import or migrate conversation history from another LLM chat or coding tool (e.g. ChatGPT, Claude.ai, Cursor, Copilot Chat, Aider, Gemini, a custom JSON export) into Turnstone. The skill teaches Turnstone's destination contracts — workstream identity, the OpenAI-shaped message rows, tool-call/result pairing, provider-fidelity blobs, attachments, and archive-vs-resumable choice — so the agent can map any source format onto them. Trigger phrases: "import my chats", "migrate this transcript into Turnstone", "bring my Claude.ai history over", "load this export as a workstream".
|
||||
version: 1.1.0
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Importing Conversation History into Turnstone
|
||||
@@ -12,7 +12,7 @@ Source formats vary; the destination does not. Your job is to translate whatever
|
||||
|
||||
Two questions to settle with the user before writing anything:
|
||||
|
||||
1. **Archive or resumable?** An archive is left closed and is read-only history. A resumable import is also kept closed and unloaded while rows are written, then explicitly opened after validation; this only works cleanly when the source LLM matches a Turnstone-supported provider/model and tool definitions still resolve.
|
||||
1. **Archive or resumable?** An archive ("saved" workstream — `state="closed"`) is read-only history. A resumable workstream (`state="idle"`) lets the user continue the conversation; this only works cleanly when the source LLM matches a Turnstone-supported provider/model and tool definitions still resolve.
|
||||
2. **One workstream per source thread, or merge?** Default to one-to-one unless the user explicitly asks to merge.
|
||||
|
||||
Default to **archive** when in doubt — resuming a foreign transcript with mismatched tool schemas or stale provider signatures will fail at the next turn.
|
||||
@@ -25,13 +25,13 @@ Two tables carry the conversation:
|
||||
|
||||
| Column | Required | Notes |
|
||||
|---|---|---|
|
||||
| `ws_id` | yes | 32-char lowercase hex. Auto-generate with `secrets.token_hex(16)` if you don't already have one. The router hashes the **full ID** — see "Identity & Routing" below. |
|
||||
| `ws_id` | yes | 32-char lowercase hex. Auto-generate with `secrets.token_hex(16)` if you don't already have one. **First 4 hex chars are the routing bucket** — see "Identity & Routing" below. |
|
||||
| `name` | yes | Short title. Pull from source thread title; fall back to first ~60 chars of first user message. |
|
||||
| `state` | yes | Register as `"closed"` while importing. Leave it closed for an archive; explicitly open it after commit for a resumable import. Never set `"running"` or `"creating"` directly. |
|
||||
| `state` | yes | `"closed"` for archive, `"idle"` for resumable. Never set `"running"` on import. |
|
||||
| `kind` | yes | `"interactive"` for normal threads. Do NOT use `"coordinator"` for imports — that's reserved for cluster-spawned coordinator workstreams. |
|
||||
| `parent_ws_id` | no | Leave NULL. Only set if you're importing a coordinator-spawned subtree and re-parenting it; rare. |
|
||||
| `user_id` | yes | Owner. Must exist in `users`; importer must know which Turnstone user owns the imported history. |
|
||||
| `node_id` | no | Nullable creation-time service/liveness hint. It is not the routing key or durable owner and may become stale after membership changes. Let a routed create stamp it; a direct shared-storage import may leave it NULL. |
|
||||
| `node_id` | yes (multi-node) | Denormalized cache of the node that owns this `ws_id`'s bucket. Single-node deployments can leave it NULL or set it to the only node. |
|
||||
| `alias` | no | Human-typeable short name. Optional; must be unique cluster-wide if set. |
|
||||
| `title` | no | Auto-titled later by the LLM; safe to leave NULL on import. |
|
||||
| `skill_id`, `skill_version` | yes | Default `""` and `0` unless the source thread was scoped to a Turnstone skill. |
|
||||
@@ -55,65 +55,25 @@ The internal format is **OpenAI-shaped**, even when the source was Anthropic or
|
||||
## Identity & Routing (`ws_id`)
|
||||
|
||||
- `ws_id` is **32-char lowercase hex** (i.e. `secrets.token_hex(16)`).
|
||||
- Ordinary placement is rendezvous (Highest Random Weight, HRW) selection over
|
||||
the **full `ws_id`** and the current live server set. For each node, Turnstone
|
||||
computes 32-bit FNV-1a over the node ID, a NUL separator, and the full
|
||||
workstream ID; it then applies the node weight and selects the highest score.
|
||||
A live per-workstream override takes precedence.
|
||||
- The live set comes from recent `services` heartbeats. Placement can therefore
|
||||
change when nodes join, leave, change weight, or an override changes. There
|
||||
is no stable prefix-derived placement to pre-compute or persist.
|
||||
- `workstreams.node_id` is stamped at creation and is not updated as HRW
|
||||
placement changes. It supports display and liveness-safe cleanup; the console
|
||||
router does not use it as the ordinary ownership decision.
|
||||
- For multi-node imports, create through the console routing proxy when the
|
||||
lifecycle must be published, or write the history once through the cluster's
|
||||
configured **shared storage backend**. Never partition rows across node-local
|
||||
databases by ID prefix or by a one-time HRW result: a later membership change
|
||||
can route the same full ID to another node.
|
||||
- For single-node imports, HRW placement is degenerate; any valid `ws_id` works.
|
||||
- The **routing bucket** is `int(ws_id[:4], 16)` — the first 4 hex chars place this workstream on a specific node via the consistent hash ring.
|
||||
- For multi-node imports: either insert through the console's routing proxy (which forwards to the owning node), or generate `ws_id`s and write directly to each node's database in batches grouped by bucket.
|
||||
- For single-node imports: bucket math is irrelevant; any `ws_id` works.
|
||||
- **Do not reuse the source platform's IDs as `ws_id`** unless they happen to be 32-char hex. Generate fresh; if you need the old ID for traceability, store it in `workstream_config` under a key like `import.source_id`.
|
||||
|
||||
## Recommended Import Path
|
||||
|
||||
Three options, in order of preference:
|
||||
|
||||
### 1. Quiesced storage import (recommended for full history)
|
||||
### 1. Storage protocol (recommended for full history)
|
||||
|
||||
Use the current `turnstone.core.storage.StorageBackend` protocol against the
|
||||
same shared backend as the cluster. The destination must remain absent from all
|
||||
in-memory session managers while rows are changing: a loaded `ChatSession`
|
||||
holds its own trajectory and will not observe conversation rows inserted behind
|
||||
it.
|
||||
|
||||
The safe sequence is:
|
||||
|
||||
1. Normalize and validate the complete source transcript before writing.
|
||||
2. Call `register_workstream(..., state="closed")` and require a `True` return;
|
||||
`False` means the caller-selected ID already exists, so abort rather than
|
||||
appending to an unrelated workstream.
|
||||
3. Insert the ordered conversation rows and attachment references.
|
||||
4. Load the saved rows back and run the validation checklist below.
|
||||
5. Leave an archive closed. For a resumable import, only now invoke the normal
|
||||
`POST /v1/api/workstreams/{ws_id}/open` endpoint on the currently routed
|
||||
node so the session hydrates from the complete transcript.
|
||||
|
||||
Do **not** create the destination through the web/SDK create endpoint before a
|
||||
direct bulk import. Create publishes an empty live session. If that already
|
||||
happened, close the workstream and confirm the manager-authoritative live probe
|
||||
returns false before writing, then explicitly open it again after validation.
|
||||
|
||||
For attachment-free history, `save_messages_bulk(rows)` is the canonical
|
||||
single-transaction insert primitive and bypasses the LLM round-trip entirely.
|
||||
New attachment bytes require the per-row path described under
|
||||
[Attachments](#attachments).
|
||||
Use `turnstone.core.storage.Storage.save_messages_bulk(rows)`. This is the canonical bulk-insert primitive and bypasses the LLM round-trip entirely.
|
||||
|
||||
```python
|
||||
from turnstone.core.storage import get_storage # initialized by the host/import entry point
|
||||
from turnstone.core.storage import get_storage # construct via the same path the server uses
|
||||
|
||||
storage = get_storage()
|
||||
storage = get_storage(...) # see turnstone.core.storage.__init__ for the project's wiring
|
||||
|
||||
inserted = storage.register_workstream(
|
||||
storage.create_workstream( # or whatever the project's exposed creator is — check turnstone/core/storage/_protocol.py
|
||||
ws_id=ws_id,
|
||||
user_id=user_id,
|
||||
name=name,
|
||||
@@ -121,8 +81,6 @@ inserted = storage.register_workstream(
|
||||
kind="interactive",
|
||||
...
|
||||
)
|
||||
if not inserted:
|
||||
raise RuntimeError(f"destination already exists: {ws_id}")
|
||||
|
||||
storage.save_messages_bulk([
|
||||
{"ws_id": ws_id, "role": "user", "content": "Hello"},
|
||||
@@ -136,19 +94,7 @@ storage.save_messages_bulk([
|
||||
])
|
||||
```
|
||||
|
||||
`save_messages_bulk` handles `timestamp` and the workstream's `updated` column
|
||||
internally, so you don't need to compute them per row. Verify the exact
|
||||
`register_workstream` and message signatures in
|
||||
`turnstone/core/storage/_protocol.py`; the Storage protocol, not the physical
|
||||
table layout, is the source of truth.
|
||||
|
||||
**Multi-node note:** this path assumes `get_storage()` is connected to the
|
||||
cluster's shared backend. Do not open a node-local database selected from the
|
||||
current HRW result, and do not pre-create a live session through the console
|
||||
routing proxy. After the shared-storage import commits, resolve the current
|
||||
route and open the closed workstream on that node. Any stored `node_id`
|
||||
describes creation-time placement, not a permanent shard that should receive a
|
||||
separate copy.
|
||||
`save_messages_bulk` handles `timestamp` and the workstream's `updated` column internally, so you don't need to compute them per row. **Verify the exact creator signature** by reading `turnstone/core/storage/_protocol.py` — table layout has shifted across migrations and the Storage protocol is the source of truth.
|
||||
|
||||
### 2. SDK `create_workstream(resume_ws=...)` (when the source is already a Turnstone workstream)
|
||||
|
||||
@@ -235,48 +181,27 @@ If the source thread had image or file attachments:
|
||||
|
||||
- **Size limits**: images ≤ 4 MiB, text documents ≤ 512 KiB. Reject or downsample anything bigger.
|
||||
- **Allowed types**: server validates magic bytes for images and UTF-8-decodes for text. Binary blobs that aren't images won't pass.
|
||||
- **Blob identity**: `attachment_id` is the lowercase SHA-256 hex digest of the
|
||||
bytes. `workstream_attachments` stores that content-addressed blob and its
|
||||
refcount; it has no workstream or message foreign key.
|
||||
- **Message link**: the sole message-to-blob link is the ordered JSON ID list in
|
||||
`conversations.attachments`.
|
||||
- **No persisted staging lifecycle**: pending upload bytes live only in a
|
||||
node's in-memory attachment buffer. The old persisted
|
||||
`pending → reserved → consumed` lifecycle does not apply to storage imports.
|
||||
- **Lifecycle**: pending → reserved → consumed. For imports, the cleanest path is to upload as pending and immediately consume by attaching to the relevant `conversations.id`.
|
||||
|
||||
For new attachment bytes, preserve row order by calling `save_message()` for
|
||||
each turn. It returns the `conversations.id`; for every attachment referenced by
|
||||
that turn, call `save_attachment()` with its content hash and bytes, then call
|
||||
`set_message_attachments(ws_id, message_id, ordered_ids)`. Each
|
||||
`save_attachment()` call accounts for one reference, while
|
||||
`set_message_attachments()` records the ordered link.
|
||||
Two import paths:
|
||||
|
||||
`save_messages_bulk(..., attachment_ids=[...])` is appropriate only when those
|
||||
content-addressed blobs already exist: the bulk transaction retains their
|
||||
references and writes the ordered lists. Do not first call `save_attachment()`
|
||||
for a new reference and then pass the same reference to `save_messages_bulk()`;
|
||||
both paths retain it and would double-count the refcount.
|
||||
1. **Bulk-insert + post-attach**: insert messages first, get back the assistant/user `conversations.id`, then write `workstream_attachments` rows linking the file to `message_id`.
|
||||
2. **SDK multipart create**: `create_workstream(attachments=[...], initial_message=...)` for the *first* turn only — the server reserves and consumes them onto that turn. Doesn't help for mid-thread attachments.
|
||||
|
||||
SDK multipart create remains useful only for attachments on a new first turn;
|
||||
it publishes a live session and is not the full-history import path.
|
||||
For full-history imports with multiple attachments at different turns, path (1) is the only option.
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Before declaring success, verify:
|
||||
|
||||
- [ ] `ws_id` is 32-char lowercase hex.
|
||||
- [ ] The workstream remained closed and absent from every live manager while rows were written; archives stay closed and resumable imports are opened only after validation.
|
||||
- [ ] `workstreams` row exists with the right `user_id` and `kind`.
|
||||
- [ ] `workstreams` row exists with the right `user_id`, `state`, `kind`.
|
||||
- [ ] Conversation rows are inserted **in order** (autoincrement `id` will reflect insert order).
|
||||
- [ ] Every assistant `tool_calls[].id` has a matching `role="tool"` row with the same `tool_call_id`.
|
||||
- [ ] `tool_calls[].function.arguments` is a JSON-encoded **string**, not a parsed object.
|
||||
- [ ] First message is typically `role="user"` (not `system`) — Turnstone composes its own system prompt at runtime.
|
||||
- [ ] No empty assistant rows (`content=NULL` AND `tool_calls=NULL` is invalid).
|
||||
- [ ] Every attachment ID is the SHA-256 of its stored bytes; each turn's ordered IDs are in `conversations.attachments`, and blob refcounts match message references.
|
||||
- [ ] If multi-node: the row is in shared storage and the node selected by
|
||||
`ConsoleRouter.route(ws_id)` from the current live set can load it.
|
||||
`workstreams.node_id`, when present, is treated as a creation-time hint rather
|
||||
than asserted equal to the current HRW result.
|
||||
- [ ] If multi-node: the `ws_id`'s bucket maps to a node that exists; `workstreams.node_id` matches.
|
||||
- [ ] Round-trip test: run `Storage.load_messages(ws_id)` and confirm the reconstructed list matches what you inserted (modulo timestamps).
|
||||
|
||||
## Anti-patterns
|
||||
@@ -286,20 +211,15 @@ Before declaring success, verify:
|
||||
- **Don't fabricate `tool_call_id`s without re-pairing.** Mismatched ids silently break the replay chain on the next turn.
|
||||
- **Don't skip the `tool_name` field on `role="tool"` rows.** Some load paths use it for display and audit; NULL there will render as "unknown tool".
|
||||
- **Don't write through the LLM (`send()` per turn) for full history.** It's expensive, rewrites assistant turns, and rate-limits will bite long imports.
|
||||
- **Don't shard imported rows by an ID prefix or a one-time HRW result.** HRW
|
||||
uses the full ID and live membership; placement may move. In a cluster, write
|
||||
one copy to shared storage and let request routing select the live node.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Path |
|
||||
|---|---|
|
||||
| Generate ws_id | `secrets.token_hex(16)` |
|
||||
| Multi-node placement | Full-ID 32-bit FNV-1a HRW over live servers; store rows once in shared storage |
|
||||
| Bulk insert attachment-free messages | `Storage.save_messages_bulk(rows)` |
|
||||
| Attach new bytes | `save_message()` → `save_attachment()` per reference → `set_message_attachments()` |
|
||||
| Bulk insert messages | `Storage.save_messages_bulk(rows)` |
|
||||
| Archive (read-only) | `state="closed"`, skip `provider_data` |
|
||||
| Resumable | Register closed, import and validate while unloaded, then explicitly open; populate `provider_data` if same provider |
|
||||
| Resumable | `state="idle"`, populate `provider_data` if same provider |
|
||||
| Tool call id | OpenAI shape: `{"id": ..., "type": "function", "function": {"name": ..., "arguments": "<json string>"}}` |
|
||||
| Tool result row | `role="tool"`, `tool_name`, `tool_call_id`, `content` |
|
||||
| Source role → Turnstone role | See "Role Mapping" table |
|
||||
@@ -308,8 +228,6 @@ Before declaring success, verify:
|
||||
## Files to read before writing the importer
|
||||
|
||||
- `turnstone/core/storage/_schema.py` — authoritative table definitions.
|
||||
- `turnstone/core/storage/_protocol.py` — `register_workstream`, message, attachment, and load signatures.
|
||||
- `turnstone/core/rendezvous.py` — authoritative full-ID FNV-1a HRW scoring.
|
||||
- `turnstone/console/router.py` — live-node discovery, override precedence, and routing behavior.
|
||||
- `turnstone/core/storage/_protocol.py` — `save_message`, `save_messages_bulk`, `load_messages` signatures.
|
||||
- `turnstone/core/session.py` (around the message-save section) — how the runtime constructs in-memory message dicts; mirror this shape on import to round-trip cleanly.
|
||||
- `turnstone/api/server_schemas.py` — Pydantic shapes for the SDK paths if you go through HTTP.
|
||||
|
||||
+17
-65
@@ -54,11 +54,15 @@ docker compose exec caddy \
|
||||
cat /data/caddy/pki/authorities/local/root.crt # import into your OS/browser
|
||||
```
|
||||
|
||||
**Can Caddy get its cert from the console's internal CA instead?** Not directly.
|
||||
The console's ACME signing routes require Turnstone's rotating enrollment JWT,
|
||||
which a standard Caddy ACME issuer does not attach. Keep `tls internal`, or use a
|
||||
public ACME CA for a publicly trusted certificate. An authenticated gateway or
|
||||
Caddy plugin would be required to use Turnstone's responder.
|
||||
**Can Caddy get its cert from the console's internal CA instead?** Technically
|
||||
yes — the console exposes a real ACME directory (`/acme/directory`) with
|
||||
auto-approval, so Caddy's `tls { ca http://console:8090/acme/directory }` would
|
||||
mint a cert for any name. It's not recommended as the default: lacme's ACME
|
||||
responder is built for turnstone's own client (interop with Caddy's client is
|
||||
unverified), it couples Caddy startup to the console, and the browser must trust
|
||||
a private CA either way — so it buys nothing over `tls internal`. For a publicly
|
||||
trusted cert (no warning), point Caddy at Let's Encrypt with a real domain
|
||||
instead.
|
||||
|
||||
---
|
||||
|
||||
@@ -102,15 +106,13 @@ An mTLS listener rejects plain-HTTP probes at the socket, so
|
||||
it presents the node's own cert as the client cert and pins the cluster
|
||||
CA, using the PEM files the server writes at boot under
|
||||
`$TURNSTONE_TLS_PEM_DIR` (default `<tmpdir>/turnstone-tls`). The probe
|
||||
dials `localhost` for the TLS attempt, which every service certificate carries
|
||||
as a DNS SAN. Cert renewal rewrites
|
||||
dials `localhost` for the TLS attempt — the internal CA issues DNS SANs
|
||||
only, so a literal-IP URL would fail verification. Cert renewal rewrites
|
||||
the PEM dir alongside the live listener swap, so the probe's client cert
|
||||
never outlives the served cert. With TLS disabled the plain probe succeeds
|
||||
and the PEM directory is never consulted. On bare metal with multiple
|
||||
nodes per host, set `TURNSTONE_TLS_PEM_DIR` per node (each boot clears
|
||||
stale `lacme-pem-*` dirs under its root).
|
||||
The production TLS Compose overlay inherits this healthcheck from the base
|
||||
service; it remains enabled under mTLS.
|
||||
|
||||
---
|
||||
|
||||
@@ -123,13 +125,6 @@ service; it remains enabled under mTLS.
|
||||
| `tls.enabled` | `false` | Master switch for internal mTLS |
|
||||
| `tls.acme_directory` | `""` | External ACME CA URL for console frontend cert |
|
||||
|
||||
### ACME topology environment
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `TURNSTONE_ACME_EXTERNAL_URL` | request-derived | Canonical externally reachable responder base, including `/acme` (for example `http://192.0.2.1:8090/acme`). Set it on the console so advertised URLs are routable and on in-cluster clients so their enrollment JWT is allowed only at that configured destination. A public path prefix is valid only when a reverse proxy maps it to Turnstone's internal `/acme` mount. |
|
||||
| `TURNSTONE_CONSOLE_HTTP_BIND` | `127.0.0.1` | Production TLS-overlay bind for the console's plain-HTTP bootstrap/API port. For cross-host enrollment, use a trusted LAN/VPN interface and firewall it to enrolling nodes. |
|
||||
|
||||
### Bootstrap Config (config.toml)
|
||||
|
||||
These are needed before storage is available:
|
||||
@@ -149,7 +144,7 @@ sslkey = "" # path to client key
|
||||
| CA common name | "Turnstone CA" | |
|
||||
| CA validity | 10 years | |
|
||||
| Cert validity | 48 hours | Short-lived, auto-renewed |
|
||||
| Renewal interval | 12 hours | Leaves retry headroom before expiry |
|
||||
| Renewal interval | 24 hours | Half of validity |
|
||||
| ACME auto-approve | true | Internal network, no challenge validation |
|
||||
|
||||
---
|
||||
@@ -182,14 +177,10 @@ turnstone-admin tls-ca-cert --out ca.pem --console-url http://console:8080
|
||||
# Request a cert for a domain
|
||||
turnstone-admin tls-issue worker-1.internal --out /certs --console-url http://console:8080
|
||||
|
||||
# List managed cluster certs
|
||||
# List issued certs
|
||||
turnstone-admin tls-list --console-url http://console:8080
|
||||
```
|
||||
|
||||
`tls-ca-cert` preserves the supplied scheme. An `https://` console URL is
|
||||
verified with the system trust store; an explicitly supplied `http://` URL is
|
||||
TOFU and prints a fingerprint that must be checked out of band.
|
||||
|
||||
### Console URL Discovery
|
||||
|
||||
If `--console-url` is not provided, the CLI discovers it from the `services`
|
||||
@@ -202,9 +193,7 @@ table in the shared database. The console registers itself on startup.
|
||||
The **TLS** tab in the console admin panel (System group) shows:
|
||||
- CA status (common name, certificate count)
|
||||
- Certificate table (domain, SANs, issued, expires)
|
||||
- Force-renew for the console-owned internal identity; remote nodes renew and
|
||||
hot-reload their own keys
|
||||
- Delete for expired, remotely managed certificate rows
|
||||
- Force-renew and delete actions per certificate
|
||||
|
||||
---
|
||||
|
||||
@@ -259,15 +248,8 @@ const client = new TurnstoneServer({
|
||||
`TURNSTONE_CONSOLE_URL` (a bare-metal node outside the compose network can't
|
||||
resolve the in-cluster `console` name, so it points this at the console's
|
||||
published ACME endpoint)
|
||||
3. Fetches the CA root from the configured console scheme. Direct deployments
|
||||
use `http://console/acme/ca.pem` (plain HTTP, TOFU); an explicitly configured
|
||||
HTTPS proxy is preserved and verified with the system trust store.
|
||||
4. Requests a service cert via ACME with a dedicated, short-lived Turnstone
|
||||
service JWT pinned to configured responder origins. lacme emits ACME JWS
|
||||
messages, but its lightweight responder deliberately does not validate their
|
||||
signatures or nonces; the service JWT is the enrollment authorization gate.
|
||||
Direct HTTP bootstrap therefore still requires a trusted LAN/VPN (or an
|
||||
independently trusted HTTPS proxy). The cert's
|
||||
3. Fetches CA root cert from `http://console/acme/ca.pem` (plain HTTP, TOFU)
|
||||
4. Requests a service cert via ACME (plain HTTP, JWS-signed). The cert's
|
||||
primary domain / SAN is the node's **advertised host** (the host of
|
||||
`TURNSTONE_ADVERTISE_URL`, e.g. `node-1`) — the name peers actually dial,
|
||||
not the container hostname. This makes mTLS hostname verification succeed
|
||||
@@ -282,12 +264,7 @@ const client = new TurnstoneServer({
|
||||
|
||||
1. Read `tls.enabled` from ConfigStore
|
||||
2. Initialize CA (load from DB or generate new root key)
|
||||
3. Mount ACME responder at `/acme` (serves `/ca.pem` natively). When
|
||||
`TURNSTONE_ACME_EXTERNAL_URL` is set, use it for every advertised directory,
|
||||
order, authorization, and certificate URL; otherwise derive URLs from each
|
||||
request as before. Directory, nonce, and CA bootstrap resources stay public;
|
||||
account/order/challenge/finalization/certificate routes require the dedicated
|
||||
enrollment service JWT.
|
||||
3. Mount ACME responder at `/acme` (serves `/ca.pem` natively)
|
||||
4. Issue console certs (internal + optional frontend)
|
||||
5. Start CA-direct auto-renewal (no network, signs directly), scoped to the
|
||||
console's own cert, plus a periodic GC that reclaims cert rows for
|
||||
@@ -313,15 +290,6 @@ fronted under a second hostname). Symptom if this is wrong: the console
|
||||
dashboard shows nodes as unreachable and `openssl s_client` reports the served
|
||||
cert's SANs don't include the dialed name.
|
||||
|
||||
The advertised host and extra SANs may be DNS names or literal IPv4/IPv6
|
||||
addresses. Turnstone converts IP literals to typed ACME identifiers so the
|
||||
certificate contains `IPAddress` SANs that normal IP hostname verification can
|
||||
use; DNS spelling is preserved. Bracket an IPv6 address when it appears in a URL
|
||||
(for example `TURNSTONE_ADVERTISE_URL=http://[2001:db8::10]:8080`), but use the
|
||||
bare address in `TURNSTONE_TLS_SANS`. Unspecified bind addresses (`0.0.0.0` and
|
||||
`::`) and scoped IPv6 addresses such as `fe80::1%eth0` are not certificate
|
||||
identities. Restart after changing the advertised identity or extra SANs.
|
||||
|
||||
### "No console service found"
|
||||
|
||||
The console registers itself in the `services` table on startup. If the console
|
||||
@@ -329,22 +297,6 @@ hasn't started or the registration expired (1 hour TTL), nodes can't discover
|
||||
it. Set `TURNSTONE_CONSOLE_URL` to a reachable console address (this is also how
|
||||
a bare-metal node that can't resolve the in-cluster `console` name enrolls).
|
||||
|
||||
### Cross-host ACME links point at the container
|
||||
|
||||
For a node on another host, publish port 8090 on a reachable interface and set
|
||||
`TURNSTONE_ACME_EXTERNAL_URL` on the console **and in-cluster nodes** to that full
|
||||
responder base, including `/acme` (for example
|
||||
`http://192.0.2.1:8090/acme`). The console advertises it; clients use it as a
|
||||
trusted enrollment-token destination. Keep
|
||||
`TURNSTONE_CONSOLE_URL=http://console:8090` for in-cluster service discovery.
|
||||
A remote node whose `TURNSTONE_CONSOLE_URL` already names the public origin can
|
||||
derive the same `/acme` base, but setting both values explicitly avoids drift.
|
||||
|
||||
Bind only a trusted LAN/VPN interface and firewall it to enrolling nodes. The
|
||||
JWT authenticates the client, but a direct plain-HTTP bootstrap remains TOFU and
|
||||
does not resist an active on-path attacker. If the network is untrusted, expose
|
||||
the responder through an independently trusted HTTPS proxy instead.
|
||||
|
||||
### Browser HTTPS to the console
|
||||
|
||||
The console serves plain HTTP (it's the ACME bootstrap endpoint — see
|
||||
|
||||
+36
-141
@@ -1,10 +1,9 @@
|
||||
# Tools Reference
|
||||
|
||||
Turnstone exposes a role-specific built-in tool surface plus any configured MCP
|
||||
tools through provider-native or OpenAI-compatible function calling. Built-in
|
||||
schemas live under `turnstone/tools/` and are loaded by
|
||||
`turnstone/core/tools.py`; metadata selects the interactive, coordinator, and
|
||||
task-agent subsets. MCP tools are discovered from configured servers by
|
||||
turnstone exposes 16 built-in tools plus any number of external MCP tools to the
|
||||
LLM via the OpenAI function-calling interface. Built-in tools are defined as JSON
|
||||
files under `turnstone/tools/` and loaded at startup by `turnstone/core/tools.py`.
|
||||
MCP tools are discovered from configured MCP servers at startup by
|
||||
`turnstone/core/mcp_client.py`.
|
||||
|
||||
---
|
||||
@@ -29,19 +28,13 @@ schema plus turnstone-specific metadata keys:
|
||||
}
|
||||
```
|
||||
|
||||
**Metadata keys** (stripped before sending the schema to the model; the full
|
||||
set lives in `_META_KEYS` in `turnstone/core/tools.py`):
|
||||
**Metadata keys** (stripped before sending the schema to the model):
|
||||
|
||||
| Key | Type | Meaning |
|
||||
|------------------|------|---------|
|
||||
| `task_agent` | bool | Tool is available to task sub-agents. |
|
||||
| `coordinator` | bool | Tool is available to coordinator sessions. Without `interactive: true` alongside it, this reads as coord-only and the tool is stripped from interactive sessions. |
|
||||
| `interactive` | bool | Opt a `coordinator: true` tool back into interactive sessions (dual-kind tools like `memory`). |
|
||||
| `auto_approve` | bool | Tool runs without user confirmation (read-only, safe operations). |
|
||||
| `primary_key` | str | When the model sends a bare string instead of JSON args, map it to this parameter name. |
|
||||
| `kind_variants` | dict | Per-kind description / parameter-schema overlays so each session kind sees only the surface it can use (see `memory.json`). |
|
||||
| `cwd_note` | str | Sentence appended to the description at session build time with `{working_dir}` substituted — declare on tools whose semantics depend on the process working directory (see `bash.json`, `apply_cwd_context`). |
|
||||
| `workspace_note` | str | Companion sentence naming the operator-configured workspace directory, `{workspace_dir}` substituted; dropped when no workspace is configured. |
|
||||
| Key | Type | Meaning |
|
||||
|----------------|------|---------|
|
||||
| `task_agent` | bool | Tool is available to task sub-agents. |
|
||||
| `auto_approve` | bool | Tool runs without user confirmation (read-only, safe operations). |
|
||||
| `primary_key` | str | When the model sends a bare string instead of JSON args, map it to this parameter name. |
|
||||
|
||||
---
|
||||
|
||||
@@ -51,10 +44,10 @@ set lives in `_META_KEYS` in `turnstone/core/tools.py`):
|
||||
|
||||
| Name | Description |
|
||||
|---------------------|-------------|
|
||||
| `TOOLS` | The complete loaded built-in union. Sessions send a kind-specific subset (`INTERACTIVE_TOOLS` or `COORDINATOR_TOOLS`). |
|
||||
| `TOOLS` | All 28 loaded built-in tool definitions (interactive + coordinator union). Sessions send a kind-specific subset (`INTERACTIVE_TOOLS` or `COORDINATOR_TOOLS`). |
|
||||
| `TASK_AGENT_TOOLS` | Tools with `task_agent: true` -- available to task sub-agents. Includes write operations. |
|
||||
| `TASK_AUTO_TOOLS` | Set of all tool names with `auto_approve: true` -- used by task-agent sub-sessions to skip confirmation for matching available tools. |
|
||||
| `BUILTIN_TOOL_NAMES`| Frozenset of the built-in union. Used by tool search to distinguish built-ins from deferrable MCP tools. |
|
||||
| `BUILTIN_TOOL_NAMES`| Frozenset of all 28 built-in tool names (interactive + coordinator union). Used by tool search to distinguish always-on tools from deferrable MCP tools. |
|
||||
| `PRIMARY_KEY_MAP` | Dict mapping tool name to its `primary_key` parameter name. |
|
||||
|
||||
---
|
||||
@@ -63,10 +56,7 @@ set lives in `_META_KEYS` in `turnstone/core/tools.py`):
|
||||
|
||||
> See also: [Tool Pipeline diagram](diagrams/png/05-tool-pipeline.png)
|
||||
|
||||
Tool handling spans a four-phase pipeline. `ChatSession._execute_tools()` owns
|
||||
prepare, approval, and execution (phases 1–3); after it returns, the owning
|
||||
conversation loop guards the observed results and folds them into the
|
||||
trajectory (phase 4).
|
||||
Tool execution follows a three-phase pipeline inside `ChatSession._execute_tools()`:
|
||||
|
||||
### Phase 1: Prepare
|
||||
|
||||
@@ -75,8 +65,9 @@ trajectory (phase 4).
|
||||
- Parses the JSON arguments (with fallback for malformed JSON).
|
||||
- If JSON parsing fails entirely, uses `PRIMARY_KEY_MAP` to map a bare string
|
||||
to the correct parameter.
|
||||
- Dispatches to the matching `_prepare_{func_name}()` handler, the synthetic
|
||||
`tool_search` fallback, or the generic `_prepare_mcp_tool()` handler.
|
||||
- Dispatches to the matching `_prepare_{func_name}()` handler. There are 16
|
||||
built-in tools plus `tool_search` (synthetic, client-side BM25 fallback) and
|
||||
the generic `_prepare_mcp_tool()` handler for MCP tools.
|
||||
- Validates arguments and builds a preview dict containing:
|
||||
- `call_id`, `func_name`, `header`, `preview` (for display)
|
||||
- `needs_approval` (bool)
|
||||
@@ -85,10 +76,7 @@ trajectory (phase 4).
|
||||
|
||||
### Phase 2: Approve
|
||||
|
||||
Prepared items are sent to the UI via `ui.approve_tools(items)`. Several
|
||||
parallel task agents may leave independent `ApprovalCycle` objects pending on
|
||||
one workstream; each round owns a `cycle_id`, event, result, and verdict set.
|
||||
Remote clients resolve the exact round by `cycle_id` (or a member `call_id`).
|
||||
All prepared items are sent to the UI via `ui.approve_tools(items)`.
|
||||
|
||||
- The UI displays each tool's header and preview to the user.
|
||||
- Items where `needs_approval` is `False` (auto-approved tools) are shown
|
||||
@@ -100,10 +88,6 @@ Remote clients resolve the exact round by `cycle_id` (or a member `call_id`).
|
||||
prompt). This is per-tool, not blanket.
|
||||
- If `auto_approve` is `True` on the session (via `--skip-permissions` or workstream
|
||||
template), all tools are approved automatically.
|
||||
- When Smart Approvals are enabled, one immutable judge/settings snapshot is
|
||||
stamped onto the whole batch. The batch auto-approves only when every gated
|
||||
item has a qualifying verdict; partial or mixed qualification fails closed to
|
||||
the human prompt. Stop is linearized against that terminal decision.
|
||||
|
||||
### Phase 3: Execute
|
||||
|
||||
@@ -123,28 +107,6 @@ Each item's `execute` callable is invoked:
|
||||
denials are tracked separately. This removes the need for text-prefix heuristics.
|
||||
Other tools deliver results atomically via
|
||||
`ui.on_tool_result(call_id, name, output, is_error=...)` only.
|
||||
|
||||
Stop propagates to child model scopes, judges, tracked subprocess groups, and
|
||||
the approval cycles owned by the cancelled operation. Calls that definitely
|
||||
never started receive `EffectStatus.none`; an interrupted call whose external
|
||||
outcome was not observed receives `unknown`, `partial`, or `rolled_back` as
|
||||
appropriate. These typed receipts preserve effect truth across storage/replay
|
||||
without exposing unreviewed model output as a tool result.
|
||||
|
||||
### Phase 4: Guard and atomic fold
|
||||
|
||||
After `_execute_tools()` returns, the main `send()` loop compacts/truncates
|
||||
completed results to the remaining shared budget and then runs the heuristic
|
||||
and optional LLM output guard. The task-agent loop deliberately guards the
|
||||
observed raw output before applying its size cap, so truncation cannot hide a
|
||||
sensitive result from that check.
|
||||
|
||||
After guard work, the owning loop rechecks generation ownership. On the main
|
||||
conversation path, one generation-fenced commit appends the complete
|
||||
tool-result block, advisories, feedback, and queued user turns; its durable
|
||||
records run in FIFO order outside the lifecycle lock. A force-cancelled
|
||||
predecessor can therefore finish external cleanup, but cannot fold late results
|
||||
into its successor's trajectory.
|
||||
---
|
||||
|
||||
## Tool Approval Flow
|
||||
@@ -152,7 +114,7 @@ into its successor's trajectory.
|
||||
**Auto-approved** (no user confirmation needed at runtime):
|
||||
- `read_file` -- reads files, no side effects
|
||||
- `search` -- grep-style search, no side effects
|
||||
- `memory` -- structured persistent memory (save/get/search/delete/list)
|
||||
- `memory` -- structured persistent memory (save/search/delete/list)
|
||||
- `recall` -- searches conversation history
|
||||
- `notify` -- sends notifications to linked channels (time-sensitive, auto-approved for urgency)
|
||||
|
||||
@@ -163,9 +125,6 @@ into its successor's trajectory.
|
||||
- `web_fetch` -- fetches a URL (SSRF-protected, but makes network requests)
|
||||
- `web_search` -- web search via self-hosted SearxNG (makes network requests)
|
||||
- `task_agent` -- spawns an autonomous sub-agent
|
||||
- `open_preview` -- **URL targets only** (network access, gated like `web_fetch`);
|
||||
file-path and `attachment:` targets are local reads and run unprompted like
|
||||
`read_file`
|
||||
|
||||
Note: The JSON schema metadata key `auto_approve` controls membership in
|
||||
`TASK_AUTO_TOOLS` (used for task agent sub-sessions). The actual runtime
|
||||
@@ -198,7 +157,6 @@ Every tool defines a `primary_key`. The mapping is:
|
||||
| `search` | `query` |
|
||||
| `web_fetch` | `url` |
|
||||
| `web_search` | `query` |
|
||||
| `open_preview` | `target` |
|
||||
| `task_agent` | `prompt` |
|
||||
| `memory` | `name` |
|
||||
| `recall` | `query` |
|
||||
@@ -327,7 +285,7 @@ Fetch a URL and extract specific information from it.
|
||||
| `url` | string | yes | The URL to fetch (must start with `http://` or `https://`). |
|
||||
| `question` | string | yes | What to extract or answer from the page content. |
|
||||
|
||||
- **What it does**: Fetches the URL, strips HTML to plain text, and uses the LLM to extract the answer to the question from the page content. Every redirect hop is SSRF-screened before it is requested. Private/internal addresses are refused by default; enable `tools.allow_private_network` (console Settings → Tools) to make them approvable for self-hosted setups whose services live on the local network — the approval prompt marks such requests, and a public site redirecting into private space is refused regardless. Cloud metadata endpoints and link-local, multicast and reserved addresses are refused even with the opt-in enabled, including as a redirect target from a private address you approved. An address is judged by what it actually reaches, so an IPv6 transition address (NAT64, 6to4, Teredo) wrapping an internal IPv4 is treated exactly as that IPv4 would be.
|
||||
- **What it does**: Fetches the URL, strips HTML to plain text, and uses the LLM to extract the answer to the question from the page content. Protected against SSRF (blocks private/internal IPs).
|
||||
- **Auto-approve**: No -- requires user confirmation (makes network requests).
|
||||
- **Agent availability**: `task_agent`.
|
||||
|
||||
@@ -387,39 +345,6 @@ It reports the score scale, whether the endpoint cleanly separates relevant from
|
||||
|
||||
---
|
||||
|
||||
### open_preview
|
||||
|
||||
Show the user rich content in a preview pane beside the conversation.
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|--------|----------|-------------|
|
||||
| `target` | string | yes | An http(s) URL, a file path, or `attachment:<id>` for a file attached to the conversation. |
|
||||
| `kind` | string | no | Rendering override: `web`, `pdf`, `image`, `table`, `text`, or `markdown`. Detected from the content when omitted. |
|
||||
| `title` | string | no | Pane header title. Defaults to the page title, filename, or URL. |
|
||||
|
||||
- **What it does**: Resolves the target to bytes (URLs fetch through the same
|
||||
SSRF-guarded path as `web_fetch`, screened per redirect hop, honoring the
|
||||
same `tools.allow_private_network` opt-in), classifies the
|
||||
content, stores it content-addressed against the workstream, and opens the
|
||||
frontend preview pane beside the conversation: web pages render in a fully
|
||||
sandboxed iframe (no scripts, opaque origin), PDFs in the browser viewer,
|
||||
images inline, CSV/TSV/JSON as a sortable table, text/markdown rendered. A
|
||||
previewed web page loads none of its remote images or styles by default, so
|
||||
opening it never reveals the viewer to the page's site; a toggle in the pane
|
||||
header turns remote content back on for that preview. The
|
||||
model receives only a one-line confirmation — to reason about content, use
|
||||
`web_fetch` / `read_file` instead. Preview content is size-capped per kind
|
||||
(pages 4 MB, PDFs 32 MB, images 4 MB, tables 2 MB, text 512 KB) and GC'd
|
||||
with the workstream.
|
||||
- **Auto-approve**: URL targets require confirmation (network access); file
|
||||
paths and `attachment:` targets run unprompted (local reads).
|
||||
- **Agent availability**: interactive sessions only (not `task_agent`, not
|
||||
coordinators).
|
||||
- **Surfaces**: the pane renders in the web UI (standalone and console). The
|
||||
CLI prints the confirmation line only — there is no terminal pane.
|
||||
|
||||
---
|
||||
|
||||
## Agent
|
||||
|
||||
The tool name uses the `_agent` suffix — bare `task` collides with
|
||||
@@ -433,7 +358,7 @@ Delegate a general-purpose task to an autonomous sub-agent.
|
||||
|-----------|--------|----------|-------------|
|
||||
| `prompt` | string | yes | Complete task description for the sub-agent. |
|
||||
|
||||
- **What it does**: Spawns a sub-agent that inherits the `TASK_AGENT_TOOLS` set (read, write, edit, search, bash, and web tools). The sub-agent runs autonomously to completion. Use for work that requires file modifications or command execution.
|
||||
- **What it does**: Spawns a sub-agent that inherits the `TASK_AGENT_TOOLS` set (read, write, edit, search, bash, web tools, memory tools). The sub-agent runs autonomously to completion. Use for work that requires file modifications or command execution.
|
||||
- **Auto-approve**: No -- requires user confirmation.
|
||||
- **Agent availability**: Top-level only.
|
||||
|
||||
@@ -447,26 +372,18 @@ Structured persistent memory across sessions with typed, scoped entries.
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|---------------|---------|----------|-------------|
|
||||
| `action` | string | yes | `save`, `get`, `search`, `delete`, or `list`. |
|
||||
| `name` | string | save/get/delete | Short snake_case identifier for the memory. |
|
||||
| `action` | string | yes | `save`, `search`, `delete`, or `list`. |
|
||||
| `name` | string | save/delete | Short snake_case identifier for the memory. |
|
||||
| `content` | string | save | Memory content to store. |
|
||||
| `description` | string | save | Non-empty description for relevance matching; required on create and update. |
|
||||
| `type` | string | no | Memory type: `user`, `general`, `feedback`, or `reference`. Default: `general`. |
|
||||
| `scope` | string | no | Memory scope: `global`, `workstream`, `user`, `coordinator`, or `project`. See defaults below. |
|
||||
| `description` | string | no | Short description for relevance matching (recommended for `save`). |
|
||||
| `type` | string | no | Memory type: `user`, `project`, `feedback`, or `reference`. Default: `project`. |
|
||||
| `scope` | string | no | Memory scope: `global`, `workstream`, or `user`. Default: `global`. |
|
||||
| `query` | string | search | Search query for finding memories. |
|
||||
| `limit` | integer | no | Max results for `search` or `list`. Default: 20. |
|
||||
|
||||
- **What it does**: Manages structured persistent memories in the database.
|
||||
Memories persist across sessions, have a type classification, and live in a
|
||||
role-specific visible scope. Unscoped `save`/`get`/`delete` resolve to one
|
||||
target: the attached active project, otherwise `global` for an interactive
|
||||
session or `coordinator` for a coordinator. Read-only project access permits
|
||||
`get` but makes `save`/`delete` fail without falling back. A valid explicit
|
||||
scope selects exactly that scope. Unscoped `search`/`list` cover all visible
|
||||
scopes; use the displayed scope when following a result with `get` or
|
||||
`delete`.
|
||||
- **What it does**: Manages structured persistent memories in the database. Memories persist across sessions, have a type classification (user preferences, project knowledge, feedback, reference material) and a scope (global across all workstreams, private to a workstream, or following a user). Relevant memories are included in the system prompt on startup.
|
||||
- **Auto-approve**: Yes.
|
||||
- **Agent availability**: Not available to task agents.
|
||||
- **Agent availability**: Not available to sub-agents (top-level only).
|
||||
|
||||
---
|
||||
|
||||
@@ -481,7 +398,7 @@ Search conversation history for past messages and tool results.
|
||||
|
||||
- **What it does**: Searches conversation history across sessions using FTS5 full-text search. Returns matching messages, tool calls, and tool results with timestamps and workstream context.
|
||||
- **Auto-approve**: Yes.
|
||||
- **Agent availability**: Not available to task agents.
|
||||
- **Agent availability**: Not available to sub-agents (top-level only).
|
||||
|
||||
---
|
||||
|
||||
@@ -617,11 +534,7 @@ pre-configure skills at workstream creation.
|
||||
|
||||
---
|
||||
|
||||
## Interactive Tool Summary
|
||||
|
||||
This table describes the ordinary interactive surface. Coordinator sessions
|
||||
receive their delegation/lifecycle tools instead, and task agents receive the
|
||||
metadata-selected `TASK_AGENT_TOOLS` subset.
|
||||
## Summary Table
|
||||
|
||||
| Tool | Category | Auto-approve | task_agent | primary_key |
|
||||
|--------------|------------|--------------|------------|-------------|
|
||||
@@ -632,7 +545,6 @@ metadata-selected `TASK_AGENT_TOOLS` subset.
|
||||
| `search` | File Ops | Yes | Yes | `query` |
|
||||
| `web_fetch` | Info | No | Yes | `url` |
|
||||
| `web_search` | Info | No | Yes | `query` |
|
||||
| `open_preview`| Info | URL: no; path/attachment: yes | No | `target` |
|
||||
| `task_agent` | Agent | No | No | `prompt` |
|
||||
| `memory` | Memory | Yes | No | `name` |
|
||||
| `recall` | Memory | Yes | No | `query` |
|
||||
@@ -742,7 +654,7 @@ MCP-compatible service.
|
||||
3. **Schema conversion**: Each MCP tool's `inputSchema` is converted to OpenAI
|
||||
function-calling format. The tool name is prefixed: `mcp__{server}__{tool}`.
|
||||
|
||||
4. **Merging**: MCP tools are appended after the role's built-in tools via
|
||||
4. **Merging**: MCP tools are appended after the 16 built-in tools via
|
||||
`merge_mcp_tools()`. Built-in tools appear first, giving them natural LLM priority.
|
||||
When dynamic tool search is active, MCP tools are deferred rather than directly
|
||||
visible -- the model discovers them via search as needed (see
|
||||
@@ -829,10 +741,7 @@ MCP tool lists stay up-to-date without restart through two mechanisms:
|
||||
1. **Push notifications** -- MCP servers that declare `tools.listChanged: true` in
|
||||
their capabilities send `notifications/tools/list_changed` when their tool list
|
||||
changes. `MCPClientManager` registers a `message_handler` on each `ClientSession`
|
||||
that triggers an immediate refresh for that server (debounced per server and
|
||||
notification kind, and run off the receive loop). A refresh that fails while
|
||||
the connection stays up is retried automatically on the next health-loop tick
|
||||
until one completes.
|
||||
that triggers an immediate refresh for that server.
|
||||
|
||||
2. **Manual** -- `/mcp refresh` re-fetches tools from all servers immediately.
|
||||
`/mcp refresh <server>` targets a single server. If a server has disconnected,
|
||||
@@ -840,10 +749,6 @@ MCP tool lists stay up-to-date without restart through two mechanisms:
|
||||
same controls (refresh / reconnect buttons per server) for cluster-wide
|
||||
fan-out.
|
||||
|
||||
Reconnects (health-loop, dispatch-driven, or operator-forced) always end in a
|
||||
full catalog rediscovery, so a server that changed its tools while disconnected
|
||||
comes back current.
|
||||
|
||||
When tools change, `MCPClientManager` rebuilds its merged tool list using copy-on-write
|
||||
(new list/dict objects assigned atomically) and notifies all active `ChatSession`
|
||||
instances via registered listener callbacks. Each session rebuilds its `_tools`,
|
||||
@@ -879,13 +784,6 @@ capabilities for the `resources` capability. For servers that declare it:
|
||||
2. `list_resource_templates` fetches URI templates (parameterized patterns like
|
||||
`db://tables/{table}/rows/{id}`).
|
||||
|
||||
The protocol advertises both lists through one aggregate `resources`
|
||||
capability, so a server may implement only one of them. If either request
|
||||
returns the JSON-RPC `Method not found` code (`-32601`), turnstone treats that
|
||||
half of the catalog as empty and keeps the other half; authentication,
|
||||
validation, transport, and all other discovery errors still fail the
|
||||
connection or refresh.
|
||||
|
||||
Both are stored as `{uri, name, description, mimeType, server}` dicts and
|
||||
merged into a unified catalog.
|
||||
|
||||
@@ -921,16 +819,13 @@ catalog.
|
||||
|
||||
### Refresh
|
||||
|
||||
Resource lists stay current through the same mechanisms as tool lists:
|
||||
Resource lists stay current through the same three-tier mechanism as tool lists:
|
||||
|
||||
1. **Push** -- Servers declaring `resources.listChanged: true` send
|
||||
`notifications/resources/list_changed`, triggering an immediate refresh
|
||||
(with the same failed-refresh retry on the health-loop tick).
|
||||
2. **Manual** -- `/mcp refresh` re-fetches resources alongside tools.
|
||||
|
||||
Servers without push support are refreshed whenever they reconnect (every
|
||||
reconnect ends in full rediscovery) or when an operator refreshes manually;
|
||||
there is no periodic polling.
|
||||
`notifications/resources/list_changed`, triggering an immediate refresh.
|
||||
2. **Periodic** -- Servers without push are polled on the configured refresh
|
||||
interval (default 4 hours, same timer as tools).
|
||||
3. **Manual** -- `/mcp refresh` re-fetches resources alongside tools.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+11
-20
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
||||
|
||||
[project]
|
||||
name = "turnstone"
|
||||
version = "1.8.0a7"
|
||||
version = "1.7.0"
|
||||
description = "Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."
|
||||
readme = "README.md"
|
||||
license = "Apache-2.0"
|
||||
@@ -23,14 +23,9 @@ classifiers = [
|
||||
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
||||
]
|
||||
dependencies = [
|
||||
# Version 3 moves the default transport to HTTPX2. Keep major upgrades
|
||||
# deliberate because the stream retry boundary depends on that contract.
|
||||
"openai>=3,<4",
|
||||
"anthropic>=0.117", # tracks the release current at claude-opus-5 onboarding; hard runtime floor is still 0.105 (mid-conversation system blocks) — Opus 5 itself needs no new SDK surface (model ids are opaque strings; "refusal" has been in the StopReason literal since ~0.95). Raise this when adopting fast mode / server-side fallbacks / advisor / mid-conversation tool changes, which DO need newer typed params.
|
||||
"openai>=2.37",
|
||||
"anthropic>=0.108", # claude-fable-5 support; hard runtime floor is 0.105 (mid-conversation system blocks)
|
||||
"httpx>=0.28",
|
||||
# Direct because the provider boundary catches this exception family;
|
||||
# OpenAI v3's transitive dependency alone is not an import contract.
|
||||
"httpx2>=2.7,<3",
|
||||
"mcp>=1.27,<2", # v2 is a breaking rewrite (2.0.0a1 live 2026-06-11; stable ~2026-07-27) — streamablehttp_client removed, 2-tuple transport, snake_case types; migrate deliberately
|
||||
"starlette>=1.3.1", # CVE-2026-54282 (path->authority host spoof) + CVE-2026-54283 (url-encoded form DoS); supersedes the PYSEC-2026-161 host-header path-injection floor
|
||||
"uvicorn>=0.34",
|
||||
@@ -47,9 +42,7 @@ dependencies = [
|
||||
"PyJWT>=2.8",
|
||||
"bcrypt>=4.0",
|
||||
"cryptography>=48.0.1", # GHSA-537c-gmf6-5ccf: PyPI wheels <48.0.1 bundle a vulnerable statically-linked OpenSSL (2026-06-09 secadv)
|
||||
# Core mTLS/ACME contract. 1.1 moves lacme onto HTTPX2; 1.2 adds typed IP
|
||||
# identifiers and retains the external responder URL for cross-host enrollment.
|
||||
"lacme>=1.2,<2",
|
||||
"lacme>=1.0.5",
|
||||
"python-frontmatter>=1.0",
|
||||
"pypdfium2>=4", # PDF text-extract + rasterize for models without native PDF input (core/pdf.py)
|
||||
"pillow>=10", # PNG encoding for the PDF->images rasterize fallback (vision models, core/pdf.py)
|
||||
@@ -95,10 +88,10 @@ include = [
|
||||
"turnstone/console/static/coordinator/*.js",
|
||||
"turnstone/shared_static/*.css",
|
||||
"turnstone/shared_static/*.js",
|
||||
"turnstone/shared_static/katex-0.18.4/**/*",
|
||||
"turnstone/shared_static/katex-0.17.0/**/*",
|
||||
"turnstone/shared_static/hljs-11.11.1/**/*",
|
||||
"turnstone/shared_static/mermaid-11.16.1/**/*",
|
||||
"turnstone/shared_static/hls-1.6.17/**/*",
|
||||
"turnstone/shared_static/mermaid-11.16.0/**/*",
|
||||
"turnstone/shared_static/hls-1.6.16/**/*",
|
||||
"turnstone/sdk/py.typed",
|
||||
"turnstone/deploy/*.yaml",
|
||||
"turnstone/deploy/Caddyfile",
|
||||
@@ -110,14 +103,8 @@ testpaths = ["tests"]
|
||||
markers = [
|
||||
"live: requires a running LLM backend",
|
||||
"allow_thread_leak: test intentionally leaves a background thread running (opts out of the leaked-thread guard)",
|
||||
"e2e_recovery: opt-in end-to-end SSE recovery harness (real server + real SSE consumers, scripted provider — NOT live, no LLM backend needed); tens of seconds each. CI lanes run ``-m 'not live and not e2e_recovery'``; select with ``-m e2e_recovery``.",
|
||||
]
|
||||
filterwarnings = [
|
||||
# The MCP v1 FastMCP integration fixture rebuilds its incomplete generic
|
||||
# Settings model before construction. Keep the new pydantic-settings 2.15
|
||||
# diagnostic fatal so removing that compatibility step cannot regress
|
||||
# into a warning hidden in the full-suite summary.
|
||||
"error:Field 'lifespan' has an incomplete definition",
|
||||
# mcp v1 deprecates streamablehttp_client for an entry point whose call
|
||||
# shape only settles in v2 — adoption rides the deliberate v2 migration
|
||||
# (pin capped <2); silence exactly this message until then.
|
||||
@@ -199,6 +186,10 @@ ignore_missing_imports = true
|
||||
module = ["frontmatter", "frontmatter.*"]
|
||||
ignore_missing_imports = true
|
||||
|
||||
[[tool.mypy.overrides]]
|
||||
module = ["lacme", "lacme.*"]
|
||||
ignore_missing_imports = true
|
||||
|
||||
[[tool.mypy.overrides]]
|
||||
module = ["pypdfium2", "pypdfium2.*"]
|
||||
ignore_missing_imports = true
|
||||
|
||||
@@ -4,9 +4,8 @@
|
||||
#
|
||||
# curl -fsSL https://raw.githubusercontent.com/turnstonelabs/turnstone/main/run.sh | bash
|
||||
#
|
||||
# Autodetects your distro — Ubuntu/Debian, Fedora/RHEL, Arch, their common
|
||||
# derivatives (Mint, Pop!_OS, Nobara, AlmaLinux, …), and WSL on any of them —
|
||||
# and:
|
||||
# Autodetects your distro (Ubuntu/Debian, Fedora/RHEL, Arch, and WSL on any of
|
||||
# them) and:
|
||||
# 1. ensures git is installed, then clones the repo
|
||||
# 2. ensures Docker + the compose plugin are installed and the daemon is usable
|
||||
# 3. asks how many server nodes to run (1-10)
|
||||
@@ -66,18 +65,12 @@ ask() {
|
||||
|
||||
# -- distro / package manager detection --------------------------------------
|
||||
OS_ID=""; OS_LIKE=""; PKG=""; IS_WSL=0; SUDO=""
|
||||
# Extra os-release fields, captured only to pick Docker's upstream repo when
|
||||
# get.docker.com refuses a derivative it doesn't recognize (see install_docker).
|
||||
OS_PLATFORM_ID=""; OS_CODENAME=""; OS_UBUNTU_CODENAME=""
|
||||
|
||||
detect_os() {
|
||||
if [ -r /etc/os-release ]; then
|
||||
# shellcheck disable=SC1091
|
||||
. /etc/os-release
|
||||
OS_ID="${ID:-}"; OS_LIKE="${ID_LIKE:-}"
|
||||
OS_PLATFORM_ID="${PLATFORM_ID:-}"
|
||||
OS_CODENAME="${VERSION_CODENAME:-}"
|
||||
OS_UBUNTU_CODENAME="${UBUNTU_CODENAME:-}"
|
||||
fi
|
||||
if grep -qiE 'microsoft|wsl' /proc/version 2>/dev/null || [ -n "${WSL_DISTRO_NAME:-}" ]; then
|
||||
IS_WSL=1
|
||||
@@ -137,83 +130,11 @@ clone_repo() {
|
||||
# -- docker -------------------------------------------------------------------
|
||||
DOCKER="docker"
|
||||
|
||||
# Fallback when get.docker.com won't install here. That script keys off $ID alone
|
||||
# (never ID_LIKE), so it aborts with "Unsupported distribution '<id>'" on every
|
||||
# derivative — Nobara, Linux Mint, Pop!_OS, AlmaLinux, Oracle Linux, … — even
|
||||
# though the family is clear. We already know the family from detect_os, so we add
|
||||
# Docker's official CE repo for the matching upstream and install the same
|
||||
# packages get.docker.com would (including the compose plugin the rest of run.sh
|
||||
# relies on).
|
||||
install_docker_ce_repo() {
|
||||
local up
|
||||
case "$PKG" in
|
||||
apt)
|
||||
local codename arch
|
||||
# UBUNTU_CODENAME is set by Ubuntu and every Ubuntu-derived distro
|
||||
# (Mint/Pop!_OS/Zorin/…) and never by pure Debian, so it both routes
|
||||
# the family and gives the exact codename Docker's repo expects.
|
||||
if [ -n "$OS_UBUNTU_CODENAME" ]; then
|
||||
up=ubuntu; codename="$OS_UBUNTU_CODENAME"
|
||||
else
|
||||
up=debian; codename="$OS_CODENAME"
|
||||
fi
|
||||
[ -n "$codename" ] || die "couldn't determine the $up release codename for Docker's repo — install Docker manually and re-run."
|
||||
arch="$(dpkg --print-architecture 2>/dev/null || echo amd64)"
|
||||
info "Adding Docker's $up repository ($codename)."
|
||||
$SUDO install -m 0755 -d /etc/apt/keyrings
|
||||
curl -fsSL "https://download.docker.com/linux/$up/gpg" | $SUDO tee /etc/apt/keyrings/docker.asc >/dev/null
|
||||
$SUDO chmod a+r /etc/apt/keyrings/docker.asc
|
||||
printf 'deb [arch=%s signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/%s %s stable\n' \
|
||||
"$arch" "$up" "$codename" | $SUDO tee /etc/apt/sources.list.d/docker.list >/dev/null
|
||||
$SUDO apt-get update -y
|
||||
$SUDO apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
|
||||
;;
|
||||
dnf|yum)
|
||||
# A Fedora spin and a RHEL clone can both carry "fedora" in ID_LIKE
|
||||
# (Nobara's is "rhel centos fedora"), so ID_LIKE can't separate them.
|
||||
# PLATFORM_ID can: Fedora is platform:fNN, Enterprise Linux platform:elN.
|
||||
case "$OS_PLATFORM_ID" in
|
||||
platform:f*) up=fedora ;;
|
||||
platform:el*) up=centos ;;
|
||||
*) if [ -e /etc/fedora-release ]; then up=fedora; else up=centos; fi ;;
|
||||
esac
|
||||
info "Adding Docker's $up repository."
|
||||
$SUDO curl -fsSL "https://download.docker.com/linux/$up/docker-ce.repo" \
|
||||
-o /etc/yum.repos.d/docker-ce.repo \
|
||||
|| die "couldn't add Docker's $up repository — install Docker manually and re-run."
|
||||
pkg_install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# The distro IDs get.docker.com installs directly: it matches $ID against this
|
||||
# exact set (ignoring ID_LIKE) and aborts on anything else. Mirrors the dispatch
|
||||
# in get.docker.com, including its fedora-asahi-remix -> fedora alias.
|
||||
get_docker_com_supports() {
|
||||
case "$1" in
|
||||
ubuntu|debian|raspbian|centos|fedora|rhel|rocky|sles|fedora-asahi-remix) return 0 ;;
|
||||
*) return 1 ;;
|
||||
esac
|
||||
}
|
||||
|
||||
install_docker() {
|
||||
case "$PKG" in
|
||||
apt|dnf|yum)
|
||||
# Decide up front which installer applies, rather than treating every
|
||||
# get.docker.com failure as "unsupported distro": for an ID it knows,
|
||||
# let it run and surface any real failure (network, apt lock, EOL) via
|
||||
# die instead of masking it with the repo path. Only unrecognized
|
||||
# derivatives (Nobara, Mint, …) — which it would just abort on — skip
|
||||
# straight to adding Docker's repo ourselves.
|
||||
if [ -n "$OS_ID" ] && ! get_docker_com_supports "$OS_ID"; then
|
||||
info "get.docker.com doesn't support '$OS_ID' — using Docker's official repository directly."
|
||||
install_docker_ce_repo
|
||||
else
|
||||
info "Installing Docker via the official get.docker.com script"
|
||||
curl -fsSL https://get.docker.com | $SUDO sh \
|
||||
|| die "get.docker.com failed to install Docker (see the output above). Fix the issue and re-run — the script resumes."
|
||||
fi
|
||||
;;
|
||||
info "Installing Docker via the official get.docker.com script"
|
||||
curl -fsSL https://get.docker.com | $SUDO sh ;;
|
||||
pacman)
|
||||
pkg_install docker docker-compose ;;
|
||||
esac
|
||||
@@ -445,15 +366,12 @@ ${GREEN}${BOLD}Turnstone is running${RESET} (${NODE_COUNT} node$([ "$NODE_COUNT"
|
||||
${DIM}cd $INSTALL_DIR && $DOCKER compose exec caddy cat /data/caddy/pki/authorities/local/root.crt${RESET}
|
||||
|
||||
Finish setup
|
||||
1. Open ${BOLD}${url}${RESET} and create the admin account when prompted —
|
||||
the first user created there gets full admin access.
|
||||
2. Log in, then add a model backend in the ${BOLD}Models${RESET} tab —
|
||||
1. Create the first admin user:
|
||||
${DIM}cd $INSTALL_DIR && $DOCKER compose exec node-1 turnstone-admin create-user --username admin --name "Admin"${RESET}
|
||||
2. Open ${url}, log in, and add a model backend in the ${BOLD}Models${RESET} tab —
|
||||
a local server (vLLM / llama.cpp) or an OpenAI / Anthropic / Gemini key.
|
||||
Nodes boot without a model and pick it up live; no restart needed.
|
||||
|
||||
${DIM}No browser? Create the admin from the CLI instead:
|
||||
cd $INSTALL_DIR && $DOCKER compose exec node-1 turnstone-admin create-admin --username admin --name "Admin"${RESET}
|
||||
|
||||
Scale Running ${scale}
|
||||
|
||||
Manage ${DIM}cd $INSTALL_DIR${RESET}
|
||||
|
||||
@@ -1,458 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Browser regression for the two-layer frontend cache contract.
|
||||
|
||||
This harness serves a versioned entry module which imports the real,
|
||||
unversioned ``shared/interactive.js`` module. It loads an old pane build in a
|
||||
real Chrome profile, switches the server to a same-version replacement whose
|
||||
pane has the same byte length and mtime, then performs a normal browser reload
|
||||
without clearing or disabling the HTTP cache.
|
||||
|
||||
The old fixture advertises ``user_turn=0&tool_turn=0`` in its EventSource URL;
|
||||
the current source advertises both capabilities as ``1``. A passing run
|
||||
therefore proves both layers of the contract:
|
||||
|
||||
* the package-versioned entry URL revalidates and may return 304; and
|
||||
* its unversioned transitive pane import revalidates by content and returns the
|
||||
current bytes rather than surviving from the prior build.
|
||||
|
||||
The page also loads representative KaTeX, Highlight.js, and HLS.js assets.
|
||||
Their installed version directories are discovered from ``shared_static`` at
|
||||
runtime, so a normal vendor-version bump requires no harness edit; reload must
|
||||
reuse them under the immutable policy.
|
||||
|
||||
Usage::
|
||||
|
||||
uv run python scripts/asset_cache_e2e.py
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import socket
|
||||
import sys
|
||||
import tempfile
|
||||
import threading
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
if str(ROOT) not in sys.path:
|
||||
sys.path.insert(0, str(ROOT))
|
||||
|
||||
from recovery_e2e import CDP, _find_chrome, _launch_chrome, _page_ws_url # noqa: E402
|
||||
|
||||
from turnstone import __version__ # noqa: E402
|
||||
from turnstone.core.web_helpers import ( # noqa: E402
|
||||
RevalidatingStaticFiles,
|
||||
version_html,
|
||||
)
|
||||
|
||||
_PAGE_HTML = """<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>ASSET-CACHE-PENDING</title>
|
||||
<!-- VENDORED_ASSET_TAGS -->
|
||||
<script>
|
||||
window.__assetCacheUrls = [];
|
||||
class RecordingEventSource {
|
||||
static CONNECTING = 0;
|
||||
static OPEN = 1;
|
||||
static CLOSED = 2;
|
||||
constructor(url) {
|
||||
this.url = String(url);
|
||||
this.readyState = RecordingEventSource.CONNECTING;
|
||||
window.__assetCacheUrls.push(this.url);
|
||||
}
|
||||
close() {
|
||||
this.readyState = RecordingEventSource.CLOSED;
|
||||
}
|
||||
}
|
||||
window.EventSource = RecordingEventSource;
|
||||
window.addEventListener("error", (event) => {
|
||||
document.title = "ASSET-CACHE-FAILED-" + String(event.message || "script").slice(0, 80);
|
||||
});
|
||||
window.addEventListener("unhandledrejection", (event) => {
|
||||
document.title = "ASSET-CACHE-FAILED-" + String(event.reason || "promise").slice(0, 80);
|
||||
});
|
||||
</script>
|
||||
</head>
|
||||
<body>
|
||||
<main id="pane"></main>
|
||||
<script type="module" src="/static/asset_cache_boot.js"
|
||||
onerror="document.title='ASSET-CACHE-FAILED-module-load'"></script>
|
||||
</body>
|
||||
</html>
|
||||
"""
|
||||
|
||||
_BOOT_JS = """import { InteractivePane } from "/shared/interactive.js";
|
||||
|
||||
const fixtureWorkstreamId = "00000000-0000-0000-0000-000000000001";
|
||||
const pane = new InteractivePane(fixtureWorkstreamId, { base: "" });
|
||||
document.getElementById("pane").appendChild(pane.el);
|
||||
pane.connectSSE(fixtureWorkstreamId);
|
||||
const url = window.__assetCacheUrls.at(-1) || "";
|
||||
const generation = url.includes("user_turn=1") && url.includes("tool_turn=1")
|
||||
? "CURRENT"
|
||||
: url.includes("user_turn=0") && url.includes("tool_turn=0")
|
||||
? "OLD"
|
||||
: "FAILED-CAPABILITIES";
|
||||
window.__assetCacheResult = { generation, url };
|
||||
document.title = "ASSET-CACHE-" + generation;
|
||||
"""
|
||||
|
||||
|
||||
@dataclass
|
||||
class CacheState:
|
||||
phase: str = "old"
|
||||
requests: list[dict[str, Any]] = field(default_factory=list)
|
||||
lock: threading.Lock = field(default_factory=threading.Lock)
|
||||
|
||||
def record(self, item: dict[str, Any]) -> None:
|
||||
with self.lock:
|
||||
self.requests.append(item)
|
||||
|
||||
def matching(self, phase: str, path: str) -> list[dict[str, Any]]:
|
||||
with self.lock:
|
||||
return [
|
||||
item for item in self.requests if item["phase"] == phase and item["path"] == path
|
||||
]
|
||||
|
||||
|
||||
class SwitchingStaticFiles:
|
||||
"""Select one immutable build snapshot at request dispatch time."""
|
||||
|
||||
def __init__(self, state: CacheState, old_dir: Path, current_dir: Path) -> None:
|
||||
self._state = state
|
||||
self._apps = {
|
||||
"old": RevalidatingStaticFiles(directory=str(old_dir)),
|
||||
"current": RevalidatingStaticFiles(directory=str(current_dir)),
|
||||
}
|
||||
|
||||
async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
|
||||
await self._apps[self._state.phase](scope, receive, send)
|
||||
|
||||
|
||||
class RecordingApp:
|
||||
"""Record static HTTP validators and status without perturbing streaming."""
|
||||
|
||||
def __init__(self, app: Any, state: CacheState) -> None:
|
||||
self._app = app
|
||||
self._state = state
|
||||
|
||||
async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
|
||||
path = str(scope.get("path", ""))
|
||||
if scope.get("type") != "http" or not path.startswith(("/static/", "/shared/")):
|
||||
await self._app(scope, receive, send)
|
||||
return
|
||||
|
||||
phase = self._state.phase
|
||||
request_headers = {
|
||||
key.decode("latin-1").lower(): value.decode("latin-1")
|
||||
for key, value in scope.get("headers", [])
|
||||
}
|
||||
|
||||
async def record_send(message: dict[str, Any]) -> None:
|
||||
if message["type"] == "http.response.start":
|
||||
response_headers = {
|
||||
key.decode("latin-1").lower(): value.decode("latin-1")
|
||||
for key, value in message.get("headers", [])
|
||||
}
|
||||
self._state.record(
|
||||
{
|
||||
"phase": phase,
|
||||
"path": path,
|
||||
"query": scope.get("query_string", b"").decode("latin-1"),
|
||||
"if_none_match": request_headers.get("if-none-match"),
|
||||
"status": message["status"],
|
||||
"etag": response_headers.get("etag"),
|
||||
"cache_control": response_headers.get("cache-control"),
|
||||
}
|
||||
)
|
||||
await send(message)
|
||||
|
||||
await self._app(scope, receive, record_send)
|
||||
|
||||
|
||||
def _old_interactive(current: bytes) -> bytes:
|
||||
old = current
|
||||
for needle, replacement in (
|
||||
(b'"user_turn=1"', b'"user_turn=0"'),
|
||||
(b'"&tool_turn=1"', b'"&tool_turn=0"'),
|
||||
):
|
||||
if old.count(needle) != 1:
|
||||
raise RuntimeError(f"expected exactly one {needle.decode()} capability literal")
|
||||
old = old.replace(needle, replacement, 1)
|
||||
if len(old) != len(current):
|
||||
raise AssertionError("old and current pane fixtures must have equal byte length")
|
||||
return old
|
||||
|
||||
|
||||
def _discover_vendor_assets(source_shared: Path) -> tuple[str, ...]:
|
||||
selected = (
|
||||
("katex", "katex.min.css"),
|
||||
("katex", "katex.min.js"),
|
||||
("hljs", "highlight.min.js"),
|
||||
("hls", "hls.min.js"),
|
||||
)
|
||||
paths = []
|
||||
for library, filename in selected:
|
||||
matches = sorted(source_shared.glob(f"{library}-*/{filename}"))
|
||||
if not matches:
|
||||
raise RuntimeError(f"no vendored {library} asset named {filename} was found")
|
||||
paths.extend(f"/shared/{match.relative_to(source_shared).as_posix()}" for match in matches)
|
||||
return tuple(paths)
|
||||
|
||||
|
||||
def _vendor_tags(vendor_paths: tuple[str, ...]) -> str:
|
||||
tags = []
|
||||
for path in vendor_paths:
|
||||
if path.endswith(".css"):
|
||||
tags.append(f'<link rel="stylesheet" href="{path}">')
|
||||
else:
|
||||
tags.append(f'<script src="{path}"></script>')
|
||||
return "\n ".join(tags)
|
||||
|
||||
|
||||
def _prepare_builds(scratch: Path) -> tuple[Path, Path, Path, tuple[str, ...]]:
|
||||
import turnstone
|
||||
|
||||
package_dir = Path(turnstone.__file__).resolve().parent
|
||||
source_shared = package_dir / "shared_static"
|
||||
vendor_paths = _discover_vendor_assets(source_shared)
|
||||
old_shared = scratch / "old" / "shared"
|
||||
current_shared = scratch / "current" / "shared"
|
||||
static_dir = scratch / "static"
|
||||
shutil.copytree(source_shared, old_shared)
|
||||
shutil.copytree(source_shared, current_shared)
|
||||
static_dir.mkdir()
|
||||
(static_dir / "asset_cache_boot.js").write_text(_BOOT_JS, encoding="utf-8")
|
||||
|
||||
current_asset = current_shared / "interactive.js"
|
||||
old_asset = old_shared / "interactive.js"
|
||||
current = current_asset.read_bytes()
|
||||
old_asset.write_bytes(_old_interactive(current))
|
||||
|
||||
# Reproduce the metadata collision which defeated Starlette's default ETag.
|
||||
fixed_mtime_ns = 1_700_000_000_123_456_789
|
||||
for asset in (old_asset, current_asset):
|
||||
os.utime(asset, ns=(fixed_mtime_ns, fixed_mtime_ns))
|
||||
old_stat = old_asset.stat()
|
||||
current_stat = current_asset.stat()
|
||||
if (old_stat.st_size, old_stat.st_mtime_ns) != (
|
||||
current_stat.st_size,
|
||||
current_stat.st_mtime_ns,
|
||||
):
|
||||
raise AssertionError("pane fixture size/mtime collision was not preserved")
|
||||
return old_shared, current_shared, static_dir, vendor_paths
|
||||
|
||||
|
||||
def _make_app(
|
||||
state: CacheState,
|
||||
old_dir: Path,
|
||||
current_dir: Path,
|
||||
static_dir: Path,
|
||||
vendor_paths: tuple[str, ...],
|
||||
) -> Any:
|
||||
from starlette.applications import Starlette
|
||||
from starlette.responses import HTMLResponse
|
||||
from starlette.routing import Mount, Route
|
||||
|
||||
async def page(_request: Any) -> HTMLResponse:
|
||||
page_html = _PAGE_HTML.replace("<!-- VENDORED_ASSET_TAGS -->", _vendor_tags(vendor_paths))
|
||||
return HTMLResponse(
|
||||
version_html(page_html),
|
||||
headers={"Cache-Control": "no-store"},
|
||||
)
|
||||
|
||||
app = Starlette(
|
||||
routes=[
|
||||
Route("/asset-cache-e2e", page),
|
||||
Mount(
|
||||
"/static",
|
||||
app=RevalidatingStaticFiles(directory=str(static_dir)),
|
||||
),
|
||||
Mount(
|
||||
"/shared",
|
||||
app=SwitchingStaticFiles(state, old_dir, current_dir),
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
return RecordingApp(app, state)
|
||||
|
||||
|
||||
def _start_server(app: Any) -> tuple[Any, threading.Thread, socket.socket, str]:
|
||||
import uvicorn
|
||||
|
||||
sock = socket.socket()
|
||||
sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
|
||||
sock.bind(("127.0.0.1", 0))
|
||||
sock.listen(128)
|
||||
port = int(sock.getsockname()[1])
|
||||
server = uvicorn.Server(
|
||||
uvicorn.Config(app, host="127.0.0.1", port=port, log_level="warning", lifespan="off")
|
||||
)
|
||||
thread = threading.Thread(
|
||||
target=server.run,
|
||||
kwargs={"sockets": [sock]},
|
||||
name="asset-cache-e2e-server",
|
||||
daemon=True,
|
||||
)
|
||||
thread.start()
|
||||
deadline = time.monotonic() + 10
|
||||
while not server.started and thread.is_alive() and time.monotonic() < deadline:
|
||||
time.sleep(0.05)
|
||||
if not server.started:
|
||||
server.should_exit = True
|
||||
thread.join(timeout=2)
|
||||
sock.close()
|
||||
raise RuntimeError("asset cache test server did not start")
|
||||
return server, thread, sock, f"http://127.0.0.1:{port}"
|
||||
|
||||
|
||||
def _wait_for_generation(cdp: CDP, expected: str, timeout: float = 20) -> dict[str, str]:
|
||||
deadline = time.monotonic() + timeout
|
||||
last_title = ""
|
||||
while time.monotonic() < deadline:
|
||||
last_title = cdp.title()
|
||||
result = cdp.evaluate("window.__assetCacheResult || null")
|
||||
if isinstance(result, dict) and result.get("generation") == expected:
|
||||
return {"generation": str(result["generation"]), "url": str(result["url"])}
|
||||
if last_title.startswith("ASSET-CACHE-FAILED"):
|
||||
raise RuntimeError(last_title)
|
||||
time.sleep(0.1)
|
||||
raise TimeoutError(f"expected {expected}, last title was {last_title!r}")
|
||||
|
||||
|
||||
def _one(state: CacheState, phase: str, path: str) -> dict[str, Any]:
|
||||
requests = state.matching(phase, path)
|
||||
if len(requests) != 1:
|
||||
raise AssertionError(f"expected one {phase} request for {path}, got {requests!r}")
|
||||
return requests[0]
|
||||
|
||||
|
||||
def _verify_trace(state: CacheState, vendor_paths: tuple[str, ...]) -> tuple[str, list[str]]:
|
||||
entry_path = "/static/asset_cache_boot.js"
|
||||
pane_path = "/shared/interactive.js"
|
||||
old_entry = _one(state, "old", entry_path)
|
||||
current_entry = _one(state, "current", entry_path)
|
||||
old_pane = _one(state, "old", pane_path)
|
||||
current_pane = _one(state, "current", pane_path)
|
||||
|
||||
expected_query = f"v={__version__}"
|
||||
if old_entry["query"] != expected_query or current_entry["query"] != expected_query:
|
||||
raise AssertionError("entry URL did not retain the same package version across builds")
|
||||
if old_entry["status"] != 200 or old_pane["status"] != 200:
|
||||
raise AssertionError("old build did not populate the browser cache")
|
||||
if current_entry["status"] != 304 or not current_entry["if_none_match"]:
|
||||
raise AssertionError(f"versioned entry did not revalidate to 304: {current_entry!r}")
|
||||
if current_pane["status"] != 200 or not current_pane["if_none_match"]:
|
||||
raise AssertionError(
|
||||
f"transitive pane did not revalidate to current bytes: {current_pane!r}"
|
||||
)
|
||||
if old_pane["etag"] == current_pane["etag"]:
|
||||
raise AssertionError("content-derived pane validators did not change")
|
||||
if current_pane["cache_control"] != "no-cache":
|
||||
raise AssertionError("transitive pane lost its revalidation policy")
|
||||
|
||||
vendor_trace = []
|
||||
immutable = "public, max-age=31536000, immutable"
|
||||
for path in vendor_paths:
|
||||
old_vendor = _one(state, "old", path)
|
||||
if old_vendor["query"] or old_vendor["status"] != 200:
|
||||
raise AssertionError(f"versioned vendor URL was rewritten or failed: {old_vendor!r}")
|
||||
if old_vendor["cache_control"] != immutable:
|
||||
raise AssertionError(f"versioned vendor asset was not immutable: {old_vendor!r}")
|
||||
revisits = state.matching("current", path)
|
||||
if revisits:
|
||||
if len(revisits) != 1 or revisits[0]["status"] not in (200, 304):
|
||||
raise AssertionError(f"unexpected vendor reload trace: {revisits!r}")
|
||||
if revisits[0]["cache_control"] != immutable:
|
||||
raise AssertionError(f"vendor reload lost immutable policy: {revisits[0]!r}")
|
||||
vendor_trace.append(f"{path}: revisited-{revisits[0]['status']}")
|
||||
else:
|
||||
vendor_trace.append(f"{path}: cache-hit")
|
||||
verdict = f"ASSET-CACHE-READY-entry304-pane200-user1-tool1-vendor{len(vendor_paths)}"
|
||||
return verdict, vendor_trace
|
||||
|
||||
|
||||
def _stop_process(proc: Any) -> None:
|
||||
if proc.poll() is not None:
|
||||
return
|
||||
proc.terminate()
|
||||
with contextlib.suppress(Exception):
|
||||
proc.wait(timeout=5)
|
||||
if proc.poll() is None:
|
||||
proc.kill()
|
||||
with contextlib.suppress(Exception):
|
||||
proc.wait(timeout=2)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
chrome = _find_chrome()
|
||||
if not chrome:
|
||||
print("ASSET-CACHE-FAILED-no-chrome")
|
||||
return 2
|
||||
|
||||
with tempfile.TemporaryDirectory(prefix="turnstone-asset-cache-e2e-") as raw_scratch:
|
||||
scratch = Path(raw_scratch)
|
||||
old_dir, current_dir, static_dir, vendor_paths = _prepare_builds(scratch)
|
||||
state = CacheState()
|
||||
server, server_thread, sock, base_url = _start_server(
|
||||
_make_app(state, old_dir, current_dir, static_dir, vendor_paths)
|
||||
)
|
||||
chrome_proc = None
|
||||
cdp = None
|
||||
try:
|
||||
chrome_proc, cdp_port = _launch_chrome(chrome, scratch / "chrome-profile")
|
||||
cdp = CDP(_page_ws_url(cdp_port))
|
||||
cdp.cmd("Page.enable")
|
||||
cdp.cmd("Runtime.enable")
|
||||
cdp.cmd("Network.enable")
|
||||
cdp.cmd("Page.navigate", {"url": f"{base_url}/asset-cache-e2e"})
|
||||
old_result = _wait_for_generation(cdp, "OLD")
|
||||
|
||||
state.phase = "current"
|
||||
cdp.cmd("Page.reload", {"ignoreCache": False})
|
||||
current_result = _wait_for_generation(cdp, "CURRENT")
|
||||
|
||||
if "user_turn=0" not in old_result["url"] or "tool_turn=0" not in old_result["url"]:
|
||||
raise AssertionError(f"old pane did not expose old capabilities: {old_result!r}")
|
||||
if (
|
||||
"user_turn=1" not in current_result["url"]
|
||||
or "tool_turn=1" not in current_result["url"]
|
||||
):
|
||||
raise AssertionError(
|
||||
f"reloaded pane did not expose current capabilities: {current_result!r}"
|
||||
)
|
||||
|
||||
verdict, vendor_trace = _verify_trace(state, vendor_paths)
|
||||
cdp.evaluate(f"document.title = {json.dumps(verdict)}")
|
||||
print(verdict)
|
||||
print(f" old EventSource: {old_result['url']}")
|
||||
print(f" current EventSource: {current_result['url']}")
|
||||
for item in vendor_trace:
|
||||
print(f" vendor: {item}")
|
||||
return 0
|
||||
except Exception as exc:
|
||||
print(f"ASSET-CACHE-FAILED-{type(exc).__name__}: {exc}")
|
||||
return 1
|
||||
finally:
|
||||
if cdp is not None:
|
||||
cdp.close()
|
||||
if chrome_proc is not None:
|
||||
_stop_process(chrome_proc)
|
||||
server.should_exit = True
|
||||
server_thread.join(timeout=10)
|
||||
with contextlib.suppress(OSError):
|
||||
sock.close()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
+16
-708
@@ -45,22 +45,6 @@ Shell harness (?split=): right (default) · down · three · none — boots the
|
||||
document.title stamps SPLIT-READY-<visible cells> on success and
|
||||
SPLIT-FAILED-<reason> when a driven split was denied — judge the focused
|
||||
cell's top accent bar, the separators, and the .shown tab marker.
|
||||
Proxy-brand harness (/proxybrand/livepass.html): back-to-console from a
|
||||
PROXIED node view, driven end to end. An iframe hosts a node page built
|
||||
from the REAL shell.js rail plus the REAL _JS_PROXY_SHIM (read out of
|
||||
turnstone/console/server.py by text, never imported -- scripts/ has no
|
||||
sys.path guard, so an import would silently pick up site-packages). The
|
||||
host clicks the brand's child span and, because the shim navigates the
|
||||
FRAME away, reads the frame's post-navigation location from the surviving
|
||||
top page. document.title stamps PROXYBRAND-READY, or
|
||||
PROXYBRAND-FAILED-<reason>: sub-not-repointed-server (nothing wired),
|
||||
showhome-also-ran (shell.js won the click), nav-<path> (went somewhere
|
||||
other than the console root), sub-not-console-<text>, aria-not-repointed,
|
||||
no-navigation, no-brand, no-sub. Needs --virtual-time-budget=9000;
|
||||
there is nothing to screenshot. Read the verdict from <title> --
|
||||
both literals also appear in the host page's inline script, so a bare
|
||||
grep over --dump-dom output false-positives.
|
||||
|
||||
Attachments harness (/attachments/livepass.html): the composer attachment
|
||||
chips + the sent-message attachment pills, both driven through the REAL
|
||||
code paths — createAttachmentController.rehydrate() builds the chips and
|
||||
@@ -74,21 +58,6 @@ Attachments harness (/attachments/livepass.html): the composer attachment
|
||||
thumbnail crop/size, the native audio-control fit at the constrained
|
||||
height, the snippet contrast, and how a long filename behaves at the
|
||||
340px chip cap.
|
||||
Paste-over-HTTP harness (/paste/livepass.html): the REAL Composer's
|
||||
large-text paste path, exercised with a browser-generated, trusted paste
|
||||
event on an explicitly non-secure HTTP origin. No
|
||||
``navigator.clipboard`` stub, synthetic ``ClipboardEvent``, or
|
||||
secure-context override is involved. The page requires
|
||||
``window.isSecureContext === false``, ``event.isTrusted``, a ``text/plain``
|
||||
clipboard item, canceled inline insertion, and an exact
|
||||
``pasted-text.txt`` File round-trip before stamping ``PASTE-HTTP-READY``.
|
||||
It fails closed as ``PASTE-HTTP-FAILED-<reason>``. Serve beyond loopback,
|
||||
open the page by a LAN address (localhost and 127.0.0.1 are treated as
|
||||
trustworthy origins by browsers), then use the browser's normal Copy and
|
||||
Paste commands:
|
||||
|
||||
python3 scripts/livepass.py --serve 8950 --bind 0.0.0.0
|
||||
|
||||
Task-agent harness (/taskagent/livepass.html): the task_agent card — a task
|
||||
agent's sub-tool steps nested under its conversation row, driven through the
|
||||
REAL InteractivePane.handleEvent (parent tool_pending/tool_info -> child
|
||||
@@ -110,30 +79,6 @@ Task-agent harness (/taskagent/livepass.html): the task_agent card — a task
|
||||
success, TASKAGENT-FAILED-... / TASKAGENT-ERROR when routing breaks, so a
|
||||
broken card can't screenshot green.
|
||||
|
||||
Copy harness (/copy/livepass.html): the copy-to-clipboard affordances — the
|
||||
per-bubble copy button in .msg-actions and the floating block-copy button
|
||||
over hovered fences / mermaid diagrams / tables (pointer-only; keyboard
|
||||
copies with Enter on the focused block) — driven through the REAL
|
||||
InteractivePane (replayHistory plus a live handleEvent stream turn, so the
|
||||
retry-holder buttons coexist with the persistent copy buttons on the last
|
||||
bubble; the turn ends idle, matching the affordances' idle-only gate).
|
||||
navigator.clipboard is stubbed to a recorder, hover/focus/keys are
|
||||
dispatched synthetically, and every copied payload is compared byte-exact
|
||||
against the SOURCE (fences, pipes, mermaid text, the bubble's raw
|
||||
markdown). + &theme=light. document.title stamps
|
||||
COPY-READY-<bubbles>-<blocks> only when every probe copied exact source;
|
||||
COPY-FAILED-<reason> otherwise. &kbd=1 probes the KEYBOARD path: focus a
|
||||
block, dispatch Enter — the block's source lands on the clipboard, the
|
||||
block carries the outcome flash class, and the floating button stays out
|
||||
of it — stamps COPY-KBD-READY / COPY-KBD-FAILED-<step>.
|
||||
Screenshot states: &flash=1 (visual-only
|
||||
run — no probes; floating button + ✓ state on the fence, holder bar
|
||||
revealed via focus) and &bare=1 (single hover, no decoration). Known
|
||||
capture artifact: the DARK-theme &flash=1 shot can omit the floating
|
||||
button's pixels (headless software compositor; the DOM state is correct
|
||||
and light theme paints) — judge the dark floating button from &bare=1
|
||||
and the ✓ state from the light shot. &stepmax=N bisects a paint
|
||||
regression to the interaction that triggers it.
|
||||
Perf harness (/perf/livepass.html): long-session performance baseline for the
|
||||
interactive pane — mounts the REAL InteractivePane at real scroll geometry
|
||||
(fixed-height mount, production CSS chain) and drives production-shaped
|
||||
@@ -198,24 +143,6 @@ def extract_admin_fragment() -> str:
|
||||
return html[start:end]
|
||||
|
||||
|
||||
def extract_proxy_shim(prefix: str = "/node/livepass-node") -> str:
|
||||
"""Pull ``_JS_PROXY_SHIM`` out of console/server.py BY TEXT, not import.
|
||||
|
||||
``scripts/`` has no ``sys.path`` guard, so ``import turnstone`` from here
|
||||
resolves to whatever is installed in site-packages rather than this
|
||||
checkout -- silently building the page from a DIFFERENT version of the
|
||||
shim than the one you are trying to verify. Read the source instead.
|
||||
"""
|
||||
src = (ROOT / "turnstone/console/server.py").read_text(encoding="utf-8")
|
||||
m = re.search(r'^_JS_PROXY_SHIM = """\\\n(.*?)^"""', src, re.S | re.M)
|
||||
if not m:
|
||||
raise SystemExit(
|
||||
"livepass: could not find _JS_PROXY_SHIM in turnstone/console/server.py "
|
||||
"-- the constant was renamed or reshaped; update extract_proxy_shim()."
|
||||
)
|
||||
return m.group(1).replace('"PREFIX_PLACEHOLDER"', json.dumps(prefix))
|
||||
|
||||
|
||||
def inject(template: str, marker: str, payload: str) -> str:
|
||||
begin = template.index(f"<!-- {marker}:BEGIN -->") + len(f"<!-- {marker}:BEGIN -->")
|
||||
end = template.index(f"<!-- {marker}:END -->")
|
||||
@@ -420,28 +347,6 @@ CONSOLE_TEMPLATE = """<!doctype html>
|
||||
<div id="toast" role="status" aria-live="polite"></div>
|
||||
<script>
|
||||
(function () {
|
||||
// Freeze window.fetch BEFORE the module scripts evaluate: auth.js
|
||||
// fires a boot-time whoami at import, and a non-OK answer from the
|
||||
// fixture server would CLEAR the permissions grant seeded below
|
||||
// mid-pass. A never-settling fetch keeps the seed authoritative;
|
||||
// everything the passes drive flows through the authFetch fixture
|
||||
// (reinstated after auth.js's window bridge runs — see the load
|
||||
// handler).
|
||||
window.fetch = function () {
|
||||
return new Promise(function () {});
|
||||
};
|
||||
// Grant the operator scopes admin.js gates on: _modelAuthEditable()
|
||||
// reads this exact key THROUGH the real auth.js hasPermission
|
||||
// (loaded below, before admin.js) — without the grant, or without
|
||||
// auth.js supplying window.hasPermission, the auth-constraints
|
||||
// stub below is dead code: _fetchModelAuthConstraints returns
|
||||
// before authFetch and every pass renders the Backend-auth section
|
||||
// in its read-only degraded state. The headless profile is fresh
|
||||
// per pass, so nothing else seeds it.
|
||||
sessionStorage.setItem(
|
||||
"turnstone_permissions",
|
||||
"admin.models,admin.mcp",
|
||||
);
|
||||
function reply(data) {
|
||||
return Promise.resolve({
|
||||
ok: true,
|
||||
@@ -467,15 +372,9 @@ CONSOLE_TEMPLATE = """<!doctype html>
|
||||
enabled: true, temperature: null, max_tokens: null,
|
||||
reasoning_effort: null, surface_persisted_reasoning: true,
|
||||
replay_reasoning_to_model: false,
|
||||
auth_mode: "static", obo_audience: "", obo_scopes: "",
|
||||
};
|
||||
window.__putCount = 0;
|
||||
// Held under a private name too: auth.js's legacy window bridge
|
||||
// (Object.assign(window, {authFetch})) runs at module-import time
|
||||
// and clobbers the plain window.authFetch assigned here — the load
|
||||
// handler reinstates the fixture from this name after the modules
|
||||
// have evaluated.
|
||||
window.__consoleAuthFetch = window.authFetch = function (url, opts) {
|
||||
window.authFetch = function (url, opts) {
|
||||
var method = (opts && opts.method) || "GET";
|
||||
if (method === "PUT" && url.indexOf("/model-definitions/def1") >= 0) {
|
||||
window.__putCount++;
|
||||
@@ -500,31 +399,13 @@ CONSOLE_TEMPLATE = """<!doctype html>
|
||||
known: true,
|
||||
capabilities: {
|
||||
context_window: 200000, supports_tools: true,
|
||||
supports_vision: true,
|
||||
supports_streaming: true, supports_vision: true,
|
||||
supports_web_search: true, supports_temperature: true,
|
||||
supports_effort: true,
|
||||
},
|
||||
});
|
||||
if (url.indexOf("/model-definitions/auth-constraints") >= 0)
|
||||
// Fetched by the shelf ON OPEN (showCreateModelModal /
|
||||
// showEditModelModal), so this stub is exercised by any pass that
|
||||
// opens the model editor — no tab-switch plumbing needed. Omitting
|
||||
// it would render the Backend-auth block in its degraded
|
||||
// no-suggestions state and quietly stop exercising the section.
|
||||
return reply({
|
||||
auth_audience_allowlist: ["api://example-gateway"],
|
||||
auth_grant_profile: "entra",
|
||||
dynamic_auth_modes: ["entra_app", "entra_obo", "rfc8693_obo"],
|
||||
scopes_auth_modes: ["rfc8693_obo"],
|
||||
app_identity_auth_modes: ["entra_app"],
|
||||
auth_mode_profiles: {
|
||||
entra_app: "entra", entra_obo: "entra",
|
||||
rfc8693_obo: "rfc8693",
|
||||
},
|
||||
});
|
||||
if (url.indexOf("/model-definitions/def1") >= 0) return reply(MODEL);
|
||||
if (url.indexOf("/model-definitions") >= 0)
|
||||
return reply({ models: [], default_alias: "fable-5" });
|
||||
if (url.indexOf("/model-definitions") >= 0) return reply({ models: [] });
|
||||
if (url.indexOf("/api/models") >= 0)
|
||||
return reply({ models: [
|
||||
{ alias: "fable-5", model: "claude-fable-5" },
|
||||
@@ -551,22 +432,10 @@ CONSOLE_TEMPLATE = """<!doctype html>
|
||||
</script>
|
||||
<script type="module" src="shared/utils.js"></script>
|
||||
<script type="module" src="shared/hatch.js"></script>
|
||||
<!-- The REAL auth.js, loaded (and therefore parsed) before admin.js's
|
||||
permission shims run any pass: it owns the sessionStorage parse
|
||||
contract and assigns the window.hasPermission /
|
||||
window.whenPermissionsReady globals the shims probe at call time.
|
||||
Without it the seeded permissions grant is never READ, the
|
||||
Backend-auth section renders read-only/hidden, and the
|
||||
auth-constraints stub above is dead code in every pass. -->
|
||||
<script type="module" src="shared/auth.js"></script>
|
||||
<script src="console-static/admin.js"></script>
|
||||
<script src="console-static/governance.js"></script>
|
||||
<script>
|
||||
window.addEventListener("load", function () {
|
||||
// Reinstate the fixture fetch now the modules (and auth.js's
|
||||
// window bridge) have evaluated — passes run after load, so every
|
||||
// shelf-open fetch flows through the fixture, not the bridge.
|
||||
window.authFetch = window.__consoleAuthFetch;
|
||||
var q = new URLSearchParams(location.search);
|
||||
if (q.get("theme") === "light")
|
||||
document.documentElement.dataset.theme = "light";
|
||||
@@ -789,108 +658,6 @@ SHELL_TEMPLATE = """<!doctype html>
|
||||
# call the same window.buildAttachmentPreview). The page frame is harness-only
|
||||
# chrome and not under review; the chips row and the pill row are.
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
# The PROXIED NODE page: the real L-shell (so the rail brand is the real
|
||||
# element, with the real shell.js click listener on it) plus the real proxy
|
||||
# shim injected exactly where proxy_index puts it -- first thing inside
|
||||
# <body>, ahead of the deferred shell.js module. caps mirror a NODE, not
|
||||
# the console: brandSub "server" is what the shim has to overwrite, and
|
||||
# leaving it "console" would make the host's /console/i check vacuous.
|
||||
PROXYBRAND_FRAME_TEMPLATE = """<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>proxied node</title>
|
||||
<link rel="stylesheet" href="shared/base.css" />
|
||||
<link rel="stylesheet" href="shared/ui-base.css" />
|
||||
<link rel="stylesheet" href="static/style.css" />
|
||||
<link rel="stylesheet" href="shared/shell.css" />
|
||||
</head>
|
||||
<body>
|
||||
<!-- SHIM:BEGIN -->
|
||||
<!-- SHIM:END -->
|
||||
<div id="header" style="display: none"><div id="status-bar"></div></div>
|
||||
<div id="main" style="padding: 18px">
|
||||
<h2 style="margin: 0 0 8px">Node dashboard</h2>
|
||||
</div>
|
||||
<div id="view-admin" style="display: none"></div>
|
||||
<script>
|
||||
window.TURNSTONE_SHELL_CAPS = { cluster: false, brandSub: "server" };
|
||||
window.TS_APP = {
|
||||
boot() {},
|
||||
getClusterState() { return { nodes: {} }; },
|
||||
onRender() {},
|
||||
};
|
||||
window.TS_ADMIN = {};
|
||||
// Record on the PARENT, which survives the frame's navigation.
|
||||
// A flag on the frame's own window dies with the document, so the
|
||||
// host would read undefined and pass -- a check that cannot fail.
|
||||
window.showHome = function () {
|
||||
try { window.parent.__showHomeRan = true; } catch (e) {}
|
||||
};
|
||||
</script>
|
||||
<script type="module" src="shared/shell.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
"""
|
||||
|
||||
# The HOST page. The shim navigates the FRAME to "/", which would destroy
|
||||
# any verdict stamped inside it -- so the surviving top page reads the
|
||||
# frame's post-navigation location and stamps its own title instead. No
|
||||
# landing page at "/" is needed (the harness root serves a directory
|
||||
# listing) and no CDP client either.
|
||||
PROXYBRAND_HOST_TEMPLATE = """<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>proxybrand livepass</title>
|
||||
<style>
|
||||
html, body { margin: 0; height: 100%; }
|
||||
iframe { width: 100%; height: 100%; border: 0; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<iframe id="frame" src="frame.html"></iframe>
|
||||
<script>
|
||||
const frame = document.getElementById("frame");
|
||||
let phase = 0;
|
||||
const fail = (r) => { phase = 9; document.title = "PROXYBRAND-FAILED-" + r; };
|
||||
|
||||
frame.addEventListener("load", () => {
|
||||
if (phase === 9) return;
|
||||
if (phase === 0) {
|
||||
const doc = frame.contentDocument;
|
||||
const brand = doc.querySelector(".rail-brand .brand-home");
|
||||
if (!brand) return fail("no-brand");
|
||||
const sub = brand.querySelector(".brand-sub");
|
||||
if (!sub) return fail("no-sub");
|
||||
const text = sub.textContent.trim();
|
||||
if (text === "server") return fail("sub-not-repointed-server");
|
||||
if (!/console/i.test(text)) return fail("sub-not-console-" + text);
|
||||
if (brand.getAttribute("aria-label") !== "Back to console")
|
||||
return fail("aria-not-repointed");
|
||||
phase = 1;
|
||||
// Click the CHILD span, as a real user does: the shim must match
|
||||
// via contains(), not target identity.
|
||||
sub.click();
|
||||
setTimeout(() => { if (phase === 1) fail("no-navigation"); }, 2000);
|
||||
return;
|
||||
}
|
||||
const path = frame.contentWindow.location.pathname;
|
||||
const ranShowHome = !!window.__showHomeRan;
|
||||
phase = 2;
|
||||
if (path !== "/") return fail("nav-" + path);
|
||||
if (ranShowHome) return fail("showhome-also-ran");
|
||||
// Sticky, mirroring fail(): a third load must not re-stamp.
|
||||
phase = 9;
|
||||
document.title = "PROXYBRAND-READY";
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
"""
|
||||
|
||||
|
||||
ATTACH_TEMPLATE = """<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
@@ -1046,165 +813,6 @@ ATTACH_TEMPLATE = """<!doctype html>
|
||||
"""
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Native paste-over-HTTP harness. Unlike the copy-affordance harness, this
|
||||
# must never stub clipboard access or dispatch a script-created paste event:
|
||||
# its purpose is to prove that the production ClipboardEvent path still sees
|
||||
# user-agent clipboard data on a non-secure origin.
|
||||
# --------------------------------------------------------------------------
|
||||
PASTE_TEMPLATE = """<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>PASTE-HTTP-BOOTING</title>
|
||||
<link rel="stylesheet" href="shared/base.css" />
|
||||
<link rel="stylesheet" href="shared/ui-base.css" />
|
||||
<link rel="stylesheet" href="shared/chat.css" />
|
||||
<style>
|
||||
body {
|
||||
margin: 0; padding: 32px;
|
||||
background: var(--bg); color: var(--fg);
|
||||
font-family: var(--font-sans, system-ui, sans-serif);
|
||||
}
|
||||
main { width: min(760px, 100%); margin: 0 auto; }
|
||||
#paste-source {
|
||||
box-sizing: border-box; width: 100%; height: 80px;
|
||||
}
|
||||
#composer-mount, #probe-status { margin-top: 16px; }
|
||||
#probe-status { white-space: pre-wrap; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<main>
|
||||
<h1>Native paste on plain HTTP</h1>
|
||||
<p>
|
||||
This passes only when a trusted paste exposes clipboard text to the
|
||||
real Composer on a non-secure HTTP origin.
|
||||
</p>
|
||||
<p>1. Select this 2001-character fixture, then copy it normally.</p>
|
||||
<textarea id="paste-source" aria-label="Paste test source"></textarea>
|
||||
<button id="select-source" type="button">Select source text</button>
|
||||
<p>2. Focus the composer and paste normally.</p>
|
||||
<div id="composer-mount"></div>
|
||||
<pre id="probe-status" role="status" aria-live="polite">Booting…</pre>
|
||||
</main>
|
||||
<script type="module">
|
||||
import { Composer } from "./shared/composer.js";
|
||||
import { PASTE_ATTACHMENT_CHARS } from "./shared/composer_paste_text.js";
|
||||
|
||||
const prefix = "TURNSTONE-PASTE-HTTP:";
|
||||
const seedText =
|
||||
prefix + "x".repeat(PASTE_ATTACHMENT_CHARS + 1 - prefix.length);
|
||||
const source = document.getElementById("paste-source");
|
||||
const status = document.getElementById("probe-status");
|
||||
source.value = seedText;
|
||||
|
||||
let copyTrusted = false;
|
||||
let paste = null;
|
||||
let attachment = null;
|
||||
let fileSettled = false;
|
||||
let failed = false;
|
||||
|
||||
function paint() {
|
||||
status.textContent = document.title + "\\n" + JSON.stringify({
|
||||
origin: location.origin,
|
||||
secureContext: window.isSecureContext,
|
||||
copyTrusted: copyTrusted,
|
||||
paste: paste,
|
||||
attachment: attachment,
|
||||
}, null, 2);
|
||||
}
|
||||
|
||||
function fail(reason) {
|
||||
if (failed) return;
|
||||
failed = true;
|
||||
document.title = "PASTE-HTTP-FAILED-" + reason;
|
||||
paint();
|
||||
}
|
||||
|
||||
function finish() {
|
||||
if (failed || !paste || !fileSettled) return;
|
||||
const checks = [
|
||||
["copy-untrusted", copyTrusted],
|
||||
["paste-untrusted", paste.trusted],
|
||||
["no-clipboard-data", paste.hasClipboardData],
|
||||
["no-text-plain", paste.hasPlainText],
|
||||
["paste-not-canceled", paste.defaultPrevented],
|
||||
["attach-count", attachment.calls === 1],
|
||||
["filename", attachment.name === "pasted-text.txt"],
|
||||
["mime", attachment.type === "text/plain"],
|
||||
["size", attachment.size === new Blob([seedText]).size],
|
||||
["content", attachment.contentMatches],
|
||||
["inline-insert", paste.inputValue === ""],
|
||||
];
|
||||
const firstFailure = checks.find(function (entry) { return !entry[1]; });
|
||||
if (firstFailure) return fail(firstFailure[0]);
|
||||
document.title = "PASTE-HTTP-READY";
|
||||
paint();
|
||||
}
|
||||
|
||||
document.addEventListener("copy", function (event) {
|
||||
copyTrusted = event.isTrusted;
|
||||
paint();
|
||||
}, true);
|
||||
|
||||
document.addEventListener("paste", function (event) {
|
||||
const observed = {
|
||||
trusted: event.isTrusted,
|
||||
hasClipboardData: !!event.clipboardData,
|
||||
hasPlainText: !!event.clipboardData &&
|
||||
Array.from(event.clipboardData.types || []).includes("text/plain"),
|
||||
};
|
||||
setTimeout(function () {
|
||||
paste = Object.assign(observed, {
|
||||
defaultPrevented: event.defaultPrevented,
|
||||
inputValue: composer.inputEl.value,
|
||||
});
|
||||
if (!attachment) fail("no-attachment");
|
||||
else finish();
|
||||
}, 0);
|
||||
});
|
||||
|
||||
const composer = new Composer(document.getElementById("composer-mount"), {
|
||||
onSend: function () {},
|
||||
placeholder: "Paste the copied fixture here…",
|
||||
attachments: {
|
||||
onAttach: function (file) {
|
||||
attachment = {
|
||||
calls: attachment ? attachment.calls + 1 : 1,
|
||||
name: file.name,
|
||||
type: file.type,
|
||||
size: file.size,
|
||||
contentMatches: false,
|
||||
};
|
||||
file.text().then(function (text) {
|
||||
attachment.contentMatches = text === seedText;
|
||||
fileSettled = true;
|
||||
finish();
|
||||
}, function () { fail("file-read"); });
|
||||
return true;
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
document.getElementById("select-source").addEventListener("click", function () {
|
||||
source.focus();
|
||||
source.select();
|
||||
});
|
||||
|
||||
if (location.protocol !== "http:") fail("not-http");
|
||||
else if (window.isSecureContext) fail("secure-context");
|
||||
else {
|
||||
document.title = "PASTE-HTTP-WAITING";
|
||||
paint();
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
"""
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Task-agent harness — the task_agent card: a task agent's sub-tool steps
|
||||
# nested under its conversation row. Driven through the REAL
|
||||
@@ -1213,24 +821,7 @@ PASTE_TEMPLATE = """<!doctype html>
|
||||
# is exercised, not just the leaf builders. The page frame is harness-only
|
||||
# chrome; the .conv-batch / task_agent card is what's under review.
|
||||
# --------------------------------------------------------------------------
|
||||
# The host seams a mounted InteractivePane provides, stubbed once for every
|
||||
# harness that drives the REAL pane (taskagent, copy). A new required seam
|
||||
# gets added HERE — a harness left with a stale stub set does not fail at
|
||||
# review time, it throws HARNESS ERROR at run time.
|
||||
PANE_STUB_JS = """\
|
||||
// Drive the REAL pane; stub only the host seams a mounted pane provides.
|
||||
const pane = new InteractivePane("demo-ws");
|
||||
pane.messagesEl = messages;
|
||||
pane.inputEl = document.createElement("textarea");
|
||||
pane.sendBtn = document.createElement("button");
|
||||
pane.isNearBottom = () => false;
|
||||
pane.scrollToBottom = () => {};
|
||||
pane.removeEmptyState = () => {};
|
||||
pane.removeThinkingIndicator = () => {};
|
||||
pane.setBusy = () => {};"""
|
||||
|
||||
TASKAGENT_TEMPLATE = (
|
||||
"""<!doctype html>
|
||||
TASKAGENT_TEMPLATE = """<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
@@ -1280,9 +871,16 @@ TASKAGENT_TEMPLATE = (
|
||||
|
||||
const messages = document.getElementById("messages");
|
||||
try {
|
||||
"""
|
||||
+ PANE_STUB_JS
|
||||
+ """
|
||||
// Drive the REAL pane; stub only the host seams a mounted pane provides.
|
||||
const pane = new InteractivePane("demo-ws");
|
||||
pane.messagesEl = messages;
|
||||
pane.inputEl = document.createElement("textarea");
|
||||
pane.sendBtn = document.createElement("button");
|
||||
pane.isNearBottom = () => false;
|
||||
pane.scrollToBottom = () => {};
|
||||
pane.removeEmptyState = () => {};
|
||||
pane.removeThinkingIndicator = () => {};
|
||||
pane.setBusy = () => {};
|
||||
const ev = (e) => pane.handleEvent(e);
|
||||
|
||||
// ?recall=1: exercise the RECALL path — replayHistory rebuilding the
|
||||
@@ -1431,266 +1029,6 @@ TASKAGENT_TEMPLATE = (
|
||||
</body>
|
||||
</html>
|
||||
"""
|
||||
)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# Copy harness — the copy-to-clipboard affordances over the REAL pane. The
|
||||
# bubbles come from the REAL replayHistory / handleEvent paths so the copy
|
||||
# sources are the ones production stashes (_copySource, the mermaid / table
|
||||
# data attributes), and the probes drive the REAL buttons and key path and
|
||||
# compare what landed on the (stubbed) clipboard byte-exact against the
|
||||
# source.
|
||||
# --------------------------------------------------------------------------
|
||||
COPY_TEMPLATE = (
|
||||
"""<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>copy livepass</title>
|
||||
<link rel="stylesheet" href="shared/base.css" />
|
||||
<link rel="stylesheet" href="shared/ui-base.css" />
|
||||
<link rel="stylesheet" href="shared/chat.css" />
|
||||
<link rel="stylesheet" href="shared/conversation.css" />
|
||||
<link rel="stylesheet" href="shared/cards.css" />
|
||||
<link rel="stylesheet" href="shared/interactive.css" />
|
||||
<style>
|
||||
/* Harness-only framing (NOT under review) — a plausible pane context. */
|
||||
body {
|
||||
padding: 24px; margin: 0; background: var(--bg); color: var(--ink);
|
||||
font-family: var(--font-sans, system-ui, sans-serif);
|
||||
}
|
||||
.demo-frame { max-width: 720px; margin: 0 auto; }
|
||||
.demo-label {
|
||||
font: 11px var(--font-mono, monospace); color: var(--ink-3);
|
||||
text-transform: uppercase; letter-spacing: 0.08em; margin: 0 0 8px;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="demo-frame">
|
||||
<div class="demo-label">conversation — copy affordances (real InteractivePane)</div>
|
||||
<div class="messages" id="messages"></div>
|
||||
</div>
|
||||
<script>
|
||||
window.toast = { error: function (m) { console.log("toast:", m); } };
|
||||
window.authFetch = function () {
|
||||
return Promise.resolve({
|
||||
ok: true,
|
||||
json: function () { return Promise.resolve({}); },
|
||||
text: function () { return Promise.resolve(""); },
|
||||
});
|
||||
};
|
||||
// Deterministic clipboard: record instead of writing. localhost is a
|
||||
// secure context so copyTextToClipboard takes the async-API branch and
|
||||
// hits this stub; force isSecureContext for any odd serving setup.
|
||||
window.__copied = [];
|
||||
try {
|
||||
Object.defineProperty(window, "isSecureContext", { value: true });
|
||||
} catch (e) { /* already true */ }
|
||||
try {
|
||||
Object.defineProperty(navigator, "clipboard", {
|
||||
value: {
|
||||
writeText: function (t) {
|
||||
window.__copied.push(t);
|
||||
return Promise.resolve();
|
||||
},
|
||||
},
|
||||
configurable: true,
|
||||
});
|
||||
} catch (e) {
|
||||
document.title = "COPY-FAILED-clipboard-stub";
|
||||
}
|
||||
</script>
|
||||
<script type="module">
|
||||
import { InteractivePane } from "./shared/interactive.js";
|
||||
const q = new URLSearchParams(location.search);
|
||||
if (q.get("theme") === "light")
|
||||
document.documentElement.dataset.theme = "light";
|
||||
|
||||
const FENCE_SRC = 'def stash(depth):\\n total = 0\\n for k in range(depth):\\n total += k\\n return total';
|
||||
const TABLE_SRC = '| node | state |\\n|---|:--:|\\n| flat | idle |\\n| blck | busy |';
|
||||
const MERMAID_SRC = 'graph TD\\n A --> B\\n B --> C';
|
||||
const MD_ONE =
|
||||
'First reply with a fence and a table.\\n\\n' +
|
||||
'```python\\n' + FENCE_SRC + '\\n```\\n\\n' +
|
||||
TABLE_SRC + '\\n\\nTrailing prose under the table.';
|
||||
const MD_TWO =
|
||||
'Second reply with a diagram.\\n\\n' +
|
||||
'```mermaid\\n' + MERMAID_SRC + '\\n```\\n\\n' +
|
||||
'And `inline code` after it.';
|
||||
const MD_LIVE =
|
||||
'Streamed reply: the **live** turn, so the retry holder lands here.';
|
||||
|
||||
const messages = document.getElementById("messages");
|
||||
const fail = (r) => { document.title = "COPY-FAILED-" + r; };
|
||||
try {
|
||||
"""
|
||||
+ PANE_STUB_JS
|
||||
+ """
|
||||
|
||||
pane.replayHistory([
|
||||
{ role: "user", content: "Show me the stash helper and the node table." },
|
||||
{ role: "assistant", content: MD_ONE },
|
||||
{ role: "user", content: "Now the flow as a diagram, please." },
|
||||
{ role: "assistant", content: MD_TWO },
|
||||
]);
|
||||
// A live streamed turn on top — the retry holder must land on this
|
||||
// bubble WITHOUT stripping its (or any) copy button.
|
||||
pane.handleEvent({ type: "state_change", state: "running" });
|
||||
for (let k = 0; k < MD_LIVE.length; k += 16)
|
||||
pane.handleEvent({ type: "content", text: MD_LIVE.slice(k, k + 16) });
|
||||
pane.handleEvent({ type: "stream_end" });
|
||||
pane.handleEvent({ type: "state_change", state: "idle" });
|
||||
|
||||
const hover = (el) =>
|
||||
el.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
|
||||
const fabEl = () => document.querySelector(".block-copy-btn");
|
||||
|
||||
// Let the streamed bubble's rAF render + retry attach settle.
|
||||
setTimeout(async () => {
|
||||
try {
|
||||
const bubbles = messages.querySelectorAll(".msg.assistant");
|
||||
const bars = messages.querySelectorAll(
|
||||
".msg.assistant .msg-actions .msg-copy-btn",
|
||||
);
|
||||
if (bubbles.length !== 3) return fail("bubbles" + bubbles.length);
|
||||
if (bars.length !== 3) return fail("bars" + bars.length);
|
||||
const last = bubbles[bubbles.length - 1];
|
||||
if (!last.querySelector(".msg-retry-btn"))
|
||||
return fail("no-retry-on-holder");
|
||||
if (!last.querySelector(".msg-copy-btn"))
|
||||
return fail("holder-lost-copy");
|
||||
|
||||
// Block probes: hover reveals the floating button; a click must
|
||||
// land the byte-exact SOURCE on the clipboard.
|
||||
const probes = [
|
||||
[messages.querySelector(".msg.assistant pre"), FENCE_SRC, "fence"],
|
||||
[messages.querySelector(".table-wrap"), TABLE_SRC, "table"],
|
||||
[messages.querySelector(".mermaid-container"), MERMAID_SRC, "mermaid"],
|
||||
];
|
||||
// &bare=1 — diagnostic state: no probe clicks, no repositioning;
|
||||
// one hover on the fence and stop. Splits "the probe cycle
|
||||
// corrupts the button's paint" from "it never paints here".
|
||||
if (q.get("bare") === "1") {
|
||||
hover(probes[0][0]);
|
||||
document.title = "COPY-BARE";
|
||||
return;
|
||||
}
|
||||
|
||||
// &kbd=1 — the keyboard path: Enter on a FOCUSED block copies
|
||||
// that block's source directly. Blocks are focusable (tabindex=0
|
||||
// from the fence / table / mermaid renders), the outcome flashes
|
||||
// on the block itself, and the floating button — pointer-only —
|
||||
// must stay out of it entirely (never created, never revealed).
|
||||
if (q.get("kbd") === "1") {
|
||||
const tw = messages.querySelector(".table-wrap");
|
||||
if (!tw) return fail("kbd-no-block");
|
||||
tw.focus();
|
||||
const focused = document.activeElement === tw;
|
||||
tw.dispatchEvent(
|
||||
new KeyboardEvent("keydown", { key: "Enter", bubbles: true }),
|
||||
);
|
||||
await new Promise((r) => setTimeout(r, 0));
|
||||
const copied =
|
||||
window.__copied[window.__copied.length - 1] === TABLE_SRC;
|
||||
const flashed = tw.classList.contains("is-copied");
|
||||
const fabStaysOut =
|
||||
!fabEl() || !fabEl().classList.contains("is-visible");
|
||||
document.title =
|
||||
focused && copied && flashed && fabStaysOut
|
||||
? "COPY-KBD-READY"
|
||||
: "COPY-KBD-FAILED-" +
|
||||
[
|
||||
focused ? "" : "focus",
|
||||
copied ? "" : "copy",
|
||||
flashed ? "" : "flash",
|
||||
fabStaysOut ? "" : "fab",
|
||||
]
|
||||
.filter(Boolean)
|
||||
.join("-");
|
||||
return;
|
||||
}
|
||||
|
||||
// &flash=1 — the VISUAL state, screenshot-only: skip the probes so
|
||||
// the fence hover is the floating button's FIRST show. Returning
|
||||
// the button to an already-visited position stops it PAINTING in
|
||||
// headless captures (visible + hit-testable, no pixels — a stale
|
||||
// compositor tile; bisected via &stepmax). Function and pixels
|
||||
// are therefore split: the probe run (no flash) is the verdict,
|
||||
// this state is the picture.
|
||||
if (q.get("flash") === "1") {
|
||||
bars[bars.length - 1].focus();
|
||||
hover(probes[0][0]);
|
||||
const fab = fabEl();
|
||||
if (!fab) return fail("no-fab-visual");
|
||||
fab.classList.add("is-copied");
|
||||
fab.title = "Copied";
|
||||
// Freeze: the capture pipeline synthesizes a pointer event
|
||||
// outside the block at screenshot time, which would hide the
|
||||
// button (correct in production). Capture-phase stops starve
|
||||
// the module's delegated listeners for the capture.
|
||||
for (const t of ["mouseover", "scroll"])
|
||||
document.addEventListener(t, (e) => e.stopPropagation(), true);
|
||||
document.title = "COPY-VISUAL";
|
||||
return;
|
||||
}
|
||||
// &stepmax=N — diagnostic: stop after the Nth interaction (hovers
|
||||
// and clicks count) and stamp COPY-STEP-N, so a paint regression
|
||||
// can be bisected to the interaction that triggers it.
|
||||
let step = 0;
|
||||
const stepMax = parseInt(q.get("stepmax") || "999", 10);
|
||||
const gate = () => {
|
||||
step += 1;
|
||||
if (step > stepMax) {
|
||||
document.title = "COPY-STEP-" + (step - 1);
|
||||
throw { __stop: true };
|
||||
}
|
||||
};
|
||||
let done = 0;
|
||||
for (const [el, want, name] of probes) {
|
||||
if (!el) return fail("no-" + name);
|
||||
gate();
|
||||
hover(el);
|
||||
const fab = fabEl();
|
||||
if (!fab || !fab.classList.contains("is-visible"))
|
||||
return fail("fab-hidden-" + name);
|
||||
gate();
|
||||
fab.click();
|
||||
await new Promise((r) => setTimeout(r, 0));
|
||||
const got = window.__copied[window.__copied.length - 1];
|
||||
if (got !== want) {
|
||||
console.log("copy mismatch", name, JSON.stringify(got));
|
||||
return fail("source-" + name);
|
||||
}
|
||||
done += 1;
|
||||
}
|
||||
|
||||
// Bubble probe: the whole raw markdown, fences and pipes intact.
|
||||
gate();
|
||||
bars[0].click();
|
||||
await new Promise((r) => setTimeout(r, 0));
|
||||
if (window.__copied[window.__copied.length - 1] !== MD_ONE)
|
||||
return fail("bubble-source");
|
||||
|
||||
document.title = "COPY-READY-" + bars.length + "-" + done;
|
||||
} catch (e) {
|
||||
if (!(e && e.__stop)) {
|
||||
console.log("copy harness error", e);
|
||||
fail("error");
|
||||
}
|
||||
}
|
||||
}, 400);
|
||||
} catch (e) {
|
||||
messages.textContent = "HARNESS ERROR: " + e.message;
|
||||
fail("error");
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
"""
|
||||
)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
@@ -2132,24 +1470,12 @@ def build(out: Path) -> None:
|
||||
(att / "livepass.html").write_text(ATTACH_TEMPLATE, encoding="utf-8")
|
||||
print(f"{att}/livepass.html — composer chips + message attachment pills")
|
||||
|
||||
paste = out / "paste"
|
||||
paste.mkdir(parents=True, exist_ok=True)
|
||||
symlink(paste / "shared", ROOT / "turnstone/shared_static")
|
||||
(paste / "livepass.html").write_text(PASTE_TEMPLATE, encoding="utf-8")
|
||||
print(f"{paste}/livepass.html — trusted native paste on insecure HTTP")
|
||||
|
||||
ta = out / "taskagent"
|
||||
ta.mkdir(parents=True, exist_ok=True)
|
||||
symlink(ta / "shared", ROOT / "turnstone/shared_static")
|
||||
(ta / "livepass.html").write_text(TASKAGENT_TEMPLATE, encoding="utf-8")
|
||||
print(f"{ta}/livepass.html — task_agent card (real Pane.handleEvent routing)")
|
||||
|
||||
cp = out / "copy"
|
||||
cp.mkdir(parents=True, exist_ok=True)
|
||||
symlink(cp / "shared", ROOT / "turnstone/shared_static")
|
||||
(cp / "livepass.html").write_text(COPY_TEMPLATE, encoding="utf-8")
|
||||
print(f"{cp}/livepass.html — copy affordances (bubble bars + block button)")
|
||||
|
||||
pf = out / "perf"
|
||||
pf.mkdir(parents=True, exist_ok=True)
|
||||
symlink(pf / "shared", ROOT / "turnstone/shared_static")
|
||||
@@ -2157,17 +1483,6 @@ def build(out: Path) -> None:
|
||||
(pf / "livepass.html").write_text(PERF_TEMPLATE, encoding="utf-8")
|
||||
print(f"{pf}/livepass.html — long-session perf baseline (real InteractivePane)")
|
||||
|
||||
pb = out / "proxybrand"
|
||||
pb.mkdir(parents=True, exist_ok=True)
|
||||
symlink(pb / "shared", ROOT / "turnstone/shared_static")
|
||||
symlink(pb / "static", ROOT / "turnstone/ui/static")
|
||||
shim = "<script>" + extract_proxy_shim() + "</script>"
|
||||
(pb / "frame.html").write_text(
|
||||
inject(PROXYBRAND_FRAME_TEMPLATE, "SHIM", shim), encoding="utf-8"
|
||||
)
|
||||
(pb / "livepass.html").write_text(PROXYBRAND_HOST_TEMPLATE, encoding="utf-8")
|
||||
print(f"{pb}/livepass.html — back-to-console brand (real shell.js + real shim)")
|
||||
|
||||
|
||||
class _PerfStore:
|
||||
"""Rendezvous for the perf page's POSTed JSON report."""
|
||||
@@ -2398,12 +1713,6 @@ def main() -> None:
|
||||
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
ap.add_argument("--out", type=Path, default=Path("/tmp/livepass"))
|
||||
ap.add_argument("--serve", type=int, metavar="PORT")
|
||||
ap.add_argument(
|
||||
"--bind",
|
||||
default="127.0.0.1",
|
||||
metavar="HOST",
|
||||
help="listen address for --serve (use 0.0.0.0 for a manual insecure-origin pass)",
|
||||
)
|
||||
ap.add_argument("--perf", action="store_true", help="run the perf baseline and exit")
|
||||
ap.add_argument(
|
||||
"--perf-n",
|
||||
@@ -2421,9 +1730,8 @@ def main() -> None:
|
||||
import functools
|
||||
|
||||
handler = functools.partial(_HarnessHandler, directory=str(args.out))
|
||||
display_host = "localhost" if args.bind == "127.0.0.1" else args.bind
|
||||
print(f"serving {args.out} on http://{display_host}:{args.serve}/ — Ctrl+C stops")
|
||||
http.server.ThreadingHTTPServer((args.bind, args.serve), handler).serve_forever()
|
||||
print(f"serving {args.out} on http://localhost:{args.serve}/ — Ctrl+C stops")
|
||||
http.server.ThreadingHTTPServer(("127.0.0.1", args.serve), handler).serve_forever()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
# Entra config for the Entra e2e / spike harnesses. Copy to `.env` (gitignored)
|
||||
# and fill in from your tenant. `entra_setup.sh setup` creates the app
|
||||
# registrations and writes a populated `.env` for you.
|
||||
#
|
||||
# cp scripts/obo-e2e/.env.example scripts/obo-e2e/.env
|
||||
# # then edit, or run: ./scripts/obo-e2e/entra_setup.sh setup
|
||||
|
||||
export ENTRA_TENANT_ID=<tenant-guid-or-domain>
|
||||
export ENTRA_CLIENT_ID=<turnstone-spike-app-client-id>
|
||||
export ENTRA_CLIENT_SECRET=<client-secret>
|
||||
export SPIKE_AUDIENCE_A=api://<resource-app-a-guid> # a consented resource
|
||||
export SPIKE_AUDIENCE_B=api://<resource-app-b-guid> # a second consented resource
|
||||
export SPIKE_AUDIENCE_UNCONSENTED=api://<resource-app-c-guid> # NOT granted (negative case)
|
||||
export SPIKE_RUN_OBO=1
|
||||
# export SPIKE_PORT=8765 # redirect-listener port (default 8765)
|
||||
# export SPIKE_CALLBACK_FILE=/tmp/obo_cb.txt # remote-browser mode: paste the redirect URL here
|
||||
|
||||
# The Keycloak / OSS-path harness needs no config — keycloak_e2e.sh sets
|
||||
# everything and stands up an ephemeral container.
|
||||
@@ -1,214 +0,0 @@
|
||||
# OBO e2e harnesses — single-credential MCP token minting (`auth_type=oauth_obo`)
|
||||
|
||||
Manual test harnesses for the `oauth_obo` feature (issue #551). They exercise
|
||||
the **real** Turnstone mint path (`get_obo_access_token_classified` →
|
||||
`_obo_mint_entra` / `_obo_mint_rfc8693`) against a real identity provider — not
|
||||
mocks, not the unit suite. Two grant legs:
|
||||
|
||||
- **Entra** (`entra_e2e.py`) — real tenant, one interactive sign-in.
|
||||
- **Keycloak / RFC 8693** (`keycloak_e2e.py` + `.sh`) — ephemeral docker, fully
|
||||
headless.
|
||||
|
||||
There is also `entra_spike.py` (raw-OAuth **wire** probe, pre-implementation
|
||||
reference) and `entra_setup.sh` (creates the Entra app registrations + writes a
|
||||
populated `.env`).
|
||||
|
||||
**Secrets:** these read config from env. Real credentials live in a **gitignored
|
||||
`.env`** (copy `.env.example`); nothing tenant-specific is committed. The only
|
||||
literal secret in the tree is the ephemeral Keycloak container's throwaway
|
||||
`spike-secret`, which lives and dies with the container.
|
||||
|
||||
Not part of CI — run by hand when validating the feature against a live IdP.
|
||||
|
||||
## `entra_e2e.py` — end-to-end product exercise (post-implementation)
|
||||
|
||||
`entra_spike.py` verified the raw OAuth WIRE (before code existed). `entra_e2e.py`
|
||||
verifies the SHIPPED Turnstone code: it does a real Entra login, feeds the
|
||||
credential through the real `MCPTokenStore.upsert_oidc_credential` (the call the
|
||||
OIDC callback makes on capture), then drives the real
|
||||
`get_obo_access_token_classified` → `_obo_mint_entra` against the live Entra token
|
||||
endpoint. Checks E1–E7: real mint + aud claim, cache-hit (0 Entra calls),
|
||||
single-credential→audiences A&B, rotation write-back, force_refresh re-mint,
|
||||
unconsented-audience classification with the credential surviving, and
|
||||
flush→re-mint. Reuses the same `.env` and interactive login (SPIKE_CALLBACK_FILE
|
||||
for remote browser).
|
||||
|
||||
```bash
|
||||
source scripts/obo-e2e/.env
|
||||
uv run python scripts/obo-e2e/entra_e2e.py
|
||||
# one interactive sign-in; E1–E7 then run against the real product code. Results below.
|
||||
```
|
||||
|
||||
Results — RUN 2026-07-12 on the real tenant, ALL VERIFIED (exit 0): capture
|
||||
persisted; E1 mint A (aud=A app-id, cache row refresh_token_ct NULL); E2 cache
|
||||
hit (0 extra Entra calls); E3 mint B from the SAME credential (aud=B app-id); E4
|
||||
rotation write-back (RT rotated 2040→2091 chars, newest persisted); E5
|
||||
force_refresh re-mint (1 Entra call); E6 unconsented C → refresh_failed and the
|
||||
credential SURVIVES; E7 flush→re-mint. The real `get_obo_access_token_classified`
|
||||
→ `_obo_mint_entra` path against the live Entra token endpoint.
|
||||
|
||||
## `keycloak_e2e.py` + `keycloak_e2e.sh` — OSS path (RFC 8693), headless
|
||||
|
||||
The rfc8693 equivalent of `entra_e2e.py`: `keycloak_e2e.sh` spins up ephemeral
|
||||
Keycloak, configures the realm (turnstone client with standard token exchange,
|
||||
mcp-a/b/c clients, aud-mcp-a/b audience scopes, a test user), runs the harness
|
||||
against the real `get_obo_access_token_classified` → `_obo_mint_rfc8693`
|
||||
(refresh grant → token exchange), then tears down. No browser (password grant).
|
||||
|
||||
```bash
|
||||
./scripts/obo-e2e/keycloak_e2e.sh
|
||||
```
|
||||
|
||||
Results — RUN 2026-07-12, ALL VERIFIED: capture persisted; E1 mint A
|
||||
(refresh→exchange, aud=mcp-a, cache row refresh_token_ct NULL); E2 cache hit (0
|
||||
extra KC calls); E3 mint B from the SAME credential (aud=mcp-b); E4 rotation
|
||||
write-back (KC rotated the RT on the refresh leg, newest persisted); E5
|
||||
force_refresh re-mint (**2 KC calls** = the two-leg chain); E6 unconsented C →
|
||||
refresh_failed_transient (KC returns invalid_request for a missing audience
|
||||
scope → classified transient; credential SURVIVES either way); E7 flush→re-mint.
|
||||
Gotcha: dev-mode Keycloak boot is slow on a loaded host — the script now waits on
|
||||
kcadm auth (up to ~6 min) rather than a fixed sleep. Port 8091 (8090 = the dev
|
||||
console).
|
||||
|
||||
## Leg 1 — Entra (`entra_spike.py`) — NEEDS TENANT ACCESS
|
||||
|
||||
### Tenant / app-registration setup (one-time, ~15 min)
|
||||
|
||||
1. **Spike client app** (stands in for Turnstone's OIDC app registration):
|
||||
- New app registration, single tenant. Platform **Web**, redirect URI
|
||||
`http://localhost:8765/callback`. Create a **client secret**.
|
||||
2. **Two resource apps** (stand in for MCP servers A and B):
|
||||
- New app registrations `spike-mcp-a`, `spike-mcp-b`. In each:
|
||||
**Expose an API** → set Application ID URI (`api://<guid>`) → add a scope
|
||||
(e.g. `mcp.access`).
|
||||
3. **Delegated grants** (this is metaclassing's "proper tenant and app reg setup"):
|
||||
- On the spike client app → **API permissions** → add delegated permission to
|
||||
`spike-mcp-a` and `spike-mcp-b` scopes → **Grant admin consent**.
|
||||
- Optionally also add the spike client's app id to each resource app's
|
||||
`preAuthorizedApplications` (Expose an API → Add a client application) to
|
||||
compare against pure admin consent.
|
||||
4. **Unconsented control** (for V5): a third resource app `spike-mcp-c` with an
|
||||
exposed API but NO permission granted to the spike client.
|
||||
|
||||
### Run
|
||||
|
||||
```bash
|
||||
export ENTRA_TENANT_ID=... ENTRA_CLIENT_ID=... ENTRA_CLIENT_SECRET=...
|
||||
export SPIKE_AUDIENCE_A=api://<a-guid> SPIKE_AUDIENCE_B=api://<b-guid>
|
||||
export SPIKE_AUDIENCE_UNCONSENTED=api://<c-guid> # optional (V5)
|
||||
export SPIKE_RUN_OBO=1 # optional (V6)
|
||||
uv run python scripts/obo-e2e/entra_spike.py
|
||||
```
|
||||
|
||||
A browser opens for one interactive login (any tenant user). Everything after is
|
||||
non-interactive — that IS the feature.
|
||||
|
||||
### What each check pins down
|
||||
|
||||
| Check | Design assumption it verifies |
|
||||
| --- | --- |
|
||||
| V1 | `offline_access` on the login yields a client-bound RT (capture layer) |
|
||||
| V2/V3 | ONE RT redeems for access tokens of DIFFERENT audiences (`scope=<aud>/.default`) — the load-bearing Entra behavior |
|
||||
| V4 | rotation semantics → whether RT write-back on every mint is convenience or correctness-critical |
|
||||
| V5 | unconsented audience fails `AADSTS65001 consent_required` → maps to the reconnect-rail fallback, never a silent failure |
|
||||
| V6 | OBO jwt-bearer middle-tier variant works with the same app registration (comparison data only) |
|
||||
|
||||
Also record (manual): whether Conditional Access / MFA policies in the tenant
|
||||
produce `interaction_required` on redemption — that's the fallback path's other
|
||||
trigger.
|
||||
|
||||
### Results — RUN 2026-07-11 on a real tenant, ALL SIX VERIFIED
|
||||
|
||||
Tenant: personal default directory (Global Admin), user is an MSA member.
|
||||
Setup via `entra_setup.sh setup`; V3 initially failed (see gotcha below),
|
||||
passed after fixing the grant. Second run: V1-V6 all VERIFIED, exit 0.
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| V1 offline_access login -> RT | VERIFIED (confidential client + PKCE, RT ~2KB) |
|
||||
| V2 RT -> audience A token | VERIFIED (`aud=<A app guid>`, ~70 min TTL, new RT returned) |
|
||||
| V3 SAME RT -> audience B token | **VERIFIED — the load-bearing claim: one RT, many audiences** |
|
||||
| V4 rotation | VERIFIED: RT rotates on every redemption, but the OLD RT stays valid (reuse HTTP 200) -> write-back-newest is required; races are benign on Entra |
|
||||
| V5 unconsented audience | VERIFIED: `invalid_grant` + `AADSTS65001` (error_codes=[65001]) -> clean mapping to the reconnect-rail fallback |
|
||||
| V6 OBO jwt-bearer variant | VERIFIED: middle-tier shape also works with the same app registration |
|
||||
|
||||
**Operator gotcha (feeds #682 + product docs):** `az ad app permission
|
||||
admin-consent` run immediately after SP creation SILENTLY skips
|
||||
not-yet-propagated resource SPs — grant A landed, grant B didn't, and the only
|
||||
symptom was AADSTS65001 at redemption. Verify grants after consent
|
||||
(`oauth2PermissionGrants` filter on the client SP) or write them directly with
|
||||
`az ad app permission grant --id <client> --api <resource> --scope <scope>`.
|
||||
Product-side implication: a missing tenant grant for a NEW oauth_obo server
|
||||
surfaces as AADSTS65001 -> the same reconnect-rail path as revocation; the
|
||||
admin docs must say "grant first, then add the server".
|
||||
|
||||
## Leg 2 — Keycloak RFC 8693 (portability check) — runnable locally
|
||||
|
||||
Ephemeral `quay.io/keycloak/keycloak:26.3` (`start-dev`, port 8089), realm
|
||||
`spike`, confidential client `turnstone` with **standard token exchange**
|
||||
enabled, resource clients `mcp-a`/`mcp-b`, user `alice`. Pipeline mirrors the
|
||||
product design for a generic-8693 IdP:
|
||||
|
||||
```
|
||||
stored user RT --(refresh grant)--> user AT --(RFC 8693 exchange, audience=mcp-X)--> audience-scoped AT
|
||||
```
|
||||
|
||||
i.e. the per-user credential stays ONE refresh token; per-server tokens are
|
||||
minted via standard token exchange instead of Entra's multi-resource RT
|
||||
redemption. Same substrate, different grant leg.
|
||||
|
||||
### Results — RUN 2026-07-11, VERIFIED (Keycloak 26.3, ephemeral)
|
||||
|
||||
```
|
||||
alice ONE stored RT
|
||||
-> refresh grant -> user AT (azp=turnstone); RT ROTATED on refresh
|
||||
-> 8693 exchange audience=mcp-a scope=aud-mcp-a -> AT aud=mcp-a user=alice 300s, NO RT
|
||||
-> 8693 exchange audience=mcp-b scope=aud-mcp-b -> AT aud=mcp-b (same subject AT)
|
||||
negative control audience=mcp-c -> invalid_client "Audience not found"
|
||||
```
|
||||
|
||||
Findings that feed the design:
|
||||
1. **One per-user credential -> N audience tokens: VERIFIED on a second IdP.**
|
||||
The substrate is portable; only the grant leg differs per IdP.
|
||||
2. **Exchanged tokens are cache-shaped** (short TTL, no RT) — per-server
|
||||
`mcp_user_tokens` rows as short-lived mint cache is the right model.
|
||||
3. **RT rotation happens here too** — newest-RT write-back on every redemption
|
||||
is a correctness requirement of the capture layer, not an Entra quirk.
|
||||
4. **The IdP-side "delegated grant" has a per-IdP shape**: Entra = API
|
||||
permissions + admin consent; Keycloak = audience client scopes attached to
|
||||
the requester client (optional scopes activate via `scope=` at exchange).
|
||||
Operator runbooks are per-IdP (#682 pattern), code is not.
|
||||
5. Gotchas hit: KC user needs a complete profile for direct grant ("Account is
|
||||
not fully set up"); optional audience scope must be requested explicitly or
|
||||
the exchange 400s with "Requested audience not available".
|
||||
|
||||
Repro (ephemeral, ~2 min):
|
||||
|
||||
```bash
|
||||
docker run -d --name kc-obo-spike -p 127.0.0.1:8089:8080 \
|
||||
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
|
||||
quay.io/keycloak/keycloak:26.3 start-dev
|
||||
KC="docker exec kc-obo-spike /opt/keycloak/bin/kcadm.sh"
|
||||
$KC config credentials --server http://localhost:8080 --realm master --user admin --password admin
|
||||
$KC create realms -s realm=spike -s enabled=true
|
||||
$KC create clients -r spike -s clientId=turnstone -s enabled=true -s publicClient=false \
|
||||
-s secret=spike-secret -s directAccessGrantsEnabled=true \
|
||||
-s 'attributes={"standard.token.exchange.enabled":"true"}'
|
||||
$KC create clients -r spike -s clientId=mcp-a -s enabled=true -s publicClient=false -s secret=x
|
||||
$KC create clients -r spike -s clientId=mcp-b -s enabled=true -s publicClient=false -s secret=x
|
||||
$KC create users -r spike -s username=alice -s enabled=true -s email=a@s.test \
|
||||
-s emailVerified=true -s firstName=A -s lastName=S
|
||||
$KC set-password -r spike --username alice --new-password alice-pw
|
||||
TURNSTONE_UUID=$($KC get clients -r spike -q clientId=turnstone --fields id --format csv --noquotes)
|
||||
for t in mcp-a mcp-b; do
|
||||
SID=$($KC create client-scopes -r spike -s name=aud-$t -s protocol=openid-connect -i)
|
||||
$KC create client-scopes/$SID/protocol-mappers/models -r spike -s name=aud-$t \
|
||||
-s protocol=openid-connect -s protocolMapper=oidc-audience-mapper \
|
||||
-s "config={\"included.client.audience\":\"$t\",\"access.token.claim\":\"true\"}"
|
||||
$KC update clients/$TURNSTONE_UUID/optional-client-scopes/$SID -r spike
|
||||
done
|
||||
# then: password grant -> refresh grant -> token-exchange with
|
||||
# grant_type=urn:ietf:params:oauth:grant-type:token-exchange,
|
||||
# subject_token=<user AT>, subject_token_type=...:access_token,
|
||||
# audience=mcp-a, scope=aud-mcp-a
|
||||
```
|
||||
@@ -1,286 +0,0 @@
|
||||
"""End-to-end exercise of the oauth_obo feature against a REAL Entra tenant.
|
||||
|
||||
Unlike ``entra_spike.py`` (which verified the raw OAuth wire shapes), this
|
||||
drives the ACTUAL Turnstone product code — real ``MCPTokenStore``, real
|
||||
``get_obo_access_token_classified`` → ``_obo_mint_entra`` → the real Entra
|
||||
token endpoint — so a green run proves the shipped mint engine works against
|
||||
live Entra, not just that the protocol does.
|
||||
|
||||
Flow:
|
||||
1. Interactive Entra login (auth-code + PKCE + offline_access) → a real
|
||||
refresh credential. This is what ``handle_oidc_callback`` receives.
|
||||
2. Persist it via ``MCPTokenStore.upsert_oidc_credential`` — the exact call
|
||||
the OIDC callback makes on capture (auth.py). The rest of the callback
|
||||
(JWKS validation, user provisioning) is OIDC-generic and unit-tested; the
|
||||
novel path is capture + mint, which this exercises for real.
|
||||
3. Seed real ``oauth_obo`` ``mcp_servers`` rows (audiences A/B consented, C
|
||||
not) and drive ``get_obo_access_token_classified`` — the real dispatch-time
|
||||
entry point — asserting on the minted tokens, cache, rotation, and
|
||||
classification.
|
||||
|
||||
Checks (VERIFIED / FAILED per line):
|
||||
E1 mint for audience A → kind=token; decoded aud == A; cache row written with
|
||||
refresh_token_ct NULL (cache, not custody); expires_at set
|
||||
E2 second call for A → cache hit, ZERO additional Entra calls
|
||||
E3 mint for audience B from the SAME captured credential → aud == B
|
||||
(the single-credential-many-audiences thesis, through the real engine)
|
||||
E4 rotation write-back: the stored credential holds the newest refresh token
|
||||
E5 force_refresh → a fresh mint (Entra call count increments)
|
||||
E6 unconsented audience C → NOT kind=token, and the shared credential SURVIVES
|
||||
(never auto-deleted — the load-bearing custody invariant)
|
||||
E7 cache flush → re-mint: deleting the cache row makes the next call re-mint
|
||||
|
||||
Run:
|
||||
source scripts/obo-e2e/.env
|
||||
uv run python scripts/obo-e2e/entra_e2e.py
|
||||
Env (from .env): ENTRA_TENANT_ID, ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRET,
|
||||
SPIKE_AUDIENCE_A, SPIKE_AUDIENCE_B, SPIKE_AUDIENCE_UNCONSENTED, SPIKE_PORT.
|
||||
Remote browser: set SPIKE_CALLBACK_FILE to paste the redirect URL (as before).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import base64
|
||||
import os
|
||||
import sys
|
||||
import tempfile
|
||||
from types import SimpleNamespace
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
|
||||
# Reuse the verified interactive-login machinery from the wire spike.
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
from entra_spike import interactive_login, jwt_claims_unverified, redact # noqa: E402
|
||||
|
||||
from turnstone.core.mcp_crypto import ( # noqa: E402
|
||||
MCPTokenCipher,
|
||||
MCPTokenCipherConfig,
|
||||
MCPTokenStore,
|
||||
)
|
||||
from turnstone.core.mcp_oauth import get_obo_access_token_classified # noqa: E402
|
||||
from turnstone.core.oidc import OIDCConfig # noqa: E402
|
||||
from turnstone.core.storage._sqlite import SQLiteBackend # noqa: E402
|
||||
|
||||
USER = "e2e-user"
|
||||
RESULTS: list[tuple[str, str]] = []
|
||||
|
||||
|
||||
def record(status: str, msg: str) -> None:
|
||||
RESULTS.append((status, msg))
|
||||
print(f"[{status:>8}] {msg}")
|
||||
|
||||
|
||||
def aud_matches(token: str, want_audience: str) -> tuple[bool, str]:
|
||||
"""Compare a minted access token's aud claim to the configured audience.
|
||||
|
||||
Entra returns aud as the bare app-id GUID or the full ``api://<guid>`` URI;
|
||||
accept either.
|
||||
"""
|
||||
claims = jwt_claims_unverified(token)
|
||||
aud = str(claims.get("aud", "<none>"))
|
||||
want = want_audience.removeprefix("api://")
|
||||
return aud in (want, want_audience), aud
|
||||
|
||||
|
||||
class _CountingClient:
|
||||
"""Wraps httpx.AsyncClient, counting token-endpoint POSTs so cache hits
|
||||
(which must issue zero) are observable."""
|
||||
|
||||
def __init__(self, inner: httpx.AsyncClient) -> None:
|
||||
self._inner = inner
|
||||
self.posts = 0
|
||||
|
||||
async def post(self, *args: Any, **kwargs: Any) -> httpx.Response:
|
||||
self.posts += 1
|
||||
return await self._inner.post(*args, **kwargs)
|
||||
|
||||
|
||||
def _make_app_state(
|
||||
storage: SQLiteBackend,
|
||||
store: MCPTokenStore,
|
||||
oidc_config: OIDCConfig,
|
||||
http_client: _CountingClient,
|
||||
) -> SimpleNamespace:
|
||||
return SimpleNamespace(
|
||||
auth_storage=storage,
|
||||
mcp_token_store=store,
|
||||
oidc_config=oidc_config,
|
||||
obo_http_client=http_client,
|
||||
mcp_oauth_refresh_locks={},
|
||||
mcp_oauth_refresh_backoff={},
|
||||
)
|
||||
|
||||
|
||||
def _seed_obo_server(storage: SQLiteBackend, name: str, audience: str) -> None:
|
||||
storage.create_mcp_server(
|
||||
server_id=f"{name}-id",
|
||||
name=name,
|
||||
transport="streamable-http",
|
||||
url="https://mcp.example.invalid/sse",
|
||||
auth_type="oauth_obo",
|
||||
oauth_audience=audience,
|
||||
)
|
||||
|
||||
|
||||
async def _run(cfg: dict[str, str], refresh_token: str) -> None:
|
||||
tenant = cfg["ENTRA_TENANT_ID"]
|
||||
issuer = f"https://login.microsoftonline.com/{tenant}/v2.0"
|
||||
token_endpoint = f"https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token"
|
||||
aud_a = cfg["SPIKE_AUDIENCE_A"]
|
||||
aud_b = cfg["SPIKE_AUDIENCE_B"]
|
||||
aud_c = cfg.get("SPIKE_AUDIENCE_UNCONSENTED", "")
|
||||
|
||||
# Real Turnstone objects.
|
||||
db_path = os.path.join(tempfile.mkdtemp(prefix="obo-e2e-"), "e2e.db")
|
||||
storage = SQLiteBackend(db_path)
|
||||
from cryptography.fernet import Fernet
|
||||
|
||||
raw = base64.urlsafe_b64decode(Fernet.generate_key())
|
||||
store = MCPTokenStore(storage, MCPTokenCipher(MCPTokenCipherConfig(keys=(raw,))), node_id="e2e")
|
||||
oidc_config = OIDCConfig(
|
||||
enabled=True,
|
||||
issuer=issuer,
|
||||
client_id=cfg["ENTRA_CLIENT_ID"],
|
||||
client_secret=cfg["ENTRA_CLIENT_SECRET"],
|
||||
token_endpoint=token_endpoint,
|
||||
obo_grant_profile="entra",
|
||||
capture_user_credential=True,
|
||||
)
|
||||
|
||||
# Step 2 — CAPTURE: the exact storage call handle_oidc_callback makes.
|
||||
store.upsert_oidc_credential(USER, issuer, refresh_token=refresh_token)
|
||||
cap = store.get_oidc_credential(USER, issuer)
|
||||
if cap and cap["refresh_token"] == refresh_token:
|
||||
record("VERIFIED", f"capture: credential persisted for {USER} ({redact(refresh_token)})")
|
||||
else:
|
||||
record("FAILED", "capture: credential did not round-trip")
|
||||
return
|
||||
|
||||
_seed_obo_server(storage, "e2e-a", aud_a)
|
||||
_seed_obo_server(storage, "e2e-b", aud_b)
|
||||
if aud_c:
|
||||
_seed_obo_server(storage, "e2e-c", aud_c)
|
||||
|
||||
inner = httpx.AsyncClient(timeout=20.0)
|
||||
client = _CountingClient(inner)
|
||||
app_state = _make_app_state(storage, store, oidc_config, client)
|
||||
try:
|
||||
# E1 — real mint for audience A.
|
||||
r = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="e2e-a"
|
||||
)
|
||||
if r.kind == "token" and r.token:
|
||||
ok, aud = aud_matches(r.token, aud_a)
|
||||
row = storage.get_mcp_user_token(USER, "e2e-a")
|
||||
cache_ok = (
|
||||
row is not None and row["refresh_token_ct"] is None and bool(row["expires_at"])
|
||||
)
|
||||
record(
|
||||
"VERIFIED" if ok and cache_ok else "FAILED",
|
||||
f"E1 mint A: kind=token aud={aud} want={aud_a} cache_row_refreshless={cache_ok}",
|
||||
)
|
||||
else:
|
||||
record("FAILED", f"E1 mint A: kind={r.kind} (expected token)")
|
||||
return
|
||||
|
||||
# E2 — cache hit issues zero Entra calls.
|
||||
posts_before = client.posts
|
||||
r2 = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="e2e-a"
|
||||
)
|
||||
record(
|
||||
"VERIFIED" if r2.kind == "token" and client.posts == posts_before else "FAILED",
|
||||
f"E2 cache hit: kind={r2.kind} extra_entra_calls={client.posts - posts_before} (want 0)",
|
||||
)
|
||||
|
||||
# E3 — same credential, audience B.
|
||||
rb = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="e2e-b"
|
||||
)
|
||||
if rb.kind == "token" and rb.token:
|
||||
ok_b, aud_bclaim = aud_matches(rb.token, aud_b)
|
||||
record(
|
||||
"VERIFIED" if ok_b else "FAILED",
|
||||
f"E3 mint B from SAME credential: aud={aud_bclaim} want={aud_b}",
|
||||
)
|
||||
else:
|
||||
record("FAILED", f"E3 mint B: kind={rb.kind}")
|
||||
|
||||
# E4 — rotation write-back: the stored credential is still redeemable
|
||||
# (holds the newest RT — Entra rotates on redemption).
|
||||
cred_now = store.get_oidc_credential(USER, issuer)
|
||||
record(
|
||||
"VERIFIED" if cred_now is not None else "FAILED",
|
||||
f"E4 rotation write-back: credential persisted {redact(cred_now['refresh_token']) if cred_now else '<gone>'}",
|
||||
)
|
||||
|
||||
# E5 — force_refresh re-mints (a real Entra call).
|
||||
posts_before = client.posts
|
||||
rf = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="e2e-a", force_refresh=True
|
||||
)
|
||||
record(
|
||||
"VERIFIED" if rf.kind == "token" and client.posts > posts_before else "FAILED",
|
||||
f"E5 force_refresh re-mint: kind={rf.kind} entra_calls={client.posts - posts_before} (want >=1)",
|
||||
)
|
||||
|
||||
# E6 — unconsented audience: not a token, and the credential SURVIVES.
|
||||
if aud_c:
|
||||
rc = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="e2e-c"
|
||||
)
|
||||
cred_after = store.get_oidc_credential(USER, issuer)
|
||||
record(
|
||||
"VERIFIED" if rc.kind != "token" and cred_after is not None else "FAILED",
|
||||
f"E6 unconsented C: kind={rc.kind} (not token) credential_survives={cred_after is not None}",
|
||||
)
|
||||
else:
|
||||
record("SKIPPED", "E6 unconsented C: SPIKE_AUDIENCE_UNCONSENTED not set")
|
||||
|
||||
# E7 — cache flush → re-mint.
|
||||
store.delete_user_token(USER, "e2e-a")
|
||||
posts_before = client.posts
|
||||
r7 = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="e2e-a"
|
||||
)
|
||||
record(
|
||||
"VERIFIED" if r7.kind == "token" and client.posts > posts_before else "FAILED",
|
||||
f"E7 flush→re-mint: kind={r7.kind} entra_calls={client.posts - posts_before} (want >=1)",
|
||||
)
|
||||
finally:
|
||||
await inner.aclose()
|
||||
|
||||
|
||||
def main() -> int:
|
||||
required = [
|
||||
"ENTRA_TENANT_ID",
|
||||
"ENTRA_CLIENT_ID",
|
||||
"ENTRA_CLIENT_SECRET",
|
||||
"SPIKE_AUDIENCE_A",
|
||||
"SPIKE_AUDIENCE_B",
|
||||
]
|
||||
cfg = {k: os.environ[k] for k in os.environ if k.startswith(("ENTRA_", "SPIKE_"))}
|
||||
missing = [k for k in required if not cfg.get(k)]
|
||||
if missing:
|
||||
print(f"Missing env: {', '.join(missing)} — did you `source scripts/obo-e2e/.env`?")
|
||||
return 2
|
||||
|
||||
print("Signing in to Entra (this is the login the feature captures)...")
|
||||
tokens = interactive_login(cfg)
|
||||
refresh_token = tokens.get("refresh_token")
|
||||
if not isinstance(refresh_token, str) or not refresh_token:
|
||||
print(f"No refresh_token from login (keys={sorted(tokens)}) — offline_access missing?")
|
||||
return 1
|
||||
|
||||
asyncio.run(_run(cfg, refresh_token))
|
||||
|
||||
print("\n=== summary ===")
|
||||
for status, msg in RESULTS:
|
||||
print(f" {status:>8} {msg}")
|
||||
return 0 if all(s in ("VERIFIED", "SKIPPED") for s, _ in RESULTS) else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,134 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Entra spike setup for entra_spike.py (#551 re-scope boundary spike).
|
||||
# Manual test tooling — not run in CI. Creates throwaway Entra app registrations.
|
||||
#
|
||||
# ./entra_setup.sh setup create app registrations + consent + .env
|
||||
# ./entra_setup.sh cleanup delete everything it created (incl. .env)
|
||||
#
|
||||
# Creates in the logged-in tenant (az login first):
|
||||
# spike-turnstone confidential client (stands in for Turnstone's OIDC app)
|
||||
# spike-mcp-a/b resource apps exposing scope mcp.access, admin-consented
|
||||
# spike-mcp-c resource app with NO grant to the client (V5 control)
|
||||
# Requires: the logged-in user can create apps + grant admin consent
|
||||
# (Global Admin on a personal tenant qualifies).
|
||||
|
||||
set -euo pipefail
|
||||
cd "$(dirname "$0")"
|
||||
ENV_FILE=".env"
|
||||
NAMES=(spike-turnstone spike-mcp-a spike-mcp-b spike-mcp-c)
|
||||
|
||||
log() { printf '>> %s\n' "$*"; }
|
||||
|
||||
graph_patch_api() { # $1=appId $2=scope-uuid $3=display-name
|
||||
local obj_id
|
||||
obj_id=$(az ad app show --id "$1" --query id -o tsv)
|
||||
az rest --method PATCH \
|
||||
--url "https://graph.microsoft.com/v1.0/applications/${obj_id}" \
|
||||
--headers 'Content-Type=application/json' \
|
||||
--body "{
|
||||
\"identifierUris\": [\"api://$1\"],
|
||||
\"api\": {
|
||||
\"requestedAccessTokenVersion\": 2,
|
||||
\"oauth2PermissionScopes\": [{
|
||||
\"id\": \"$2\",
|
||||
\"value\": \"mcp.access\",
|
||||
\"type\": \"Admin\",
|
||||
\"isEnabled\": true,
|
||||
\"adminConsentDisplayName\": \"Access $3\",
|
||||
\"adminConsentDescription\": \"Spike scope for $3\"
|
||||
}]
|
||||
}
|
||||
}"
|
||||
}
|
||||
|
||||
make_resource_app() { # $1=display-name ; echoes "appId scopeId"
|
||||
local app_id scope_id
|
||||
app_id=$(az ad app create --display-name "$1" \
|
||||
--sign-in-audience AzureADMyOrg --query appId -o tsv)
|
||||
scope_id=$(python3 -c 'import uuid; print(uuid.uuid4())')
|
||||
graph_patch_api "$app_id" "$scope_id" "$1" >/dev/null
|
||||
az ad sp create --id "$app_id" >/dev/null 2>&1 || true
|
||||
echo "$app_id $scope_id"
|
||||
}
|
||||
|
||||
cmd_setup() {
|
||||
local tenant_id
|
||||
tenant_id=$(az account show --query tenantId -o tsv)
|
||||
log "tenant: ${tenant_id}"
|
||||
|
||||
log "creating resource apps (a, b, c)..."
|
||||
read -r APP_A SCOPE_A <<<"$(make_resource_app spike-mcp-a)"
|
||||
read -r APP_B SCOPE_B <<<"$(make_resource_app spike-mcp-b)"
|
||||
read -r APP_C _ <<<"$(make_resource_app spike-mcp-c)"
|
||||
log " a=${APP_A} b=${APP_B} c=${APP_C} (c stays unconsented)"
|
||||
|
||||
log "creating confidential client spike-turnstone..."
|
||||
CLIENT_ID=$(az ad app create --display-name spike-turnstone \
|
||||
--sign-in-audience AzureADMyOrg \
|
||||
--web-redirect-uris "http://localhost:8765/callback" \
|
||||
--query appId -o tsv)
|
||||
az ad sp create --id "$CLIENT_ID" >/dev/null 2>&1 || true
|
||||
# No stderr suppression here: the secret is load-bearing (it lands in .env),
|
||||
# so under `set -e` a reset failure must abort LOUDLY, not silently.
|
||||
SECRET=$(az ad app credential reset --id "$CLIENT_ID" \
|
||||
--display-name spike --years 1 --query password -o tsv)
|
||||
|
||||
log "adding delegated permissions (a, b — NOT c)..."
|
||||
# Tolerated failures (|| log): a re-run hits "permission already exists" and
|
||||
# SP-propagation delays are common right after app creation — the
|
||||
# admin-consent retry loop below is the real gate. `set -e` would otherwise
|
||||
# turn a suppressed non-zero here into a silent mid-script abort.
|
||||
az ad app permission add --id "$CLIENT_ID" \
|
||||
--api "$APP_A" --api-permissions "${SCOPE_A}=Scope" \
|
||||
|| log " warn: permission add for a failed (may already exist); admin-consent below will confirm"
|
||||
az ad app permission add --id "$CLIENT_ID" \
|
||||
--api "$APP_B" --api-permissions "${SCOPE_B}=Scope" \
|
||||
|| log " warn: permission add for b failed (may already exist); admin-consent below will confirm"
|
||||
|
||||
log "granting admin consent (retries while SPs propagate)..."
|
||||
local ok=""
|
||||
for i in 1 2 3 4 5; do
|
||||
if az ad app permission admin-consent --id "$CLIENT_ID" 2>/dev/null; then
|
||||
ok=1; break
|
||||
fi
|
||||
log " not yet (attempt $i) — waiting 15s"
|
||||
sleep 15
|
||||
done
|
||||
[ -n "$ok" ] || { log "admin-consent failed after retries — grant manually in the portal (API permissions blade) and re-run the spike"; }
|
||||
|
||||
# Single-quote the values in the generated .env: the AS-issued client secret
|
||||
# can contain $ / backtick, and an unquoted RHS would be re-expanded (or
|
||||
# partially executed) when the operator `source`s the file. The heredoc still
|
||||
# interpolates ${...} into the single-quoted output; sourcing then treats the
|
||||
# result literally. (Azure secrets are base64-ish — no single quotes to escape.)
|
||||
umask 177
|
||||
cat > "$ENV_FILE" <<EOF
|
||||
export ENTRA_TENANT_ID='${tenant_id}'
|
||||
export ENTRA_CLIENT_ID='${CLIENT_ID}'
|
||||
export ENTRA_CLIENT_SECRET='${SECRET}'
|
||||
export SPIKE_AUDIENCE_A='api://${APP_A}'
|
||||
export SPIKE_AUDIENCE_B='api://${APP_B}'
|
||||
export SPIKE_AUDIENCE_UNCONSENTED='api://${APP_C}'
|
||||
export SPIKE_RUN_OBO=1
|
||||
EOF
|
||||
log "wrote ${ENV_FILE} (chmod 600). Next:"
|
||||
log " source scripts/obo-e2e/.env && uv run python scripts/obo-e2e/entra_spike.py"
|
||||
log "cleanup later with: ./entra_setup.sh cleanup"
|
||||
}
|
||||
|
||||
cmd_cleanup() {
|
||||
for name in "${NAMES[@]}"; do
|
||||
for app_id in $(az ad app list --display-name "$name" --query '[].appId' -o tsv); do
|
||||
log "deleting ${name} (${app_id})"
|
||||
az ad app delete --id "$app_id"
|
||||
done
|
||||
done
|
||||
rm -f "$ENV_FILE"
|
||||
log "cleanup done (app registrations + .env removed)"
|
||||
}
|
||||
|
||||
case "${1:-}" in
|
||||
setup) cmd_setup ;;
|
||||
cleanup) cmd_cleanup ;;
|
||||
*) echo "usage: $0 setup|cleanup"; exit 2 ;;
|
||||
esac
|
||||
@@ -1,333 +0,0 @@
|
||||
"""Entra boundary spike for single-credential MCP token minting (#551 re-scope).
|
||||
|
||||
Verifies, against a REAL Entra tenant, the assumptions behind the oauth_obo
|
||||
design (one IdP refresh token per user; per-MCP access tokens minted on
|
||||
demand). Each check prints VERIFIED / FAILED / SKIPPED plus redacted evidence.
|
||||
|
||||
V1 interactive confidential-client login (auth-code + PKCE + offline_access)
|
||||
-> refresh token captured [capture layer works]
|
||||
V2 RT redeemed with scope=<AUDIENCE_A>/.default -> aud claim == A
|
||||
V3 SAME credential redeemed for <AUDIENCE_B> -> aud claim == B
|
||||
KEY CHECK: Entra RTs are client-bound, not resource-bound.
|
||||
V4 rotation semantics: does each redemption return a new RT, and does the
|
||||
PREVIOUS RT keep working? [write-back design]
|
||||
V5 redemption for an unconsented audience -> AADSTS65001 consent_required
|
||||
[maps to the reconnect-rail fallback]
|
||||
V6 optional: OBO jwt-bearer leg (requested_token_use=on_behalf_of) using a
|
||||
Turnstone-audience access token as assertion [middle-tier variant]
|
||||
|
||||
Run: uv run python scripts/obo-e2e/entra_spike.py
|
||||
Env: ENTRA_TENANT_ID tenant GUID or domain
|
||||
ENTRA_CLIENT_ID Turnstone spike app registration (confidential)
|
||||
ENTRA_CLIENT_SECRET client secret for the above
|
||||
SPIKE_AUDIENCE_A e.g. api://<guid-a> (exposes a scope, consented)
|
||||
SPIKE_AUDIENCE_B e.g. api://<guid-b> (exposes a scope, consented)
|
||||
SPIKE_AUDIENCE_UNCONSENTED optional, for V5
|
||||
SPIKE_RUN_OBO optional "1" to run V6
|
||||
SPIKE_PORT redirect listener port (default 8765; register
|
||||
http://localhost:<port>/callback as a Web
|
||||
redirect URI on the spike app registration)
|
||||
|
||||
App-registration setup checklist: see README.md next to this file.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import base64
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import secrets
|
||||
import sys
|
||||
import threading
|
||||
import urllib.parse
|
||||
import webbrowser
|
||||
from http.server import BaseHTTPRequestHandler, HTTPServer
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
|
||||
RESULTS: list[tuple[str, str, str]] = [] # (check, status, evidence)
|
||||
|
||||
|
||||
def record(check: str, status: str, evidence: str) -> None:
|
||||
RESULTS.append((check, status, evidence))
|
||||
print(f"[{status:>8}] {check}: {evidence}")
|
||||
|
||||
|
||||
def b64url_json(segment: str) -> dict[str, Any]:
|
||||
pad = "=" * (-len(segment) % 4)
|
||||
out: dict[str, Any] = json.loads(base64.urlsafe_b64decode(segment + pad))
|
||||
return out
|
||||
|
||||
|
||||
def jwt_claims_unverified(token: str) -> dict[str, Any]:
|
||||
"""Spike-only unverified decode. NEVER do this in product code."""
|
||||
try:
|
||||
return b64url_json(token.split(".")[1])
|
||||
except Exception:
|
||||
return {}
|
||||
|
||||
|
||||
def redact(token: str | None) -> str:
|
||||
if not token:
|
||||
return "<absent>"
|
||||
return f"{token[:8]}...({len(token)} chars)"
|
||||
|
||||
|
||||
class _CodeCatcher(BaseHTTPRequestHandler):
|
||||
code: str | None = None
|
||||
state: str | None = None
|
||||
event = threading.Event()
|
||||
|
||||
def do_GET(self) -> None: # noqa: N802 - stdlib API name
|
||||
q = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
|
||||
_CodeCatcher.code = (q.get("code") or [None])[0]
|
||||
_CodeCatcher.state = (q.get("state") or [None])[0]
|
||||
body = b"Spike login captured - return to the terminal."
|
||||
if q.get("error"):
|
||||
body = f"IdP error: {q}".encode()
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "text/plain")
|
||||
self.end_headers()
|
||||
self.wfile.write(body)
|
||||
_CodeCatcher.event.set()
|
||||
|
||||
def log_message(self, *args: Any) -> None:
|
||||
pass
|
||||
|
||||
|
||||
def interactive_login(cfg: dict[str, str]) -> dict[str, Any]:
|
||||
"""V1: authorization-code + PKCE + offline_access as a confidential client.
|
||||
|
||||
Mirrors production shape: same grant Turnstone's OIDC login uses
|
||||
(core/oidc.py exchange_code), plus offline_access.
|
||||
"""
|
||||
port = int(cfg.get("SPIKE_PORT", "8765"))
|
||||
redirect_uri = f"http://localhost:{port}/callback"
|
||||
verifier = secrets.token_urlsafe(48)
|
||||
challenge = (
|
||||
base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
|
||||
)
|
||||
state = secrets.token_urlsafe(16)
|
||||
authorize = (
|
||||
f"https://login.microsoftonline.com/{cfg['ENTRA_TENANT_ID']}/oauth2/v2.0/authorize?"
|
||||
+ urllib.parse.urlencode(
|
||||
{
|
||||
"client_id": cfg["ENTRA_CLIENT_ID"],
|
||||
"response_type": "code",
|
||||
"redirect_uri": redirect_uri,
|
||||
"response_mode": "query",
|
||||
# offline_access is THE capture-layer delta vs today's login.
|
||||
# No resource scope here: the RT is minted client-bound.
|
||||
"scope": "openid profile offline_access",
|
||||
"state": state,
|
||||
"code_challenge": challenge,
|
||||
"code_challenge_method": "S256",
|
||||
}
|
||||
)
|
||||
)
|
||||
server = HTTPServer(("127.0.0.1", port), _CodeCatcher)
|
||||
threading.Thread(target=server.serve_forever, daemon=True).start()
|
||||
print(f"\nOpen (or auto-opened) in a browser with a tenant user:\n {authorize}\n")
|
||||
cb_file = cfg.get("SPIKE_CALLBACK_FILE", "")
|
||||
if cb_file:
|
||||
print(
|
||||
"Remote-browser mode: after sign-in the browser lands on a broken\n"
|
||||
f"http://localhost:{port}/callback?... page. Copy that FULL URL and run:\n"
|
||||
f" echo '<url>' > {cb_file}\n"
|
||||
)
|
||||
|
||||
def _watch_callback_file() -> None:
|
||||
# Driver-friendly fallback: the sign-in can happen on any device;
|
||||
# whoever signed in drops the redirected URL into SPIKE_CALLBACK_FILE.
|
||||
import time as _time
|
||||
|
||||
while not _CodeCatcher.event.is_set():
|
||||
try:
|
||||
with open(cb_file) as _f:
|
||||
pasted = _f.read().strip()
|
||||
except OSError:
|
||||
pasted = ""
|
||||
if "?" in pasted:
|
||||
q = urllib.parse.parse_qs(urllib.parse.urlparse(pasted).query)
|
||||
_CodeCatcher.code = (q.get("code") or [None])[0]
|
||||
_CodeCatcher.state = (q.get("state") or [None])[0]
|
||||
_CodeCatcher.event.set()
|
||||
return
|
||||
_time.sleep(1.0)
|
||||
|
||||
if cb_file:
|
||||
threading.Thread(target=_watch_callback_file, daemon=True).start()
|
||||
webbrowser.open(authorize)
|
||||
if not _CodeCatcher.event.wait(timeout=600):
|
||||
server.shutdown()
|
||||
raise SystemExit("Timed out waiting for the redirect (10 min).")
|
||||
server.shutdown()
|
||||
if _CodeCatcher.state != state:
|
||||
raise SystemExit("state mismatch on redirect - aborting.")
|
||||
if not _CodeCatcher.code:
|
||||
raise SystemExit("No code on redirect (IdP error page shown in browser).")
|
||||
resp = httpx.post(
|
||||
f"https://login.microsoftonline.com/{cfg['ENTRA_TENANT_ID']}/oauth2/v2.0/token",
|
||||
data={
|
||||
"grant_type": "authorization_code",
|
||||
"code": _CodeCatcher.code,
|
||||
"redirect_uri": redirect_uri,
|
||||
"client_id": cfg["ENTRA_CLIENT_ID"],
|
||||
"client_secret": cfg["ENTRA_CLIENT_SECRET"],
|
||||
"code_verifier": verifier,
|
||||
},
|
||||
timeout=15.0,
|
||||
)
|
||||
tokens: dict[str, Any] = resp.json()
|
||||
if resp.status_code != 200:
|
||||
raise SystemExit(f"code exchange failed: {json.dumps(tokens, indent=2)[:800]}")
|
||||
return tokens
|
||||
|
||||
|
||||
def redeem(cfg: dict[str, str], refresh_token: str, scope: str) -> tuple[int, dict[str, Any]]:
|
||||
"""Redeem a refresh token for an access token with the given scope."""
|
||||
resp = httpx.post(
|
||||
f"https://login.microsoftonline.com/{cfg['ENTRA_TENANT_ID']}/oauth2/v2.0/token",
|
||||
data={
|
||||
"grant_type": "refresh_token",
|
||||
"refresh_token": refresh_token,
|
||||
"client_id": cfg["ENTRA_CLIENT_ID"],
|
||||
"client_secret": cfg["ENTRA_CLIENT_SECRET"],
|
||||
"scope": scope,
|
||||
},
|
||||
timeout=15.0,
|
||||
)
|
||||
body: dict[str, Any] = resp.json()
|
||||
return resp.status_code, body
|
||||
|
||||
|
||||
def obo_exchange(cfg: dict[str, str], assertion: str, scope: str) -> tuple[int, dict[str, Any]]:
|
||||
"""V6: middle-tier OBO variant (jwt-bearer + requested_token_use)."""
|
||||
resp = httpx.post(
|
||||
f"https://login.microsoftonline.com/{cfg['ENTRA_TENANT_ID']}/oauth2/v2.0/token",
|
||||
data={
|
||||
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
|
||||
"assertion": assertion,
|
||||
"client_id": cfg["ENTRA_CLIENT_ID"],
|
||||
"client_secret": cfg["ENTRA_CLIENT_SECRET"],
|
||||
"scope": scope,
|
||||
"requested_token_use": "on_behalf_of",
|
||||
},
|
||||
timeout=15.0,
|
||||
)
|
||||
body: dict[str, Any] = resp.json()
|
||||
return resp.status_code, body
|
||||
|
||||
|
||||
def check_aud(label: str, status: int, body: dict[str, Any], want_aud: str) -> str | None:
|
||||
"""Common V2/V3 assertion: 200 + aud matches. Returns the new RT if any."""
|
||||
if status != 200:
|
||||
record(label, "FAILED", f"HTTP {status}: {json.dumps(body)[:300]}")
|
||||
return None
|
||||
claims = jwt_claims_unverified(body.get("access_token", ""))
|
||||
aud = str(claims.get("aud", "<none>"))
|
||||
ok = aud == want_aud or aud == want_aud.removeprefix("api://")
|
||||
record(
|
||||
label,
|
||||
"VERIFIED" if ok else "FAILED",
|
||||
f"aud={aud} want={want_aud} expires_in={body.get('expires_in')} "
|
||||
f"new_rt={redact(body.get('refresh_token'))}",
|
||||
)
|
||||
new_rt = body.get("refresh_token")
|
||||
return str(new_rt) if isinstance(new_rt, str) else None
|
||||
|
||||
|
||||
def main() -> int:
|
||||
required = [
|
||||
"ENTRA_TENANT_ID",
|
||||
"ENTRA_CLIENT_ID",
|
||||
"ENTRA_CLIENT_SECRET",
|
||||
"SPIKE_AUDIENCE_A",
|
||||
"SPIKE_AUDIENCE_B",
|
||||
]
|
||||
cfg = {k: os.environ[k] for k in required if k in os.environ}
|
||||
missing = [k for k in required if k not in cfg]
|
||||
if missing:
|
||||
print(f"Missing env: {', '.join(missing)}\nSee module docstring.")
|
||||
return 2
|
||||
for opt in ("SPIKE_AUDIENCE_UNCONSENTED", "SPIKE_PORT", "SPIKE_RUN_OBO"):
|
||||
if opt in os.environ:
|
||||
cfg[opt] = os.environ[opt]
|
||||
|
||||
# V1 - capture
|
||||
tokens = interactive_login(cfg)
|
||||
rt0 = tokens.get("refresh_token")
|
||||
if isinstance(rt0, str) and rt0:
|
||||
record("V1 capture (offline_access -> RT)", "VERIFIED", redact(rt0))
|
||||
else:
|
||||
record("V1 capture (offline_access -> RT)", "FAILED", f"keys={sorted(tokens.keys())}")
|
||||
return 1
|
||||
|
||||
# V2 - mint for audience A
|
||||
a = cfg["SPIKE_AUDIENCE_A"]
|
||||
s2, b2 = redeem(cfg, rt0, f"{a}/.default")
|
||||
rt_after_a = check_aud("V2 mint audience A from RT", s2, b2, a)
|
||||
|
||||
# V3 - SAME credential, audience B (the design-critical check)
|
||||
b = cfg["SPIKE_AUDIENCE_B"]
|
||||
s3, b3 = redeem(cfg, rt0, f"{b}/.default")
|
||||
check_aud("V3 mint audience B from SAME RT", s3, b3, b)
|
||||
|
||||
# V4 - rotation semantics
|
||||
if rt_after_a and rt_after_a != rt0:
|
||||
s4, _ = redeem(cfg, rt0, f"{a}/.default")
|
||||
record(
|
||||
"V4 rotation (new RT returned; old still valid?)",
|
||||
"VERIFIED" if s4 == 200 else "VERIFIED",
|
||||
f"rotated=yes old_rt_reuse_http={s4} "
|
||||
"(design: persist newest RT on every mint; "
|
||||
f"{'old stays valid - benign race window' if s4 == 200 else 'old INVALIDATED - write-back is correctness-critical'})",
|
||||
)
|
||||
else:
|
||||
record(
|
||||
"V4 rotation",
|
||||
"VERIFIED",
|
||||
"no rotation observed on redemption (same/absent RT) - "
|
||||
"write-back still required for the rotating case",
|
||||
)
|
||||
|
||||
# V5 - unconsented audience -> consent_required
|
||||
unc = cfg.get("SPIKE_AUDIENCE_UNCONSENTED")
|
||||
if unc:
|
||||
s5, b5 = redeem(cfg, rt0, f"{unc}/.default")
|
||||
codes = b5.get("error_codes", [])
|
||||
hit = s5 == 400 and (65001 in codes or b5.get("suberror") == "consent_required")
|
||||
record(
|
||||
"V5 unconsented audience -> AADSTS65001",
|
||||
"VERIFIED" if hit else "FAILED",
|
||||
f"http={s5} error={b5.get('error')} codes={codes}",
|
||||
)
|
||||
else:
|
||||
record("V5 unconsented audience", "SKIPPED", "SPIKE_AUDIENCE_UNCONSENTED not set")
|
||||
|
||||
# V6 - optional OBO middle-tier variant
|
||||
if cfg.get("SPIKE_RUN_OBO") == "1":
|
||||
s6a, b6a = redeem(cfg, rt0, f"{cfg['ENTRA_CLIENT_ID']}/.default")
|
||||
at_self = b6a.get("access_token", "") if s6a == 200 else ""
|
||||
if at_self:
|
||||
s6, b6 = obo_exchange(cfg, at_self, f"{a}/.default")
|
||||
check_aud("V6 OBO jwt-bearer variant", s6, b6, a)
|
||||
else:
|
||||
record(
|
||||
"V6 OBO jwt-bearer variant",
|
||||
"FAILED",
|
||||
f"could not mint self-audience assertion: HTTP {s6a}",
|
||||
)
|
||||
else:
|
||||
record("V6 OBO jwt-bearer variant", "SKIPPED", "SPIKE_RUN_OBO != 1")
|
||||
|
||||
print("\n=== summary ===")
|
||||
for check, status, _ in RESULTS:
|
||||
print(f" {status:>8} {check}")
|
||||
return 0 if all(s != "FAILED" for _, s, _ in RESULTS) else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,371 +0,0 @@
|
||||
"""End-to-end exercise of the oauth_obo feature on the OSS path (RFC 8693).
|
||||
|
||||
Parallel to ``entra_e2e.py`` but for ``obo_grant_profile="rfc8693"`` against an
|
||||
ephemeral Keycloak — the open-source / non-Entra deployment shape. Fully
|
||||
headless (password grant, no browser), so it runs unattended.
|
||||
|
||||
Drives the REAL Turnstone code: ``MCPTokenStore.upsert_oidc_credential`` (capture)
|
||||
then ``get_obo_access_token_classified`` → ``_obo_mint_rfc8693`` (refresh grant →
|
||||
RFC 8693 token exchange) against the live Keycloak token endpoint.
|
||||
|
||||
Checks E1–E7 mirror the Entra harness:
|
||||
E1 mint audience A → token, aud claim carries A, cache row refresh_token_ct NULL
|
||||
E2 second call → cache hit, ZERO extra Keycloak calls
|
||||
E3 audience B from the SAME captured credential → aud carries B
|
||||
E4 rotation write-back (KC rotates the RT on the refresh leg)
|
||||
E5 force_refresh → re-mint (Keycloak call count increments)
|
||||
E6 unconsented audience C → NOT token, credential SURVIVES
|
||||
E7 cache flush → re-mint
|
||||
|
||||
M1-M3 drive the MODEL-backend mint (``mint_obo_access_token``, #898/#955) on
|
||||
the same captured credential — the path an ``auth_mode=rfc8693_obo`` model
|
||||
alias takes, distinct from the classified MCP path above:
|
||||
M1 model mint audience A with the alias's exchange scopes → token carries A
|
||||
(the #955 fix: model definitions now carry per-row ``obo_scopes``, so
|
||||
the exchange leg requests the audience's scope exactly as MCP rows do)
|
||||
M2 warm re-mint serves the synthetic ``__model_obo__`` cache row —
|
||||
identity-keyed on the owning alias, audience + scopes in the row's
|
||||
own columns — with zero IdP calls
|
||||
M3 an entra-leg mode (``entra_obo``) on this rfc8693 deployment refuses
|
||||
BEFORE any IdP traffic, recording cause=grant_profile_mismatch — the
|
||||
mode/profile pairing that replaced the pre-#955 overload
|
||||
|
||||
Env (set by keycloak_e2e.sh):
|
||||
KC_TOKEN_ENDPOINT, KC_ISSUER, KC_CLIENT_ID, KC_CLIENT_SECRET,
|
||||
KC_USER, KC_PASSWORD, AUD_A, SCOPE_A, AUD_B, SCOPE_B, AUD_C
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import base64
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import tempfile
|
||||
from types import SimpleNamespace
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
|
||||
from turnstone.core.mcp_crypto import (
|
||||
MCPTokenCipher,
|
||||
MCPTokenCipherConfig,
|
||||
MCPTokenStore,
|
||||
)
|
||||
from turnstone.core.mcp_oauth import (
|
||||
get_obo_access_token_classified,
|
||||
mint_obo_access_token,
|
||||
model_mint_refusal_cause,
|
||||
model_obo_cache_server,
|
||||
model_obo_cause_key,
|
||||
)
|
||||
from turnstone.core.oidc import OIDCConfig
|
||||
from turnstone.core.storage._sqlite import SQLiteBackend
|
||||
|
||||
USER = "e2e-user"
|
||||
RESULTS: list[tuple[str, str]] = []
|
||||
|
||||
|
||||
def record(status: str, msg: str) -> None:
|
||||
RESULTS.append((status, msg))
|
||||
print(f"[{status:>8}] {msg}")
|
||||
|
||||
|
||||
def redact(token: str | None) -> str:
|
||||
return f"{token[:8]}...({len(token)} chars)" if token else "<absent>"
|
||||
|
||||
|
||||
def jwt_claims(token: str) -> dict[str, Any]:
|
||||
seg = token.split(".")[1]
|
||||
pad = "=" * (-len(seg) % 4)
|
||||
out: dict[str, Any] = json.loads(base64.urlsafe_b64decode(seg + pad))
|
||||
return out
|
||||
|
||||
|
||||
def aud_carries(token: str, want: str) -> tuple[bool, str]:
|
||||
"""KC puts the exchanged audience in the aud claim (str or list)."""
|
||||
aud = jwt_claims(token).get("aud", [])
|
||||
auds = aud if isinstance(aud, list) else [aud]
|
||||
return want in auds, str(aud)
|
||||
|
||||
|
||||
class _CountingClient:
|
||||
def __init__(self, inner: httpx.AsyncClient) -> None:
|
||||
self._inner = inner
|
||||
self.posts = 0
|
||||
|
||||
async def post(self, *args: Any, **kwargs: Any) -> httpx.Response:
|
||||
self.posts += 1
|
||||
return await self._inner.post(*args, **kwargs)
|
||||
|
||||
|
||||
def _password_login(cfg: dict[str, str]) -> str:
|
||||
"""Headless direct-access grant → a real refresh token for the user."""
|
||||
resp = httpx.post(
|
||||
cfg["KC_TOKEN_ENDPOINT"],
|
||||
data={
|
||||
"grant_type": "password",
|
||||
"client_id": cfg["KC_CLIENT_ID"],
|
||||
"client_secret": cfg["KC_CLIENT_SECRET"],
|
||||
"username": cfg["KC_USER"],
|
||||
"password": cfg["KC_PASSWORD"],
|
||||
"scope": "openid",
|
||||
},
|
||||
timeout=15.0,
|
||||
)
|
||||
resp.raise_for_status()
|
||||
return str(resp.json()["refresh_token"])
|
||||
|
||||
|
||||
def _seed(storage: SQLiteBackend, name: str, audience: str, scopes: str | None) -> None:
|
||||
storage.create_mcp_server(
|
||||
server_id=f"{name}-id",
|
||||
name=name,
|
||||
transport="streamable-http",
|
||||
url="https://mcp.example.invalid/sse",
|
||||
auth_type="oauth_obo",
|
||||
oauth_audience=audience,
|
||||
oauth_scopes=scopes,
|
||||
)
|
||||
|
||||
|
||||
async def _run(cfg: dict[str, str], refresh_token: str) -> None:
|
||||
issuer = cfg["KC_ISSUER"]
|
||||
db_path = os.path.join(tempfile.mkdtemp(prefix="obo-kc-e2e-"), "e2e.db")
|
||||
storage = SQLiteBackend(db_path)
|
||||
from cryptography.fernet import Fernet
|
||||
|
||||
raw = base64.urlsafe_b64decode(Fernet.generate_key())
|
||||
store = MCPTokenStore(storage, MCPTokenCipher(MCPTokenCipherConfig(keys=(raw,))), node_id="e2e")
|
||||
oidc_config = OIDCConfig(
|
||||
enabled=True,
|
||||
issuer=issuer,
|
||||
client_id=cfg["KC_CLIENT_ID"],
|
||||
client_secret=cfg["KC_CLIENT_SECRET"],
|
||||
token_endpoint=cfg["KC_TOKEN_ENDPOINT"],
|
||||
obo_grant_profile="rfc8693",
|
||||
capture_user_credential=True,
|
||||
)
|
||||
|
||||
store.upsert_oidc_credential(USER, issuer, refresh_token=refresh_token)
|
||||
cap = store.get_oidc_credential(USER, issuer)
|
||||
if cap and cap["refresh_token"] == refresh_token:
|
||||
record("VERIFIED", f"capture: credential persisted ({redact(refresh_token)})")
|
||||
else:
|
||||
record("FAILED", "capture: credential did not round-trip")
|
||||
return
|
||||
|
||||
_seed(storage, "kc-a", cfg["AUD_A"], cfg.get("SCOPE_A"))
|
||||
_seed(storage, "kc-b", cfg["AUD_B"], cfg.get("SCOPE_B"))
|
||||
if cfg.get("AUD_C"):
|
||||
_seed(storage, "kc-c", cfg["AUD_C"], None) # no audience scope → unconsented
|
||||
|
||||
inner = httpx.AsyncClient(timeout=20.0)
|
||||
client = _CountingClient(inner)
|
||||
app_state = SimpleNamespace(
|
||||
auth_storage=storage,
|
||||
mcp_token_store=store,
|
||||
oidc_config=oidc_config,
|
||||
obo_http_client=client,
|
||||
mcp_oauth_refresh_locks={},
|
||||
mcp_oauth_refresh_backoff={},
|
||||
)
|
||||
try:
|
||||
# E1 — rfc8693 mint (refresh grant → token exchange) for audience A.
|
||||
r = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="kc-a"
|
||||
)
|
||||
if r.kind == "token" and r.token:
|
||||
ok, aud = aud_carries(r.token, cfg["AUD_A"])
|
||||
row = storage.get_mcp_user_token(USER, "kc-a")
|
||||
cache_ok = row is not None and row["refresh_token_ct"] is None
|
||||
record(
|
||||
"VERIFIED" if ok and cache_ok else "FAILED",
|
||||
f"E1 mint A (refresh→exchange): kind=token aud={aud} want={cfg['AUD_A']} "
|
||||
f"cache_row_refreshless={cache_ok}",
|
||||
)
|
||||
else:
|
||||
record("FAILED", f"E1 mint A: kind={r.kind} (expected token)")
|
||||
return
|
||||
|
||||
# E2 — cache hit.
|
||||
posts_before = client.posts
|
||||
r2 = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="kc-a"
|
||||
)
|
||||
record(
|
||||
"VERIFIED" if r2.kind == "token" and client.posts == posts_before else "FAILED",
|
||||
f"E2 cache hit: kind={r2.kind} extra_kc_calls={client.posts - posts_before} (want 0)",
|
||||
)
|
||||
|
||||
# E3 — audience B from the SAME credential.
|
||||
rb = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="kc-b"
|
||||
)
|
||||
if rb.kind == "token" and rb.token:
|
||||
ok_b, aud_b = aud_carries(rb.token, cfg["AUD_B"])
|
||||
record(
|
||||
"VERIFIED" if ok_b else "FAILED",
|
||||
f"E3 mint B from SAME credential: aud={aud_b} want={cfg['AUD_B']}",
|
||||
)
|
||||
else:
|
||||
record("FAILED", f"E3 mint B: kind={rb.kind}")
|
||||
|
||||
# E4 — rotation write-back (KC rotates the RT on the refresh leg).
|
||||
cred_now = store.get_oidc_credential(USER, issuer)
|
||||
rotated = cred_now is not None and cred_now["refresh_token"] != refresh_token
|
||||
record(
|
||||
"VERIFIED" if cred_now is not None else "FAILED",
|
||||
f"E4 rotation write-back: persisted={redact(cred_now['refresh_token']) if cred_now else '<gone>'} "
|
||||
f"rotated_from_initial={rotated}",
|
||||
)
|
||||
|
||||
# E5 — force_refresh re-mints.
|
||||
posts_before = client.posts
|
||||
rf = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="kc-a", force_refresh=True
|
||||
)
|
||||
record(
|
||||
"VERIFIED" if rf.kind == "token" and client.posts > posts_before else "FAILED",
|
||||
f"E5 force_refresh re-mint: kind={rf.kind} kc_calls={client.posts - posts_before} (want >=1)",
|
||||
)
|
||||
|
||||
# E6 — unconsented audience: not a token, credential survives.
|
||||
if cfg.get("AUD_C"):
|
||||
rc = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="kc-c"
|
||||
)
|
||||
cred_after = store.get_oidc_credential(USER, issuer)
|
||||
record(
|
||||
"VERIFIED" if rc.kind != "token" and cred_after is not None else "FAILED",
|
||||
f"E6 unconsented C: kind={rc.kind} (not token) credential_survives={cred_after is not None}",
|
||||
)
|
||||
else:
|
||||
record("SKIPPED", "E6 unconsented C: AUD_C not set")
|
||||
|
||||
# E7 — cache flush → re-mint.
|
||||
store.delete_user_token(USER, "kc-a")
|
||||
posts_before = client.posts
|
||||
r7 = await get_obo_access_token_classified(
|
||||
app_state=app_state, user_id=USER, server_name="kc-a"
|
||||
)
|
||||
record(
|
||||
"VERIFIED" if r7.kind == "token" and client.posts > posts_before else "FAILED",
|
||||
f"E7 flush→re-mint: kind={r7.kind} kc_calls={client.posts - posts_before} (want >=1)",
|
||||
)
|
||||
|
||||
# M1-M3 — MODEL backend mint on the rfc8693 profile: same captured
|
||||
# credential and legs as E1-E7, but through mint_obo_access_token —
|
||||
# the path an auth_mode=rfc8693_obo alias takes, carrying the
|
||||
# per-alias exchange scopes MCP rows always had (#955). The mint's
|
||||
# cache and cause records are identity-keyed on the owning alias, so
|
||||
# the harness names one per mode-variant exactly as a deployment
|
||||
# would define separate rows.
|
||||
posts_before = client.posts
|
||||
m1 = await mint_obo_access_token(
|
||||
app_state=app_state,
|
||||
user_id=USER,
|
||||
alias="model-a",
|
||||
audience=cfg["AUD_A"],
|
||||
scopes=cfg.get("SCOPE_A", ""),
|
||||
grant_leg="rfc8693",
|
||||
)
|
||||
m1_kc_calls = client.posts - posts_before
|
||||
if m1:
|
||||
ok1, why1 = aud_carries(m1, cfg["AUD_A"])
|
||||
record(
|
||||
"VERIFIED" if ok1 and m1_kc_calls > 0 else "FAILED",
|
||||
f"M1 model mint (rfc8693_obo, scoped exchange): token={redact(m1)} "
|
||||
f"aud_ok={ok1} ({why1}) kc_calls={m1_kc_calls} (want >=1)",
|
||||
)
|
||||
else:
|
||||
record(
|
||||
"FAILED",
|
||||
f"M1 model mint (rfc8693_obo): no token (kc_calls={m1_kc_calls}) — "
|
||||
"the #955 scope wire-through should mint here",
|
||||
)
|
||||
|
||||
# M2 — warm re-mint serves the synthetic __model_obo__ cache row —
|
||||
# identity-keyed on the owning alias, audience + scopes in the row's
|
||||
# own columns — with zero IdP calls, and the row is named so
|
||||
# deprovisioning can find it by prefix.
|
||||
posts_before = client.posts
|
||||
m2 = await mint_obo_access_token(
|
||||
app_state=app_state,
|
||||
user_id=USER,
|
||||
alias="model-a",
|
||||
audience=cfg["AUD_A"],
|
||||
scopes=cfg.get("SCOPE_A", ""),
|
||||
grant_leg="rfc8693",
|
||||
)
|
||||
cache_row = storage.get_mcp_user_token(USER, model_obo_cache_server("model-a"))
|
||||
if m1:
|
||||
record(
|
||||
"VERIFIED"
|
||||
if m2 and client.posts == posts_before and cache_row is not None
|
||||
else "FAILED",
|
||||
f"M2 model cache-hit: token={redact(m2)} kc_calls="
|
||||
f"{client.posts - posts_before} (want 0) synthetic_row="
|
||||
f"{'present' if cache_row is not None else 'MISSING'}",
|
||||
)
|
||||
else:
|
||||
record("FAILED", "M2 model cache-hit: blocked behind M1 — M1 failed, see above")
|
||||
|
||||
# M3 — the mode/profile pairing refusal that replaced the pre-#955
|
||||
# overload: an entra-leg mode on this rfc8693 deployment must yield
|
||||
# None with ZERO IdP calls and record the grant_profile_mismatch
|
||||
# cause the session heartbeat reads (under its own alias — a
|
||||
# deployment defines the entra-mode variant as its own row).
|
||||
posts_before = client.posts
|
||||
m3 = await mint_obo_access_token(
|
||||
app_state=app_state,
|
||||
user_id=USER,
|
||||
alias="model-a-entra",
|
||||
audience=cfg["AUD_A"],
|
||||
grant_leg="entra",
|
||||
)
|
||||
m3_cause = model_mint_refusal_cause(
|
||||
"model_obo", model_obo_cause_key("model-a-entra", grant_leg="entra"), USER
|
||||
)
|
||||
record(
|
||||
"VERIFIED"
|
||||
if m3 is None and client.posts == posts_before and m3_cause == "grant_profile_mismatch"
|
||||
else "FAILED",
|
||||
f"M3 mode/profile mismatch refusal: token={redact(m3)} (want absent) "
|
||||
f"kc_calls={client.posts - posts_before} (want 0) cause={m3_cause!r}",
|
||||
)
|
||||
finally:
|
||||
await inner.aclose()
|
||||
|
||||
|
||||
def main() -> int:
|
||||
required = [
|
||||
"KC_TOKEN_ENDPOINT",
|
||||
"KC_ISSUER",
|
||||
"KC_CLIENT_ID",
|
||||
"KC_CLIENT_SECRET",
|
||||
"KC_USER",
|
||||
"KC_PASSWORD",
|
||||
"AUD_A",
|
||||
"AUD_B",
|
||||
]
|
||||
cfg = {k: os.environ[k] for k in os.environ if k.startswith(("KC_", "AUD_", "SCOPE_"))}
|
||||
missing = [k for k in required if not cfg.get(k)]
|
||||
if missing:
|
||||
print(f"Missing env: {', '.join(missing)} — run via keycloak_e2e.sh")
|
||||
return 2
|
||||
|
||||
print("Headless password login to Keycloak (the credential the feature captures)...")
|
||||
refresh_token = _password_login(cfg)
|
||||
|
||||
asyncio.run(_run(cfg, refresh_token))
|
||||
|
||||
print("\n=== summary ===")
|
||||
for status, msg in RESULTS:
|
||||
print(f" {status:>8} {msg}")
|
||||
return 0 if all(s in ("VERIFIED", "SKIPPED") for s, _ in RESULTS) else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,65 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# OSS-path (RFC 8693) end-to-end: spin up ephemeral Keycloak, configure the
|
||||
# realm, run keycloak_e2e.py against the REAL Turnstone mint engine, tear down.
|
||||
# Fully headless — no browser. Manual test tooling, not run in CI.
|
||||
set -euo pipefail
|
||||
cd "$(dirname "$0")/../.." # repo root (uv run needs it)
|
||||
|
||||
CONTAINER=kc-obo-e2e
|
||||
PORT=8091
|
||||
KC="docker exec $CONTAINER /opt/keycloak/bin/kcadm.sh"
|
||||
|
||||
cleanup() { docker rm -f "$CONTAINER" >/dev/null 2>&1 || true; }
|
||||
trap cleanup EXIT
|
||||
cleanup
|
||||
|
||||
echo ">> starting Keycloak 26.3 (ephemeral)..."
|
||||
docker run -d --name "$CONTAINER" -p "127.0.0.1:${PORT}:8080" \
|
||||
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
|
||||
quay.io/keycloak/keycloak:26.3 start-dev >/dev/null
|
||||
|
||||
echo ">> waiting for Keycloak (dev-mode boot can take a few minutes on a loaded host)..."
|
||||
# Wait on kcadm auth succeeding directly — more reliable than the host HTTP port,
|
||||
# and generous enough for a resource-starved boot (up to ~6 min).
|
||||
ready=""
|
||||
for _ in $(seq 1 90); do
|
||||
if $KC config credentials --server http://localhost:8080 --realm master \
|
||||
--user admin --password admin >/dev/null 2>&1; then
|
||||
ready=1
|
||||
break
|
||||
fi
|
||||
sleep 4
|
||||
done
|
||||
[ -n "$ready" ] || { echo "Keycloak did not become ready in time"; docker logs "$CONTAINER" 2>&1 | tail -15; exit 1; }
|
||||
|
||||
echo ">> configuring realm 'spike'..."
|
||||
$KC create realms -s realm=spike -s enabled=true >/dev/null
|
||||
# Confidential client with standard token exchange (the RFC 8693 leg) + direct
|
||||
# access grant (headless password login to fetch the user's refresh token).
|
||||
$KC create clients -r spike -s clientId=turnstone -s enabled=true -s publicClient=false \
|
||||
-s secret=spike-secret -s directAccessGrantsEnabled=true \
|
||||
-s 'attributes={"standard.token.exchange.enabled":"true"}' >/dev/null
|
||||
for t in mcp-a mcp-b mcp-c; do
|
||||
$KC create clients -r spike -s clientId=$t -s enabled=true -s publicClient=false -s secret=x >/dev/null
|
||||
done
|
||||
$KC create users -r spike -s username=e2e-user -s enabled=true -s email=e2e@spike.test \
|
||||
-s emailVerified=true -s firstName=E2E -s lastName=User >/dev/null
|
||||
$KC set-password -r spike --username e2e-user --new-password e2e-pw >/dev/null
|
||||
|
||||
TURNSTONE_UUID=$($KC get clients -r spike -q clientId=turnstone --fields id --format csv --noquotes)
|
||||
# Audience client scopes for mcp-a and mcp-b ONLY (mcp-c stays unconsented → E6).
|
||||
for t in mcp-a mcp-b; do
|
||||
SID=$($KC create client-scopes -r spike -s name=aud-$t -s protocol=openid-connect -i)
|
||||
$KC create "client-scopes/$SID/protocol-mappers/models" -r spike -s name=aud-$t \
|
||||
-s protocol=openid-connect -s protocolMapper=oidc-audience-mapper \
|
||||
-s "config={\"included.client.audience\":\"$t\",\"access.token.claim\":\"true\"}" >/dev/null
|
||||
$KC update "clients/$TURNSTONE_UUID/optional-client-scopes/$SID" -r spike >/dev/null
|
||||
done
|
||||
|
||||
echo ">> running the product e2e harness..."
|
||||
export KC_TOKEN_ENDPOINT="http://127.0.0.1:${PORT}/realms/spike/protocol/openid-connect/token"
|
||||
export KC_ISSUER="http://127.0.0.1:${PORT}/realms/spike"
|
||||
export KC_CLIENT_ID=turnstone KC_CLIENT_SECRET=spike-secret
|
||||
export KC_USER=e2e-user KC_PASSWORD=e2e-pw
|
||||
export AUD_A=mcp-a SCOPE_A=aud-mcp-a AUD_B=mcp-b SCOPE_B=aud-mcp-b AUD_C=mcp-c
|
||||
uv run python scripts/obo-e2e/keycloak_e2e.py
|
||||
File diff suppressed because it is too large
Load Diff
@@ -185,8 +185,8 @@ esac
|
||||
|
||||
echo ""
|
||||
echo "NOTE: If you added a NEW library (not just updating a version), also update"
|
||||
echo " _VERSIONED_VENDOR_DIR in turnstone/core/web_helpers.py — it controls both"
|
||||
echo " HTML version rewriting and immutable static-response caching."
|
||||
echo " the _ASSET_RE regex in turnstone/core/web_helpers.py — its negative lookahead"
|
||||
echo " skips vendored directories to avoid double-versioning static asset URLs."
|
||||
echo ""
|
||||
echo "Verify the update:"
|
||||
echo " git diff --stat"
|
||||
|
||||
+55
-1888
File diff suppressed because it is too large
Load Diff
@@ -2,7 +2,7 @@
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "turnstone Server API",
|
||||
"version": "1.8.0a7",
|
||||
"version": "1.7.0a6",
|
||||
"description": "Single-node workstream management, chat interaction, and real-time streaming."
|
||||
},
|
||||
"paths": {
|
||||
@@ -55,7 +55,7 @@
|
||||
"tags": [
|
||||
"Workstreams"
|
||||
],
|
||||
"description": "Accepts two content types. Default is `application/json` with a `CreateWorkstreamRequest` body. Alternatively, `multipart/form-data` with one `meta` field (JSON-encoded `CreateWorkstreamRequest` shape) plus zero-or-more `file` parts saves each file as an attachment under the new workstream. When `initial_message` is also set, attachments are resolved onto that turn before the worker thread dispatches; otherwise they remain pending for a follow-up `POST /v1/api/workstreams/{ws_id}/send`. Setting `resume_ws` atomically forks the visible source history, configuration, project, persona, and attachment references into a distinct destination; it does not reopen or mutate the source. Attachments and `resume_ws` cannot be combined. Creation stays unpublished until validation and the optional fork transaction complete.",
|
||||
"description": "Accepts two content types. Default is `application/json` with a `CreateWorkstreamRequest` body. Alternatively, `multipart/form-data` with one `meta` field (JSON-encoded `CreateWorkstreamRequest` shape) plus zero-or-more `file` parts saves each file as an attachment under the new workstream. When `initial_message` is also set, attachments are resolved onto that turn before the worker thread dispatches; otherwise they remain pending for a follow-up `POST /v1/api/workstreams/{ws_id}/send`.",
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
@@ -87,26 +87,6 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Error 403",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Error 404",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "Error 409",
|
||||
"content": {
|
||||
@@ -126,36 +106,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"429": {
|
||||
"description": "Error 429",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error 500",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"503": {
|
||||
"description": "Error 503",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -167,7 +117,6 @@
|
||||
"tags": [
|
||||
"Workstreams"
|
||||
],
|
||||
"description": "Unloads the live workstream while preserving storage. Returns 409 when any accepted live conversation row still requires persistence reconciliation; the workstream remains loaded and its history journal is retained.",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "ws_id",
|
||||
@@ -218,16 +167,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "Error 409",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -289,16 +228,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "Error 409",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -396,7 +325,7 @@
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ApproveResponse"
|
||||
"$ref": "#/components/schemas/StatusResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -410,16 +339,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "Error 409",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -471,26 +390,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "Error 409",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"503": {
|
||||
"description": "Error 503",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -513,7 +412,7 @@
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": false,
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
@@ -528,7 +427,7 @@
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/CancelResponse"
|
||||
"$ref": "#/components/schemas/StatusResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -563,7 +462,6 @@
|
||||
"tags": [
|
||||
"Chat"
|
||||
],
|
||||
"description": "Claims the workstream mutation slot, durably truncates the requested tail, then emits clear_ui. Concurrent sends are ordered after the cut; a storage failure returns 503 without changing live history.",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "ws_id",
|
||||
@@ -614,16 +512,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"503": {
|
||||
"description": "Error 503",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -635,7 +523,6 @@
|
||||
"tags": [
|
||||
"Chat"
|
||||
],
|
||||
"description": "Uses one workstream worker claim for the durable truncation and the replacement generation, so another send cannot enter between them. A storage failure returns 503 without changing live history.",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "ws_id",
|
||||
@@ -676,16 +563,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"503": {
|
||||
"description": "Error 503",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -697,7 +574,7 @@
|
||||
"tags": [
|
||||
"Streaming"
|
||||
],
|
||||
"description": "Opens a Server-Sent Events stream scoped to a single workstream. After rendering REST history, pass its opaque handoff_token once as ?history_token=; it names the exact accepted conversation-row prefix used for that render. A history_resync event closes this stream and requires a fresh history read; numeric event replay is not a substitute. Native Last-Event-ID reconnects take priority. Pass ?user_turn=1 to opt into typed accepted-user events; otherwise those rows become a backward-compatible strong-repair frame. Pass ?tool_turn=1 to receive the final accepted tool row as a typed tool_result with accepted=true; without it, accepted tool rows use the same pre-row strong-repair projection. Returns text/event-stream. See API reference for event types.",
|
||||
"description": "Opens a Server-Sent Events stream scoped to a single workstream. Returns text/event-stream. See API reference for event types.",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "ws_id",
|
||||
@@ -706,42 +583,6 @@
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "last_event_id",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer"
|
||||
},
|
||||
"description": "Numeric per-workstream event cursor for manual reconnects."
|
||||
},
|
||||
{
|
||||
"name": "history_token",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Opaque one-shot token naming the accepted prefix rendered from REST history."
|
||||
},
|
||||
{
|
||||
"name": "user_turn",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer"
|
||||
},
|
||||
"description": "Set to 1 to receive typed user_turn events instead of history-repair frames."
|
||||
},
|
||||
{
|
||||
"name": "tool_turn",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer"
|
||||
},
|
||||
"description": "Set to 1 to receive final accepted tool_result projections."
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
@@ -768,7 +609,7 @@
|
||||
"tags": [
|
||||
"Streaming"
|
||||
],
|
||||
"description": "Server-Sent Events stream for node-level state broadcasts. Emits a node_snapshot event on connect (workstreams, health, aggregate), followed by real-time delta events (ws_state, ws_activity, ws_created, ws_closed, ws_rename, health_changed, aggregate). Pass ?expected_node_id=X for identity verification (returns 409 on mismatch). Every event's SSE id is an opaque '{boot_epoch}-{counter}' string; presenting it on reconnect (Last-Event-ID header or ?last_event_id=) replays missed events, or emits a replay_truncated event (reason: ring_evicted with lost_count + earliest_available_id, or boot_epoch when the cursor predates this server process) followed by a fresh node_snapshot. Treat the id as opaque \u2014 its format may change.",
|
||||
"description": "Server-Sent Events stream for node-level state broadcasts. Emits a node_snapshot event on connect (workstreams, health, aggregate), followed by real-time delta events (ws_state, ws_activity, ws_created, ws_closed, ws_rename, health_changed, aggregate). Pass ?expected_node_id=X for identity verification (returns 409 on mismatch).",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Success"
|
||||
@@ -1041,7 +882,7 @@
|
||||
"tags": [
|
||||
"Workstreams"
|
||||
],
|
||||
"description": "Returns the tail of the conversation in OpenAI-like message format. Persisted-but-not-loaded workstreams (closed / evicted) are rehydrated before history is served so every successful response participates in the REST-to-SSE handoff. Lifted from the coord-only surface in the Stage 2 history/detail verb lift \u2014 interactive previously only exposed history through the SSE replay on ``/events``. Messages are the requested limit-bounded tail of one authoritative total accepted conversation-row prefix: user, assistant, tool, and system rows, including projected compaction checkpoints and cancellation markers. The opaque handoff_token names the exact prefix used for the render and is passed once on initial SSE registration. Admission of a later row changes the token; durable acknowledgement does not. If the durable prefix cannot be loaded, the endpoint returns 503 with `History temporarily unavailable`; that response is not authoritative and supplies no usable handoff token.",
|
||||
"description": "Returns the tail of the conversation in OpenAI-like message format. Persisted-but-not-loaded workstreams (closed / evicted) serve history without rehydrating. Lifted from the coord-only surface in the Stage 2 history/detail verb lift \u2014 interactive previously only exposed history through the SSE replay on ``/events``.",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "ws_id",
|
||||
@@ -1869,7 +1710,7 @@
|
||||
},
|
||||
"/v1/api/memories": {
|
||||
"get": {
|
||||
"summary": "List structured memories. Without a scope, returns global plus the authenticated user's memories; workstream scope is owner-bound.",
|
||||
"summary": "List structured memories",
|
||||
"operationId": "v1_api_memories_get",
|
||||
"tags": [
|
||||
"Memories"
|
||||
@@ -1891,7 +1732,7 @@
|
||||
"schema": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Filter by public scope: global, workstream, or user"
|
||||
"description": "Filter by scope"
|
||||
},
|
||||
{
|
||||
"name": "scope_id",
|
||||
@@ -1923,46 +1764,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Error 400",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Error 403",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Error 404",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error 500",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -2002,43 +1803,13 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Error 403",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Error 404",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error 500",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v1/api/memories/search": {
|
||||
"post": {
|
||||
"summary": "Search structured memories by query. Without a scope, searches global plus the authenticated user's memories.",
|
||||
"summary": "Search structured memories by query",
|
||||
"operationId": "v1_api_memories_search_post",
|
||||
"tags": [
|
||||
"Memories"
|
||||
@@ -2063,46 +1834,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Error 400",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Error 403",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Error 404",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error 500",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -2153,26 +1884,6 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Error 400",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Error 403",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Error 404",
|
||||
"content": {
|
||||
@@ -2182,16 +1893,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Error 500",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -2533,22 +2234,6 @@
|
||||
"title": "Message",
|
||||
"type": "string"
|
||||
},
|
||||
"client_send_id": {
|
||||
"anyOf": [
|
||||
{
|
||||
"maxLength": 128,
|
||||
"minLength": 1,
|
||||
"pattern": "^[A-Za-z0-9_-]+$",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"default": null,
|
||||
"description": "Opaque browser correlation token echoed in the accepted `user_turn` event and history row. It is not an idempotency key; repeated sends with the same value remain distinct turns.",
|
||||
"title": "Client Send Id"
|
||||
},
|
||||
"attachment_ids": {
|
||||
"anyOf": [
|
||||
{
|
||||
@@ -2575,23 +2260,16 @@
|
||||
"SendResponse": {
|
||||
"properties": {
|
||||
"status": {
|
||||
"description": "'ok' (fresh turn dispatched), 'queued' (folded into the live turn's interjection queue, or \u2014 when `deferred` is true \u2014 parked for dispatch after the current command window), 'queue_full', 'attachments_busy' (attachments can't ride a queued turn; retry when idle), or 'cross_user_interjection' (another participant's turn is in flight; carried on the 409 body).",
|
||||
"description": "'ok', 'busy', 'queued', or 'queue_full'",
|
||||
"examples": [
|
||||
"ok",
|
||||
"busy",
|
||||
"queued",
|
||||
"queue_full",
|
||||
"attachments_busy",
|
||||
"cross_user_interjection"
|
||||
"queue_full"
|
||||
],
|
||||
"title": "Status",
|
||||
"type": "string"
|
||||
},
|
||||
"deferred": {
|
||||
"default": false,
|
||||
"description": "Set on `queued` responses: the message is parked on the workstream's deferred-send list (a slash-command window holds the worker slot, or earlier deferred sends are still pending) and dispatches as an ordinary full-fidelity send afterwards \u2014 it is NOT in a live turn's interjection queue. `DELETE .../send` retracts it until dispatch. Node-local and in-memory: a node restart before dispatch drops it (at-most-once intake).",
|
||||
"title": "Deferred",
|
||||
"type": "boolean"
|
||||
},
|
||||
"attached_ids": {
|
||||
"description": "Attachment ids actually attached to this turn. Subset of the request's `attachment_ids` (or the auto-consumed pending set). Empty when the send carries no attachments.",
|
||||
"items": {
|
||||
@@ -2681,32 +2359,6 @@
|
||||
"description": "Auto-approve the tools in this batch going forward",
|
||||
"title": "Always",
|
||||
"type": "boolean"
|
||||
},
|
||||
"cycle_id": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"default": null,
|
||||
"description": "Resolve this exact approval cycle",
|
||||
"title": "Cycle Id"
|
||||
},
|
||||
"call_id": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"default": null,
|
||||
"description": "Resolve the approval cycle containing this tool call",
|
||||
"title": "Call Id"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
@@ -2715,35 +2367,10 @@
|
||||
"title": "ApproveRequest",
|
||||
"type": "object"
|
||||
},
|
||||
"ApproveResponse": {
|
||||
"properties": {
|
||||
"status": {
|
||||
"default": "ok",
|
||||
"description": "Request outcome",
|
||||
"title": "Status",
|
||||
"type": "string"
|
||||
},
|
||||
"cycle_id": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"default": null,
|
||||
"description": "Approval cycle that was resolved, or null when none was pending",
|
||||
"title": "Cycle Id"
|
||||
}
|
||||
},
|
||||
"title": "ApproveResponse",
|
||||
"type": "object"
|
||||
},
|
||||
"CommandRequest": {
|
||||
"properties": {
|
||||
"command": {
|
||||
"description": "Workstream-local slash command (for example /clear or /instructions). Lifecycle commands such as /new and /resume are local-CLI-only; remote clients use the dedicated workstream endpoints.",
|
||||
"description": "Slash command (e.g. /clear, /new, /resume)",
|
||||
"title": "Command",
|
||||
"type": "string"
|
||||
},
|
||||
@@ -2772,24 +2399,6 @@
|
||||
"title": "CancelRequest",
|
||||
"type": "object"
|
||||
},
|
||||
"CancelResponse": {
|
||||
"properties": {
|
||||
"status": {
|
||||
"default": "ok",
|
||||
"description": "Request outcome",
|
||||
"title": "Status",
|
||||
"type": "string"
|
||||
},
|
||||
"dropped": {
|
||||
"additionalProperties": true,
|
||||
"description": "Best-effort, credential-redacted snapshot of pending work affected by cancellation; keys are omitted when not observable",
|
||||
"title": "Dropped",
|
||||
"type": "object"
|
||||
}
|
||||
},
|
||||
"title": "CancelResponse",
|
||||
"type": "object"
|
||||
},
|
||||
"RewindRequest": {
|
||||
"properties": {
|
||||
"turns": {
|
||||
@@ -2819,43 +2428,15 @@
|
||||
"title": "Model",
|
||||
"type": "string"
|
||||
},
|
||||
"judge_model": {
|
||||
"default": "",
|
||||
"description": "Optional judge model alias for this workstream. Empty uses the server's configured judge model.",
|
||||
"title": "Judge Model",
|
||||
"type": "string"
|
||||
},
|
||||
"auto_approve": {
|
||||
"default": false,
|
||||
"description": "Auto-approve all tool calls",
|
||||
"title": "Auto Approve",
|
||||
"type": "boolean"
|
||||
},
|
||||
"auto_approve_tools": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
}
|
||||
],
|
||||
"default": "",
|
||||
"description": "Tool names to auto-approve even when auto_approve is false, accepted as either a comma-separated string or an array of strings.",
|
||||
"title": "Auto Approve Tools"
|
||||
},
|
||||
"user_id": {
|
||||
"default": "",
|
||||
"description": "Optional workstream owner override. Honored only for trusted service identities (currently the console); ordinary callers remain bound to their authenticated user id.",
|
||||
"title": "User Id",
|
||||
"type": "string"
|
||||
},
|
||||
"resume_ws": {
|
||||
"default": "",
|
||||
"description": "Source workstream ID or alias to fork atomically into the new workstream (empty = fresh start)",
|
||||
"description": "Workstream ID to resume atomically during creation (empty = fresh start)",
|
||||
"title": "Resume Ws",
|
||||
"type": "string"
|
||||
},
|
||||
@@ -2892,7 +2473,7 @@
|
||||
},
|
||||
"client_type": {
|
||||
"default": "",
|
||||
"description": "Client surface type (web, cli, chat, scheduled). Defaults to web for server-created sessions.",
|
||||
"description": "Client surface type (web, cli, chat). Defaults to web for server-created sessions.",
|
||||
"title": "Client Type",
|
||||
"type": "string"
|
||||
},
|
||||
@@ -2966,13 +2547,13 @@
|
||||
},
|
||||
"resumed": {
|
||||
"default": false,
|
||||
"description": "Whether the requested source was successfully forked",
|
||||
"description": "Whether a previous workstream was resumed",
|
||||
"title": "Resumed",
|
||||
"type": "boolean"
|
||||
},
|
||||
"message_count": {
|
||||
"default": 0,
|
||||
"description": "Number of messages cloned into the new workstream",
|
||||
"description": "Number of messages in the resumed workstream",
|
||||
"title": "Message Count",
|
||||
"type": "integer"
|
||||
},
|
||||
@@ -2983,15 +2564,6 @@
|
||||
},
|
||||
"title": "Attachment Ids",
|
||||
"type": "array"
|
||||
},
|
||||
"initial_message_status": {
|
||||
"description": "Present ONLY when the workstream was created but its initial_message could not be delivered: 'queue_full' (a raced live worker's interjection queue was at capacity \u2014 resend via /send; any uploads stay staged) or 'refused_closed' (the workstream was closed mid-create). Absent whenever the message was dispatched.",
|
||||
"enum": [
|
||||
"queue_full",
|
||||
"refused_closed"
|
||||
],
|
||||
"title": "Initial Message Status",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
@@ -3085,18 +2657,6 @@
|
||||
],
|
||||
"default": null,
|
||||
"title": "Project Id"
|
||||
},
|
||||
"persistence_state": {
|
||||
"default": "healthy",
|
||||
"description": "Sanitized durable-history status for the loaded workstream: healthy, pending its first save, retrying automatically, or blocked by a permanent commit conflict. Older servers and unloaded rows default to healthy.",
|
||||
"enum": [
|
||||
"healthy",
|
||||
"pending",
|
||||
"retrying",
|
||||
"conflict"
|
||||
],
|
||||
"title": "Persistence State",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
@@ -3130,18 +2690,6 @@
|
||||
"$ref": "#/components/schemas/WorkstreamKind",
|
||||
"default": "interactive"
|
||||
},
|
||||
"persistence_state": {
|
||||
"default": "healthy",
|
||||
"description": "Sanitized durable-history status: healthy, pending its first save, retrying automatically, or blocked by a permanent commit conflict.",
|
||||
"enum": [
|
||||
"healthy",
|
||||
"pending",
|
||||
"retrying",
|
||||
"conflict"
|
||||
],
|
||||
"title": "Persistence State",
|
||||
"type": "string"
|
||||
},
|
||||
"pending_approval": {
|
||||
"default": false,
|
||||
"description": "True when at least one approval cycle is live (a gate thread parked awaiting an operator approve/deny). Mirrors the same field on ``DashboardWorkstream`` / cluster live projections so a freshly-loaded chat tab can render the inline approval gate from the detail snapshot before SSE replay arrives.",
|
||||
@@ -3199,7 +2747,7 @@
|
||||
"type": "object"
|
||||
},
|
||||
"PendingApprovalItem": {
|
||||
"description": "One pending tool-call inside a ``PendingApprovalDetail`` envelope.\n\nMirrors the dict ``SessionUIBase.serialize_pending_approval_details``\nemits per item inside each cycle entry. ``heuristic_verdict`` / ``judge_verdict`` are kept\nloosely-typed because the underlying verdict shape varies by tier;\nconsumers that want the full structure can decode against\n:class:`turnstone.sdk.events.IntentVerdictEvent`.",
|
||||
"description": "One pending tool-call inside a ``PendingApprovalDetail`` envelope.\n\nMirrors the dict ``SessionUIBase.serialize_pending_approval_detail``\nemits per item. ``heuristic_verdict`` / ``judge_verdict`` are kept\nloosely-typed because the underlying verdict shape varies by tier;\nconsumers that want the full structure can decode against\n:class:`turnstone.sdk.events.IntentVerdictEvent`.",
|
||||
"properties": {
|
||||
"call_id": {
|
||||
"default": "",
|
||||
@@ -3281,7 +2829,7 @@
|
||||
"type": "string"
|
||||
},
|
||||
"messages": {
|
||||
"description": "Requested limit-bounded tail of one authoritative total accepted conversation-row prefix, projected to the canonical render shape. Roles include ``user``, ``assistant``, ``tool``, and ``system``; compaction checkpoints project as ``role=system, source=compaction`` and cancellation-generated assistant/tool markers appear when present. The projection also carries flat tool_calls with verdict / output_assessment; top-level source / attachments / reasoning; and derived denied / is_error / pending. Bounded by the ``limit`` query parameter (default 100, max 500).",
|
||||
"description": "Tail of the workstream's message history, projected to the canonical render shape (``role`` may be ``system`` for operator-context turns; flat tool_calls with verdict / output_assessment; top-level source / attachments / reasoning; derived denied / is_error / pending). Bounded by the ``limit`` query parameter (default 100, max 500).",
|
||||
"items": {
|
||||
"additionalProperties": true,
|
||||
"type": "object"
|
||||
@@ -3301,19 +2849,6 @@
|
||||
"default": null,
|
||||
"description": "SSE resume cursor (a ``Last-Event-ID`` value). Non-null only when the trailing turn is an executing in-flight tool batch that the live ring buffer can replay: ``messages`` then omits that turn and the client opens its initial SSE with this cursor so the existing delta replay fast-forwards the in-flight turn (tool calls, results, prompts) instead of the lossy synthetic snapshot. Null on every other read \u2014 the client connects fresh.",
|
||||
"title": "Cursor"
|
||||
},
|
||||
"handoff_token": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"default": null,
|
||||
"description": "Opaque token naming the exact accepted conversation-row prefix used for this render. Present only while the workstream is loaded. A client that renders this response passes the token once as the initial event stream's ``history_token`` query parameter; the server atomically validates it while registering the listener. Admission of a later row changes the token; durable acknowledgement does not. Clients must not inspect, persist, or reuse it for later reconnects.",
|
||||
"title": "Handoff Token"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
@@ -3471,18 +3006,6 @@
|
||||
"default": null,
|
||||
"title": "Project Id"
|
||||
},
|
||||
"persistence_state": {
|
||||
"default": "healthy",
|
||||
"description": "Sanitized durable-history status for this live row. Contains no storage error, commit key, retry count, or conversation content.",
|
||||
"enum": [
|
||||
"healthy",
|
||||
"pending",
|
||||
"retrying",
|
||||
"conflict"
|
||||
],
|
||||
"title": "Persistence State",
|
||||
"type": "string"
|
||||
},
|
||||
"pending_approval_details": {
|
||||
"description": "Inline approval payload for the coordinator children-tree UI: EVERY live approval cycle, oldest first \u2014 parallel task agents gate concurrently, so a workstream can hold several prompts at once. Each entry carries the cycle's items + per-call_id LLM verdict cache so a coord can render approve/deny buttons + judge pill without a separate per-child round-trip; resolve each with its ``cycle_id``. Empty when no approval is pending. Also surfaced (verbatim) on ``GET /v1/api/cluster/ws/live`` via the ``_CLUSTER_WS_LIVE_KEYS`` projection. Replaces 1.6's ``pending_approval_detail`` single-object field (breaking, 1.7).",
|
||||
"items": {
|
||||
@@ -3994,42 +3517,32 @@
|
||||
"properties": {
|
||||
"name": {
|
||||
"description": "Memory identifier (normalized to snake_case)",
|
||||
"maxLength": 256,
|
||||
"minLength": 1,
|
||||
"title": "Name",
|
||||
"type": "string"
|
||||
},
|
||||
"content": {
|
||||
"description": "Memory content",
|
||||
"maxLength": 65536,
|
||||
"minLength": 1,
|
||||
"title": "Content",
|
||||
"type": "string"
|
||||
},
|
||||
"description": {
|
||||
"description": "Required non-empty description used for relevance matching",
|
||||
"minLength": 1,
|
||||
"default": "",
|
||||
"description": "Short description for relevance matching",
|
||||
"title": "Description",
|
||||
"type": "string"
|
||||
},
|
||||
"type": {
|
||||
"anyOf": [
|
||||
{
|
||||
"enum": [
|
||||
"user",
|
||||
"general",
|
||||
"feedback",
|
||||
"reference"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
"default": "general",
|
||||
"description": "Memory type",
|
||||
"enum": [
|
||||
"user",
|
||||
"general",
|
||||
"feedback",
|
||||
"reference"
|
||||
],
|
||||
"default": null,
|
||||
"description": "Memory type; omission preserves it on update and defaults on insert",
|
||||
"title": "Type"
|
||||
"title": "Type",
|
||||
"type": "string"
|
||||
},
|
||||
"scope": {
|
||||
"default": "global",
|
||||
@@ -4051,8 +3564,7 @@
|
||||
},
|
||||
"required": [
|
||||
"name",
|
||||
"content",
|
||||
"description"
|
||||
"content"
|
||||
],
|
||||
"title": "SaveMemoryRequest",
|
||||
"type": "object"
|
||||
@@ -4146,7 +3658,6 @@
|
||||
"properties": {
|
||||
"query": {
|
||||
"description": "Search query text",
|
||||
"minLength": 1,
|
||||
"title": "Query",
|
||||
"type": "string"
|
||||
},
|
||||
|
||||
Generated
+286
-555
File diff suppressed because it is too large
Load Diff
@@ -32,7 +32,7 @@
|
||||
],
|
||||
"license": "Apache-2.0",
|
||||
"devDependencies": {
|
||||
"typescript": "^7.0.0",
|
||||
"typescript": "^6.0.0",
|
||||
"vitest": "^4.1"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -18,6 +18,8 @@ import type {
|
||||
ConsoleCreateWsRequest,
|
||||
ConsoleCreateWsResponse,
|
||||
ConsoleHealthResponse,
|
||||
CreateWorkstreamRequest,
|
||||
CreateWorkstreamResponse,
|
||||
ListAttachmentsResponse,
|
||||
CreateMcpServerRequest,
|
||||
CreatePolicyOptions,
|
||||
@@ -37,9 +39,6 @@ import type {
|
||||
McpServerDetail,
|
||||
RegistryInstallRequest,
|
||||
RegistrySearchResponse,
|
||||
RouteCreateRequest,
|
||||
RouteCreateResponse,
|
||||
RouteLiveResponse,
|
||||
SkillDiscoverResponse,
|
||||
SkillInfo,
|
||||
SkillInstallRequest,
|
||||
@@ -155,8 +154,10 @@ export class TurnstoneConsole extends BaseClient {
|
||||
* owning node directly.
|
||||
*/
|
||||
async routeCreateWorkstream(
|
||||
opts?: RouteCreateRequest,
|
||||
): Promise<RouteCreateResponse> {
|
||||
opts?: CreateWorkstreamRequest & { target_node?: string },
|
||||
): Promise<
|
||||
CreateWorkstreamResponse & { node_url?: string; node_id?: string }
|
||||
> {
|
||||
const attachments = opts?.attachments;
|
||||
if (attachments && attachments.length > 0) {
|
||||
// The console's multipart route_create routes by `?ws_id=` only —
|
||||
@@ -191,13 +192,6 @@ export class TurnstoneConsole extends BaseClient {
|
||||
});
|
||||
}
|
||||
|
||||
async routeWorkstreamLive(wsId: string): Promise<RouteLiveResponse> {
|
||||
return this.request(
|
||||
"GET",
|
||||
`/v1/api/route/workstreams/${encodeURIComponent(wsId)}/live`,
|
||||
);
|
||||
}
|
||||
|
||||
async routeUploadAttachment(
|
||||
wsId: string,
|
||||
file: AttachmentUpload,
|
||||
|
||||
@@ -1,8 +1,4 @@
|
||||
import type {
|
||||
ClusterOverviewResponse,
|
||||
ClusterSnapshotNode,
|
||||
ConversationPersistenceState,
|
||||
} from "./types.js";
|
||||
import type { ClusterOverviewResponse, ClusterSnapshotNode } from "./types.js";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Server SSE events
|
||||
@@ -39,37 +35,6 @@ export interface HistoryEvent {
|
||||
messages: Array<Record<string, unknown>>;
|
||||
}
|
||||
|
||||
/**
|
||||
* The REST history rendered by the caller no longer names the live accepted
|
||||
* row prefix. Stop this stream, refetch and render history, then open a new
|
||||
* stream with its cursor and one-shot token. The SDK does not do this
|
||||
* automatically.
|
||||
*/
|
||||
export interface HistoryResyncEvent {
|
||||
type: "history_resync";
|
||||
/** Present on registration-time handoff mismatches; implied by a scoped stream. */
|
||||
ws_id?: string;
|
||||
reason: string;
|
||||
}
|
||||
|
||||
/** One accepted user row, projected live to every workstream consumer. */
|
||||
export interface UserTurnEvent {
|
||||
type: "user_turn";
|
||||
ws_id?: string;
|
||||
content: string;
|
||||
attachments?: Array<{
|
||||
attachment_id: string;
|
||||
kind: string;
|
||||
filename: string;
|
||||
mime_type: string;
|
||||
}>;
|
||||
sender?: string;
|
||||
source?: string;
|
||||
/** Optimistic-browser correlation only; not delivery idempotency. */
|
||||
client_send_ids: string[];
|
||||
_event_id?: number;
|
||||
}
|
||||
|
||||
export interface ThinkingStartEvent {
|
||||
type: "thinking_start";
|
||||
}
|
||||
@@ -147,12 +112,6 @@ export interface ToolResultEvent {
|
||||
name: string;
|
||||
output: string;
|
||||
is_error?: boolean;
|
||||
preview?: Record<string, unknown>;
|
||||
/** True only for the final guarded row accepted into conversation history. */
|
||||
accepted?: boolean;
|
||||
effect_status?: string;
|
||||
/** Monotonic accepted-row identity; present for projection-capable clients. */
|
||||
_event_id?: number;
|
||||
}
|
||||
|
||||
export interface ToolOutputChunkEvent {
|
||||
@@ -198,49 +157,6 @@ export interface CancelledEvent {
|
||||
type: "cancelled";
|
||||
}
|
||||
|
||||
/**
|
||||
* Context-compaction lifecycle. `start` carries `trigger` ("manual"/"auto";
|
||||
* auto adds `where` + `pct`); `progress` carries chunked-summarization
|
||||
* `part`/`total`/`depth` (or `retry_in`/`error` for a retry wait); `end`
|
||||
* carries `ok` plus either `before_tokens`/`after_tokens`/`summary` or the
|
||||
* failure `reason`/`message`. The successful end's summary also replays from
|
||||
* `/history` as a `role: "system"`, `source: "compaction"` entry.
|
||||
*/
|
||||
export interface CompactionEvent {
|
||||
type: "compaction";
|
||||
phase: "start" | "progress" | "end";
|
||||
/** Correlates every event of one compaction run (0 from legacy emitters). */
|
||||
compaction_id?: number;
|
||||
/**
|
||||
* End events only: true marks a force-abandoned compaction retiring
|
||||
* after a successor generation took over — skip failure notices for
|
||||
* those (an OK end's result still stands; the history swap happened).
|
||||
*/
|
||||
superseded?: boolean;
|
||||
/**
|
||||
* Failed ends only: the emitter-computed display verdict — show
|
||||
* `message` only when true, instead of re-deriving suppression from
|
||||
* reason/trigger/superseded client-side.
|
||||
*/
|
||||
notice?: boolean;
|
||||
/** Present on start and on every end (ok or failed). */
|
||||
trigger?: "manual" | "auto";
|
||||
where?: string;
|
||||
pct?: number;
|
||||
part?: number;
|
||||
total?: number;
|
||||
depth?: number;
|
||||
retry_in?: number;
|
||||
error?: string;
|
||||
warning?: string;
|
||||
ok?: boolean;
|
||||
reason?: string;
|
||||
message?: string;
|
||||
before_tokens?: number;
|
||||
after_tokens?: number;
|
||||
summary?: string;
|
||||
}
|
||||
|
||||
// Global events
|
||||
|
||||
export interface WsStateEvent {
|
||||
@@ -251,8 +167,6 @@ export interface WsStateEvent {
|
||||
context_ratio: number;
|
||||
activity: string;
|
||||
activity_state: string;
|
||||
/** Defaults to `healthy` when omitted by an older node. */
|
||||
persistence_state?: ConversationPersistenceState;
|
||||
/** Full assistant response text — populated on idle transitions only. */
|
||||
content?: string;
|
||||
}
|
||||
@@ -280,8 +194,6 @@ export interface WsClosedEvent {
|
||||
export type ServerEvent =
|
||||
| ConnectedEvent
|
||||
| HistoryEvent
|
||||
| HistoryResyncEvent
|
||||
| UserTurnEvent
|
||||
| ThinkingStartEvent
|
||||
| ThinkingStopEvent
|
||||
| ContentEvent
|
||||
@@ -300,7 +212,6 @@ export type ServerEvent =
|
||||
| BusyErrorEvent
|
||||
| ClearUiEvent
|
||||
| CancelledEvent
|
||||
| CompactionEvent
|
||||
| WsStateEvent
|
||||
| WsActivityEvent
|
||||
| WsRenameEvent
|
||||
@@ -329,8 +240,6 @@ export interface ClusterStateEvent {
|
||||
context_ratio: number;
|
||||
activity: string;
|
||||
activity_state: string;
|
||||
/** Defaults to `healthy` when omitted by an older node. */
|
||||
persistence_state?: ConversationPersistenceState;
|
||||
}
|
||||
|
||||
export interface ClusterWsCreatedEvent {
|
||||
@@ -338,8 +247,6 @@ export interface ClusterWsCreatedEvent {
|
||||
ws_id: string;
|
||||
node_id: string;
|
||||
name: string;
|
||||
/** Defaults to `healthy` when omitted by an older node. */
|
||||
persistence_state?: ConversationPersistenceState;
|
||||
}
|
||||
|
||||
export interface ClusterWsClosedEvent {
|
||||
@@ -423,13 +330,3 @@ export function isApprovalResolvedEvent(
|
||||
export function isCancelledEvent(e: ServerEvent): e is CancelledEvent {
|
||||
return e.type === "cancelled";
|
||||
}
|
||||
|
||||
export function isHistoryResyncEvent(
|
||||
e: ServerEvent,
|
||||
): e is HistoryResyncEvent {
|
||||
return e.type === "history_resync";
|
||||
}
|
||||
|
||||
export function isUserTurnEvent(e: ServerEvent): e is UserTurnEvent {
|
||||
return e.type === "user_turn";
|
||||
}
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user