toolframe-core 0.6.2__py3-none-any.whl

toolframe_core/bundled_skills/toolframe-plugin-design/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 byfb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolframe_core/bundled_skills/toolframe-plugin-design/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: toolframe-plugin-design
+version: "0.3.2"
+description: Load when designing, creating, or extending a Toolframe business plugin, including its domain model, persistence, or dashboard and MCP interfaces. Excludes routine application operation, calling existing tools, standalone Streamlit apps, Codex plugins, and Toolframe runtime/provider internals.
+---
+
+# Toolframe plugin design
+
+Turn the user's business outcome into an independently packaged Toolframe plugin.
+This skill targets Toolframe Core 0.6.1 and SDK 0.3. The attached references and
+starter travel with the application; a Toolframe source checkout is optional.
+
+## Establish the design
+
+Identify the application home, existing plugin source (if any), and whether the
+request is design-only or includes implementation. Preserve existing plugin IDs
+and data ownership when extending a plugin.
+
+Read [design.md](references/design.md) when establishing or changing business
+behavior. Resolve the operations, invariants, data ownership and required user
+surfaces before choosing tables or widgets. Finish this stage with a concise
+design covering those decisions and any consequential unresolved questions.
+For a design-only request, deliver that design and stop before creating code or
+changing the application. An implementation request already authorizes ordinary
+coding; continue without an extra design-approval ceremony.
+
+## Implement the plugin
+
+For implementation, read [plugin-api.md](references/plugin-api.md) before defining
+services, storage or resources. Use public `toolframe_sdk` contracts. Business
+state belongs in provider-managed storage; business services own its meaning.
+Dashboard pages and MCP tools call those services.
+Declare owned read/write scopes and each method's audience. Use page permissions
+for navigation and controls; core enforces service permissions. Choose each entrance explicitly. Confidential applications need protected Dashboard
+access with `failure_mode="closed"`, a separate protected MCP policy, and no sensitive
+`public_api` methods or llms documents. Preserve an existing application's explicit
+policy until an authorized change. Method scopes do not provide person/tenant or
+row isolation. [plugin-api.md](references/plugin-api.md) defines these boundaries.
+
+For a **new** plugin, read [operations.md](references/operations.md), then run
+`toolframe --home APP plugin new PLUGIN-ID --json`. Customize the generated source
+at `APP/plugins/PLUGIN-ID/`; `--output PATH` selects an exact alternative directory.
+The CLI renders the core-packaged [Notes example](assets/sample-plugin), including
+consistent package, module and service identities. Generation alone leaves the
+application composition unchanged. Adapt its schema and behavior to the design;
+remove unneeded presentation resources, UI extras or storage declarations.
+For an **existing** plugin, edit its source directly; do not regenerate it.
+Generated sources belong to the application and survive binary/skill updates.
+Finish implementation with a buildable wheel, explicit scopes and service schemas and
+checks for the requested business rules.
+
+## Validate in the application
+
+When installing or testing code, read [operations.md](references/operations.md).
+Distinguish package validation, temporary runtime validation and active health.
+Existing-data migrations require a reviewed migration plan and an explicitly
+authorized apply; a normal reload does not apply them. Report evidence for the
+affected service and each requested presentation surface, retained data after
+reload, and any checks not run. An installed package alone is not completion.

toolframe_core/bundled_skills/toolframe-plugin-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Toolframe Plugin Design"
+  short_description: "Design and build custom Toolframe business plugins"
+  default_prompt: "Use $toolframe-plugin-design to design and implement a Toolframe plugin for my business workflow."

toolframe_core/bundled_skills/toolframe-plugin-design/assets/sample-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 byfb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolframe_core/bundled_skills/toolframe-plugin-design/assets/sample-plugin/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "toolframe-sample-notes"
+version = "0.1.0"
+description = "Small independently packaged Toolframe notes plugin"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = ["toolframe-sdk==0.3.0"]
+
+[project.optional-dependencies]
+ui = ["streamlit==1.61.0"]
+
+[project.entry-points."toolframe.plugins"]
+sample-notes = "toolframe_sample_notes.plugin:plugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/toolframe_sample_notes"]

toolframe_core/bundled_skills/toolframe-plugin-design/assets/sample-plugin/src/toolframe_sample_notes/__init__.py

@@ -0,0 +1 @@
+"""Sample Notes business plugin."""

