copass-management 0.5.0__tar.gz

copass_management-0.5.0/.gitignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+coverage/
+
+# Lerna
+lerna-debug.log
+.nx/cache
+.nx/workspace-data
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.venv/
+venv/
+.olane

copass_management-0.5.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: copass-management
+Version: 0.5.0
+Summary: Spec-driven management tool registrar for Copass agents (read-only, Phase 1).
+Project-URL: Homepage, https://github.com/olane-labs/copass
+Project-URL: Repository, https://github.com/olane-labs/copass.git
+Author: Olane Inc.
+License: MIT
+Keywords: agents,copass,management,mcp,olane
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: copass-core>=0.3.0
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# copass-management
+
+Spec-driven management tool registrar for Copass agents (Python).
+
+This package consumes the `copass/spec/management/v1/` JSON
+Schema corpus and exposes a transport-agnostic registrar that wires
+each tool through `copass-core`. An optional MCP adapter lives at
+`copass_management.adapters.mcp` for Model Context Protocol consumers.
+
+Phase 1 ships the **read-only subset** (14 tools). Write tools follow
+in Phase 2.
+
+## Usage
+
+```python
+from copass_core import ApiKeyAuth, CopassClient
+from copass_management import (
+    RegistrarOptions,
+    register_management_tools,
+)
+
+client = CopassClient(auth=ApiKeyAuth(key="olk_..."))
+
+def register(registration):
+    print(registration.name, registration.description)
+
+register_management_tools(
+    register,
+    client,
+    RegistrarOptions(sandbox_id="sb_..."),
+)
+```
+
+For MCP transports, use `register_to_mcp_server` from
+`copass_management.adapters.mcp`. The MCP SDK is an optional
+dependency installed separately.
+
+## Spec source
+
+The package vendors a copy of the JSON Schema corpus under
+`copass_management/_spec/v1/`. In dev, set
+`COPASS_MANAGEMENT_SPEC_DIR` to point at the source tree.

copass_management-0.5.0/README.md

@@ -0,0 +1,42 @@
+# copass-management
+
+Spec-driven management tool registrar for Copass agents (Python).
+
+This package consumes the `copass/spec/management/v1/` JSON
+Schema corpus and exposes a transport-agnostic registrar that wires
+each tool through `copass-core`. An optional MCP adapter lives at
+`copass_management.adapters.mcp` for Model Context Protocol consumers.
+
+Phase 1 ships the **read-only subset** (14 tools). Write tools follow
+in Phase 2.
+
+## Usage
+
+```python
+from copass_core import ApiKeyAuth, CopassClient
+from copass_management import (
+    RegistrarOptions,
+    register_management_tools,
+)
+
+client = CopassClient(auth=ApiKeyAuth(key="olk_..."))
+
+def register(registration):
+    print(registration.name, registration.description)
+
+register_management_tools(
+    register,
+    client,
+    RegistrarOptions(sandbox_id="sb_..."),
+)
+```
+
+For MCP transports, use `register_to_mcp_server` from
+`copass_management.adapters.mcp`. The MCP SDK is an optional
+dependency installed separately.
+
+## Spec source
+
+The package vendors a copy of the JSON Schema corpus under
+`copass_management/_spec/v1/`. In dev, set
+`COPASS_MANAGEMENT_SPEC_DIR` to point at the source tree.