toolframe_core/bundled_skills/toolframe-plugin-design/assets/sample-plugin/src/toolframe_sample_notes/docs/usage.md

@@ -0,0 +1,13 @@
+# Notes
+
+Capture a note of 1–1000 characters from the Notes dashboard. Notes are immutable;
+this example does not edit or delete them. The dashboard shows the newest 20.
+
+The read-only MCP tool `sample-notes__list_notes` accepts an optional integer
+`limit` from 1 to 100, default 20. It returns `notes` and `count`, where `count` is
+the number in this response. Each note has an `id`, `body` and UTC `created_at`.
+The MCP tool does not create notes.
+
+Notes remain stored when the plugin is disabled or reloaded. If a capture's result
+is uncertain after a lost connection, inspect the latest notes before submitting
+again; this sample does not deduplicate separate capture requests.

toolframe_core/bundled_skills/toolframe-plugin-design/assets/sample-plugin/src/toolframe_sample_notes/migrations/0001_init.sql

@@ -0,0 +1,5 @@
+CREATE TABLE notes (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    body TEXT NOT NULL CHECK (length(trim(body)) BETWEEN 1 AND 1000),
+    created_at TEXT NOT NULL
+);

toolframe_core/bundled_skills/toolframe-plugin-design/assets/sample-plugin/src/toolframe_sample_notes/page.py

@@ -0,0 +1,25 @@
+from toolframe_sdk import PageContext, PluginError
+
+
+def render(context: PageContext):
+    import streamlit as st
+
+    service = context.services.require("sample-notes.notes", version=1)
+    st.title("Notes")
+    with st.form("sample-notes-capture"):
+        body = st.text_area("New note", max_chars=1000, key="sample-notes-body")
+        if st.form_submit_button(
+            "Capture", disabled=not context.can("sample-notes.write")
+        ):
+            try:
+                service.call("capture", {"body": body})
+            except PluginError as error:
+                st.error(error.message)
+            else:
+                st.rerun()
+    try:
+        result = service.call("list_notes", {"limit": 20})
+    except PluginError as error:
+        st.error(error.message)
+        return
+    st.dataframe(result["notes"], hide_index=True, width="stretch")

toolframe_core/bundled_skills/toolframe-plugin-design/assets/sample-plugin/src/toolframe_sample_notes/plugin.py

@@ -0,0 +1,119 @@
+"""Definitions import without Streamlit or provider implementation dependencies."""
+
+from importlib.resources import files
+
+from toolframe_sdk import (
+    AuthorizationSpec,
+    MethodSpec,
+    Migration,
+    PluginDefinition,
+    Requirement,
+    Resource,
+    ScopeSpec,
+    ServiceSpec,
+    StoreSchema,
+)
+
+SERVICE = "sample-notes.notes"
+PACKAGE = "toolframe_sample_notes"
+NOTE = {
+    "type": "object",
+    "properties": {
+        "id": {"type": "integer", "minimum": 1},
+        "body": {"type": "string", "minLength": 1, "maxLength": 1000},
+        "created_at": {"type": "string"},
+    },
+    "required": ["id", "body", "created_at"],
+    "additionalProperties": False,
+}
+LIST_INPUT = {
+    "type": "object",
+    "properties": {
+        "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20},
+    },
+    "additionalProperties": False,
+}
+LIST_OUTPUT = {
+    "type": "object",
+    "properties": {
+        "notes": {"type": "array", "items": NOTE},
+        "count": {"type": "integer", "minimum": 0},
+    },
+    "required": ["notes", "count"],
+    "additionalProperties": False,
+}
+
+plugin = PluginDefinition(
+    id="sample-notes",
+    factory="toolframe_sample_notes.service:Notes",
+    authorization=AuthorizationSpec(
+        scopes={
+            "sample-notes.read": ScopeSpec(title="Read notes"),
+            "sample-notes.write": ScopeSpec(title="Capture notes"),
+        }
+    ),
+    requires={"storage": Requirement(service="toolframe.storage.sql")},
+    services={
+        SERVICE: ServiceSpec(
+            methods={
+                "capture": MethodSpec(
+                    audience="business",
+                    required_scopes=("sample-notes.write",),
+                    description="Capture a new note.",
+                    input_schema={
+                        "type": "object",
+                        "properties": {"body": NOTE["properties"]["body"]},
+                        "required": ["body"],
+                        "additionalProperties": False,
+                    },
+                    output_schema=NOTE,
+                ),
+                "list_notes": MethodSpec(
+                    audience="business",
+                    required_scopes=("sample-notes.read",),
+                    public_api=True,
+                    description="Read the newest notes.",
+                    input_schema=LIST_INPUT,
+                    output_schema=LIST_OUTPUT,
+                    read_only=True,
+                ),
+            }
+        )
+    },
+    store=StoreSchema(
+        revision="v1",
+        migrations=(
+            Migration(
+                revision="v1",
+                sql=files(PACKAGE).joinpath("migrations/0001_init.sql").read_text(),
+            ),
+        ),
+    ),
+    resources=(
+        Resource(
+            id="notes",
+            kind="dashboard.page",
+            title="Notes",
+            required_scopes=("sample-notes.read",),
+            data={"entrypoint": "toolframe_sample_notes.page:render", "order": 10},
+        ),
+        Resource(
+            id="list_notes",
+            kind="mcp.tool",
+            title="List notes",
+            data={
+                "service": SERVICE,
+                "method": "list_notes",
+                "description": "Read the newest captured notes.",
+                "input_schema": LIST_INPUT,
+                "output_schema": LIST_OUTPUT,
+            },
+        ),
+        Resource(
+            id="usage",
+            kind="llms.document",
+            title="Notes",
+            data={"package": PACKAGE, "path": "docs/usage.md"},
+        ),
+    ),
+)

toolframe_core/bundled_skills/toolframe-plugin-design/assets/sample-plugin/src/toolframe_sample_notes/service.py

@@ -0,0 +1,48 @@
+from datetime import UTC, datetime
+
+from toolframe_sdk import Plugin, PluginError
+
+from .plugin import SERVICE
+
+
+class Notes(Plugin):
+    async def capture(self, body):
+        if not isinstance(body, str) or not 1 <= len(body.strip()) <= 1000:
+            raise PluginError(
+                "note_invalid", "A note needs 1–1000 nonblank characters."
+            )
+        body = body.strip()
+        async with self.context.storage().transaction() as tx:
+            created = await tx.execute(
+                "INSERT INTO notes(body, created_at) VALUES (?, ?)",
+                (body, datetime.now(UTC).isoformat()),
+            )
+            rows = await tx.query(
+                "SELECT id, body, created_at FROM notes WHERE id = ?",
+                (created["lastrowid"],),
+            )
+            return rows[0]
+
+    async def list_notes(self, limit=20):
+        if (
+            isinstance(limit, bool)
+            or not isinstance(limit, int)
+            or not 1 <= limit <= 100
+        ):
+            raise PluginError("note_invalid", "limit must be an integer from 1 to 100.")
+        notes = await self.context.storage().query(
+            "SELECT id, body, created_at FROM notes ORDER BY id DESC LIMIT ?", (limit,)
+        )
+        return {"notes": notes, "count": len(notes)}
+
+    async def invoke(self, service, method, params):
+        if service == SERVICE:
+            if method == "capture":
+                return await self.capture(**params)
+            if method == "list_notes":
+                return await self.list_notes(**params)
+        raise PluginError("method_not_found", f"Unknown method {service}/{method}")
+
+    async def health(self):
+        await self.context.storage().query("SELECT id FROM notes LIMIT 1")
+        return {"runtime": "ready", "business": "ready"}

toolframe_core/bundled_skills/toolframe-plugin-design/references/design.md