copass_management-0.5.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copass-management"
+version = "0.5.0"
+description = "Spec-driven management tool registrar for Copass agents (read-only, Phase 1)."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Olane Inc." }]
+requires-python = ">=3.10"
+keywords = ["copass", "management", "agents", "mcp", "olane"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "copass-core>=0.3.0",
+    "pydantic>=2.7",
+    "jsonschema>=4.21",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "mypy>=1.10",
+    "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/olane-labs/copass"
+Repository = "https://github.com/olane-labs/copass.git"
+
+[tool.copass]
+min_spec_version = "v1"
+max_spec_version = "v1"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/copass_management"]
+artifacts = ["src/copass_management/_spec/**/*.json"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["copass_management"]

copass_management-0.5.0/src/copass_management/__init__.py

@@ -0,0 +1,52 @@
+"""Spec-driven management tool registrar for Copass agents (Python).
+
+Phase 1 ships the read-only subset (14 tools). Write tools land in
+Phase 2.
+
+Public surface::
+
+    from copass_management import (
+        register_management_tools,
+        register_to_mcp_server,
+        load_management_specs,
+        MIN_SPEC_VERSION,
+        MAX_SPEC_VERSION,
+    )
+"""
+
+from copass_management.adapters.mcp import register_to_mcp_server
+from copass_management.registrar import (
+    Register,
+    RegistrarOptions,
+    ToolContext,
+    ToolHandler,
+    ToolRegistration,
+    register_management_tools,
+)
+from copass_management.specs import (
+    LoadedManagementCorpus,
+    ManagementFixture,
+    ManagementSpec,
+    MAX_SPEC_VERSION,
+    MIN_SPEC_VERSION,
+    load_management_specs,
+)
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "__version__",
+    "Register",
+    "RegistrarOptions",
+    "ToolContext",
+    "ToolHandler",
+    "ToolRegistration",
+    "register_management_tools",
+    "register_to_mcp_server",
+    "load_management_specs",
+    "LoadedManagementCorpus",
+    "ManagementFixture",
+    "ManagementSpec",
+    "MIN_SPEC_VERSION",
+    "MAX_SPEC_VERSION",
+]

copass_management-0.5.0/src/copass_management/_spec/v1/examples/get_agent.example.json

@@ -0,0 +1,32 @@
+{
+  "input": {
+    "slug": "gtm-marketing"
+  },
+  "output": {
+    "agent": {
+      "agent_id": "ag_01HXYZAB1234567890123ABCDE",
+      "slug": "gtm-marketing",
+      "name": "GTM Marketing Triage",
+      "description": "Reads incoming marketing-channel events and drafts responses.",
+      "system_prompt": "You triage marketing-channel events. When a mention arrives, summarise the request and react with a thumbs-up.",
+      "tool_allowlist": [
+        "discover",
+        "interpret",
+        "search",
+        "pd_slack_v2_slack_v2-add-reaction"
+      ],
+      "model_settings": {
+        "backend": "anthropic",
+        "model": "claude-sonnet-4-6",
+        "temperature": 0.3,
+        "max_tokens": 4096,
+        "max_turns": 8,
+        "timeout_s": 60
+      },
+      "status": "active",
+      "version": 7,
+      "created_at": "2026-03-12T11:14:00.000000+00:00",
+      "updated_at": "2026-04-22T08:01:55.000000+00:00"
+    }
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/get_run_trace.example.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "run_id": "rn_01HXYZAB1234567890123RUN01"
+  },
+  "output": {
+    "run_id": "rn_01HXYZAB1234567890123RUN01",
+    "agent_id": "ag_01HXYZAB1234567890123ABCDE",
+    "status": "succeeded",
+    "started_at": "2026-04-29T18:02:55.000000+00:00",
+    "finished_at": "2026-04-29T18:03:00.000000+00:00",
+    "error_message": null,
+    "tool_resolution_trace": {
+      "sources_resolved": ["copass_management", "copass_retrieval"],
+      "sources_skipped": [],
+      "tool_names_advertised": [
+        "discover",
+        "interpret",
+        "search",
+        "pd_slack_v2_slack_v2-add-reaction"
+      ],
+      "allowlist_filtered_out": [],
+      "allowlist_missing_entries": [],
+      "duration_ms": 132
+    }
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/get_source.example.json

@@ -0,0 +1,31 @@
+{
+  "input": {
+    "data_source_id": "ds_01HXYZAB1234567890123ABCDE"
+  },
+  "output": {
+    "source": {
+      "data_source_id": "ds_01HXYZAB1234567890123ABCDE",
+      "name": "Acme HQ Slack",
+      "provider": "slack_v2",
+      "ingestion_mode": "realtime",
+      "status": "active",
+      "kind": "trigger",
+      "external_account_id": "apn_demo_acct_001",
+      "webhook_url": "https://api.example.copass.id/api/v1/webhooks/integrations/inbound/abc123",
+      "last_sync_at": "2026-04-29T22:14:01.000000+00:00",
+      "created_at": "2026-02-11T17:02:33.000000+00:00",
+      "adapter_config": {
+        "app_slug": "slack_v2",
+        "account_id": "apn_demo_acct_001",
+        "external_user_id": "u_user-uuid-placeholder",
+        "trigger_component": {
+          "component_id": "slack_v2-new-mention",
+          "configured_props": {
+            "slack": { "authProvisionId": "apn_demo_acct_001" },
+            "keyword": "copass"
+          }
+        }
+      }
+    }
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_agent_tools.example.json

@@ -0,0 +1,32 @@
+{
+  "input": {
+    "app_slug": "slack_v2"
+  },
+  "output": {
+    "tools": [
+      {
+        "name": "pd_slack_v2_slack_v2-add-reaction",
+        "app_slug": "slack_v2",
+        "description": "Add an emoji reaction to a message."
+      },
+      {
+        "name": "pd_slack_v2_slack_v2-post-message",
+        "app_slug": "slack_v2",
+        "description": "Post a message into a channel or thread."
+      }
+    ],
+    "by_app": {
+      "slack_v2": [
+        {
+          "name": "pd_slack_v2_slack_v2-add-reaction",
+          "description": "Add an emoji reaction to a message."
+        },
+        {
+          "name": "pd_slack_v2_slack_v2-post-message",
+          "description": "Post a message into a channel or thread."
+        }
+      ]
+    },
+    "count": 2
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_agents.example.json

@@ -0,0 +1,30 @@
+{
+  "input": {
+    "status": "active"
+  },
+  "output": {
+    "agents": [
+      {
+        "agent_id": "ag_01HXYZAB1234567890123ABCDE",
+        "slug": "gtm-marketing",
+        "name": "GTM Marketing Triage",
+        "description": "Reads incoming marketing-channel events and drafts responses.",
+        "status": "active",
+        "version": 7,
+        "created_at": "2026-03-12T11:14:00.000000+00:00",
+        "updated_at": "2026-04-22T08:01:55.000000+00:00"
+      },
+      {
+        "agent_id": "ag_01HXYZAB1234567890123ABCDF",
+        "slug": "support-firefighter",
+        "name": "Support Firefighter",
+        "description": "Reacts to high-severity support pings.",
+        "status": "active",
+        "version": 3,
+        "created_at": "2026-04-01T09:00:00.000000+00:00",
+        "updated_at": "2026-04-01T09:00:00.000000+00:00"
+      }
+    ],
+    "count": 2
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_api_keys.example.json

@@ -0,0 +1,31 @@
+{
+  "input": {
+    "kinds": ["general", "agent_invoke"],
+    "include_revoked": false
+  },
+  "output": {
+    "keys": [
+      {
+        "api_key_id": "ak_01HXYZAB1234567890123KEY01",
+        "kind": "general",
+        "label": "Workstation",
+        "key_prefix": "olk_demo",
+        "agent_id": null,
+        "created_at": "2026-02-08T10:15:30.000000+00:00",
+        "expires_at": null,
+        "revoked_at": null
+      },
+      {
+        "api_key_id": "ak_01HXYZAB1234567890123KEY02",
+        "kind": "agent_invoke",
+        "label": "gtm-marketing invoke",
+        "key_prefix": "olk_demo",
+        "agent_id": "ag_01HXYZAB1234567890123ABCDE",
+        "created_at": "2026-04-01T09:01:00.000000+00:00",
+        "expires_at": "2026-10-01T09:01:00.000000+00:00",
+        "revoked_at": null
+      }
+    ],
+    "count": 2
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_apps.example.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "q": "slack",
+    "limit": 10
+  },
+  "output": {
+    "apps": [
+      {
+        "app_slug": "slack_v2",
+        "name": "Slack",
+        "description": "Send messages, react, and read channels.",
+        "categories": ["chat", "team-collaboration"],
+        "provider": "trigger_provider"
+      },
+      {
+        "app_slug": "slack-admin",
+        "name": "Slack Admin",
+        "description": "Workspace admin actions.",
+        "categories": ["chat", "admin"],
+        "provider": "trigger_provider"
+      }
+    ],
+    "next_cursor": null
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_connected_accounts.example.json

@@ -0,0 +1,17 @@
+{
+  "input": {
+    "app_slug": "slack_v2"
+  },
+  "output": {
+    "accounts": [
+      {
+        "id": "apn_demo_acct_001",
+        "app_slug": "slack_v2",
+        "name": "Acme HQ",
+        "created_at": "2026-02-11T17:02:30.000000+00:00",
+        "provider": "trigger_provider"
+      }
+    ],
+    "count": 1
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_runs.example.json

@@ -0,0 +1,34 @@
+{
+  "input": {
+    "agent_slug": "gtm-marketing",
+    "limit": 5
+  },
+  "output": {
+    "agent_slug": "gtm-marketing",
+    "runs": [
+      {
+        "run_id": "rn_01HXYZAB1234567890123RUN01",
+        "status": "succeeded",
+        "trigger_id": "tg_01HXYZAB1234567890123TRIG1",
+        "tokens_in": 2418,
+        "tokens_out": 412,
+        "duration_ms": 4812,
+        "error_message": null,
+        "started_at": "2026-04-29T18:02:55.000000+00:00",
+        "finished_at": "2026-04-29T18:03:00.000000+00:00"
+      },
+      {
+        "run_id": "rn_01HXYZAB1234567890123RUN02",
+        "status": "failed",
+        "trigger_id": "tg_01HXYZAB1234567890123TRIG1",
+        "tokens_in": 1112,
+        "tokens_out": 0,
+        "duration_ms": 921,
+        "error_message": "tool 'pd_slack_v2_slack_v2-add-reaction' returned 429",
+        "started_at": "2026-04-29T17:54:01.000000+00:00",
+        "finished_at": "2026-04-29T17:54:02.000000+00:00"
+      }
+    ],
+    "count": 2
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_sandbox_connections.example.json

@@ -0,0 +1,34 @@
+{
+  "input": {
+    "include_revoked": false
+  },
+  "output": {
+    "connections": [
+      {
+        "connection_id": "cn_01HXYZAB1234567890123CONN1",
+        "user_id": "00000000-0000-4000-a000-000000000001",
+        "copass_id": "alice",
+        "role": "editor",
+        "project_id": null,
+        "label": "@alice",
+        "status": "active",
+        "expires_at": null,
+        "revoked_at": null,
+        "created_at": "2026-04-01T11:30:00.000000+00:00"
+      },
+      {
+        "connection_id": "cn_01HXYZAB1234567890123CONN2",
+        "user_id": "00000000-0000-4000-a000-000000000002",
+        "copass_id": "bob",
+        "role": "viewer",
+        "project_id": "pj_01HXYZAB1234567890123PRJ01",
+        "label": "@bob — sales project",
+        "status": "active",
+        "expires_at": "2026-12-31T23:59:59.000000+00:00",
+        "revoked_at": null,
+        "created_at": "2026-04-15T08:00:00.000000+00:00"
+      }
+    ],
+    "count": 2
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_sandboxes.example.json

@@ -0,0 +1,22 @@
+{
+  "input": {},
+  "output": {
+    "sandboxes": [
+      {
+        "sandbox_id": "sb_01HXYZAB12345678901234567A",
+        "name": "Personal",
+        "tier": "free",
+        "status": "active",
+        "created_at": "2025-12-04T18:23:11.000000+00:00"
+      },
+      {
+        "sandbox_id": "sb_01HXYZAB12345678901234567B",
+        "name": "Work",
+        "tier": "pro",
+        "status": "active",
+        "created_at": "2026-01-22T09:15:00.000000+00:00"
+      }
+    ],
+    "count": 2
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_sources.example.json

@@ -0,0 +1,22 @@
+{
+  "input": {
+    "provider": "slack_v2"
+  },
+  "output": {
+    "sources": [
+      {
+        "data_source_id": "ds_01HXYZAB1234567890123ABCDE",
+        "name": "Acme HQ Slack",
+        "provider": "slack_v2",
+        "ingestion_mode": "realtime",
+        "status": "active",
+        "kind": "trigger",
+        "external_account_id": "apn_demo_acct_001",
+        "webhook_url": "https://api.example.copass.id/api/v1/webhooks/integrations/inbound/abc123",
+        "last_sync_at": "2026-04-29T22:14:01.000000+00:00",
+        "created_at": "2026-02-11T17:02:33.000000+00:00"
+      }
+    ],
+    "count": 1
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_trigger_components.example.json

@@ -0,0 +1,33 @@
+{
+  "input": {
+    "app": "slack_v2",
+    "q": "mention",
+    "limit": 25
+  },
+  "output": {
+    "components": [
+      {
+        "component_id": "slack_v2-new-mention",
+        "name": "New Mention (Instant)",
+        "description": "Emit when the connected user is mentioned in any subscribed channel.",
+        "version": "0.0.7",
+        "configurable_props": [
+          {
+            "name": "slack",
+            "type": "app",
+            "label": "Slack account",
+            "required": true
+          },
+          {
+            "name": "keyword",
+            "type": "string",
+            "label": "Mention keyword",
+            "required": true,
+            "description": "Literal substring matched against the message text. e.g. 'copass'."
+          }
+        ]
+      }
+    ],
+    "count": 1
+  }
+}

copass_management-0.5.0/src/copass_management/_spec/v1/examples/list_triggers.example.json

@@ -0,0 +1,24 @@
+{
+  "input": {
+    "agent_slug": "gtm-marketing"
+  },
+  "output": {
+    "agent_slug": "gtm-marketing",
+    "triggers": [
+      {
+        "trigger_id": "tg_01HXYZAB1234567890123TRIG1",
+        "data_source_id": "ds_01HXYZAB1234567890123ABCDE",
+        "event_type_filter": "slack.message.new",
+        "filter_config": {
+          "item.channel": "C0123456789"
+        },
+        "status": "active",
+        "rate_limit_per_hour": 60,
+        "fire_count": 142,
+        "last_fired_at": "2026-04-29T18:02:55.000000+00:00",
+        "created_at": "2026-03-12T11:14:30.000000+00:00"
+      }
+    ],
+    "count": 1
+  }
+}