@@ -0,0 +1,60 @@
+# Business design
+
+Use the user's vocabulary to define the smallest useful business capability.
+Toolframe's plugin boundary is a deployable package and a data owner; it need not
+be a folder per screen or a separate plugin for every entity.
+
+## From workflow to contract
+
+Record these decisions in the plugin's own design notes, at a level proportional
+to the request. Keep the notes outside the files published by `llms.document`.
+
+| Decision | Evidence needed before implementation |
+| --- | --- |
+| Outcome and actors | Who performs which operation, and what successful completion means. |
+| Vocabulary and identity | Stable business identities and the meaning of statuses, units, dates and money. |
+| Invariants | Rules that must hold even when a page, MCP tool and another plugin call concurrently. |
+| Data ownership | Which plugin owns each record; which services expose it to other plugins. |
+| Commands and queries | Inputs, outputs, validation failures, conflict behavior and required read/write permissions. |
+| Presentation | Required pages/tools/docs and the behavior when those optional providers are absent. |
+| Persistence and change | Constraints, indexes, transaction boundaries and whether existing data needs migration. |
+
+For example, inventory requires an explicit choice between an editable current
+balance and an append-only movement history. If corrections must be explainable,
+model receipts, issues and reversals, and derive stock from movements. Decide
+whether negative stock is allowed and check it in the same transaction as a new
+movement. A table with an unrestricted editable quantity does not establish that
+rule. Choose according to the actual workflow, not this example by default.
+
+Use stable IDs for references, not display names. Define timezone and date-only
+semantics. For money, choose a currency and exact representation such as integer
+minor units; an unrestricted binary float is not an accounting contract. Add
+uniqueness and database constraints for rules that persist independently of UI.
+
+## Concurrency and side effects
+
+Enforce invariants in the business service. The page can explain a validation
+failure but must not be its only enforcement point. For editable records, use a
+version or another explicit conflict strategy; a stale editor should not silently
+replace a newer write. Keep related same-owner changes in one managed transaction.
+
+Other plugins consume a declared, versioned service rather than opening this
+plugin's SQLite file. There is no cross-owner SQL transaction. If a workflow
+changes multiple owners, define its intermediate states and reconciliation.
+
+Storage mutation receipts can help resolve an uncertain database write. They do
+not make an entire business method or external HTTP side effect exactly-once.
+Define an application-level idempotency key when safe retries are a requirement;
+otherwise surface an unknown outcome for reconciliation instead of replaying it.
+
+## Scope and completion
+
+Ask only about choices that change behavior and cannot be inferred from the
+request or existing source. Record reversible defaults and continue independent
+work. Design-only completion is a reviewable model and contract, including any
+open business decisions; it does not require scaffolding or starting a server.
+
+During implementation, keep the stable plugin ID and previously applied migration
+SQL bytes. Append migrations for schema changes, including data backfills and
+their failure handling. Complete the design when every requested operation maps
+to an owning service, data changes, user feedback and a checkable outcome.

toolframe_core/bundled_skills/toolframe-plugin-design/references/operations.md

@@ -0,0 +1,133 @@
+# Build, install and validate
+
+Use the application's actual executable and home. The examples use `toolframe`
+on PATH; `--home APP` goes before the subcommand. Consult `--help` for the installed
+version rather than assuming commands from another Toolframe generation.
+
+## New source and application
+
+For a new plugin, generate the source with the installed CLI:
+
+```sh
+toolframe --home APP plugin new customer-notes --json
+# Alternative: the exact destination directory, relative to the current directory.
+toolframe --home APP plugin new customer-notes --output ./custom/customer-notes
+```
+
+Choose one of these destinations. The default is `APP/plugins/customer-notes/`.
+The CLI sets distribution `toolframe-customer-notes`, module
+`toolframe_customer_notes`, plugin ID `customer-notes` and service namespace
+`customer-notes.*`. JSON returns `plugin_id`, `package_name`, `python_module`,
+`path` and `status: "created"`. An existing file, directory or symlink is refused.
+IDs ending in `-` keep their plugin ID but add `plugin` to the distribution's end
+to form a valid package name; the module uses its underscores form. Read the
+returned names when editing references.
+An existing plugin is edited directly, never regenerated or overwritten.
+
+Generation uses the template bundled inside core, without needing this skill to
+be installed or a Toolframe source checkout. It does not build, install, register,
+enable or start a plugin, read application configuration, or request a management
+token. The launcher may prepare its own core runtime on first use as usual.
+Generated plugins are independent source trees; skill/binary updates leave them
+alone. `plugins/` is an authoring location, not an auto-discovery mechanism.
+
+Customize the generated files for the agreed design. The Notes example provides
+managed SQLite, capture/list services, a Streamlit page, a read-only MCP list tool
+and llms documentation. A headless service can omit the page, tools, docs, `ui`
+extra and storage when not needed. Keep its package and resource references
+consistent when intentionally changing identity.
+
+Build with `uv build --wheel` from the generated plugin directory. The starter contains no
+sibling path dependencies. Where Toolframe packages are not in the configured
+index, use an existing wheelhouse for dependency resolution. For a new local
+application:
+
+```sh
+toolframe --home APP init
+toolframe --home APP serve
+```
+
+Run `serve` in a separate terminal. Add required providers to the composition
+before enabling a plugin that consumes their services. For a local SQLite wheel:
+
+```sh
+toolframe --home APP plugin add /path/to/toolframe_storage_sqlite-0.3.1-py3-none-any.whl --enable
+toolframe --home APP plugin add APP/plugins/customer-notes
+toolframe --home APP plugin validate customer-notes
+toolframe --home APP plugin validate customer-notes --runtime
+toolframe --home APP plugin enable customer-notes
+toolframe --home APP plugin status customer-notes --check
+```
+
+Use your generated path and ID in place of `customer-notes`. `add` validates and leaves the plugin
+disabled unless `--enable` is explicit. Default validation covers package,
+dependencies, imports, configuration and resources. `--runtime` runs against a
+temporary data environment; it does not establish production health or prove a
+migration of existing data. Use sandbox configuration for plugins with external
+side effects. Active health is checked after enable/reload.
+
+`toolframe.toml` is the desired composition. CLI/API changes use the same core
+operations; core SQLite records their actual state. For offline or unpublished
+packages, use the launcher's `--wheelhouse PATH` and the composition's
+`[packages].find_links`. Warm-cache `--offline` does not download missing assets.
+
+## Local edits and reload
+
+In the commands below, replace `my-plugin` with the definition's ID.
+Editing source does not modify an active immutable snapshot, even if its package
+version is unchanged. Validate and reload explicitly:
+
+```sh
+toolframe --home APP plugin validate my-plugin
+toolframe --home APP plan --action reload --id my-plugin
+toolframe --home APP plugin reload my-plugin --plan-id REVIEWED_PLAN_ID
+toolframe --home APP plugin status my-plugin --check
+```
+
+The operation's `result.plan_id` identifies the reviewed plan. Recompute a stale
+plan instead of replaying it. `plugin update ID --source PATH` stages a different
+source; reload performs the switch. Operations normally wait; `--no-wait` returns
+an operation ID for `operation status ID`.
+
+Normal drain timeout aborts replacement and retains the old runtime. If activation
+fails and cleanup/schema conditions permit it, core tries the retained old
+snapshot once; `failed_recovered` still means this reload failed. Inspect candidate
+status, active status and `plugin logs ID`, not only the installed version. When
+the plan reports `restart_required`, follow that diagnosis instead of forcing a
+reload. Dashboard sessions may reconnect; MCP catalog/schema updates require
+client reconnection. Do not retry an uncertain business write automatically.
+
+## Existing-data schema changes
+
+Append a migration and stage the candidate. Then:
+
+```sh
+toolframe --home APP migrate plan my-plugin
+toolframe --home APP migrate apply my-plugin --plan-id REVIEWED_MIGRATION_PLAN_ID
+```
+
+Review the plan's affected cohort, schema change and backup/recovery implications.
+Apply only within the user's authorization to change that application's data;
+finish the migration code and reviewable plan before requesting any still-missing
+authorization. The explicit apply operation performs the schema change and runtime
+switch. An ordinary reload, including watch mode, cannot substitute for it. A
+committed schema upgrade is not automatically undone when new code fails; preserve
+the database and perform forward repair or an explicitly chosen restore.
+
+## Evidence for completion
+
+Verify business invariants through public services and requested interfaces.
+For a Dashboard plugin, also verify a read-only password cannot write, including a
+direct protected service call. Check anonymous, reader, writer and local operator
+access separately through Dashboard/service calls, explicit public HTTP methods,
+and an actual MCP client. In a disposable application, disable the Dashboard auth
+provider and verify closed policy denies protected calls, public HTTP remains
+intentional, and protected MCP keeps its independent gate. Restore auth, revoke a
+grant, and verify denial and recovery. Back up configuration/data before testing
+failure or reload in an existing application. Scope tests do not prove row isolation.
+Record preflight, scratch runtime and active health separately. For persistent
+plugins, create synthetic data in a disposable application, reload after a real
+local edit, and show that the behavior updates while old records remain. Check
+absence of optional providers where headless use is required. Test each requested
+page/tool/docs surface and disclose any unavailable checks; do not count a schema
+or package build as a successful user workflow.