primethink-cli 1.4.1__tar.gz → 1.5.0__tar.gz

{primethink_cli-1.4.1 → primethink_cli-1.5.0}/DEVELOPER.md

@@ -55,8 +55,8 @@ pip install -e ".[dev]"
 primethink-cli/
 ├── primethink.py           # Main CLI implementation (single module)
 ├── primethink_mcp.py       # MCP server (pt mcp), reuses primethink.py's helpers; optional [mcp] extra
-├── internal_tools/         # primethink-agent-tools: LangChain tools plugin for PT agents
-│                           #   (own distribution; depends on primethink-cli; reuses its helpers)
+├── primethink_agent_tools/ # Agent tools plugin: LangChain tools for PT agents; optional [agent-tools] extra
+│                           #   (entry point primethink.tools; reuses primethink.py's helpers)
 ├── pyproject.toml          # Package configuration (entry point: pt)
 ├── setup.py                # Legacy packaging shim
 ├── requirements.txt        # Runtime dependencies
@@ -85,7 +85,10 @@ primethink-cli/
     ├── test_task_commands.py # Task command tests
     ├── test_live_app.py    # Safe GitHub template scaffolding tests
     ├── test_install_developer_skill.py # Recursive public skill installer tests
-    └── test_install_skill.py # bundled CLI skill installer tests
+    ├── test_install_skill.py # bundled CLI skill installer tests
+    ├── test_mcp_server.py  # MCP server tests (skipped without the mcp SDK)
+    ├── test_agent_tools.py # Agent tools plugin tests (skipped without langchain-core)
+    └── test_packaging.py   # Wheel/entry-point/extras contract (runs on a base install)
 ```
 
 ## Architecture
@@ -142,7 +145,7 @@ def my_command(thing_id, profile, api_url):
 
 Security boundaries are enforced before the destination is exposed: HTTPS GitHub repository URLs only, compressed/expanded size and file-count limits, repository-relative manifest paths, path-traversal and duplicate-path checks, symbolic-link rejection, and refusal to touch an existing destination. Tests build in-memory ZIP archives and mock `requests.request`; do not make live GitHub calls in the test suite. The default catalog lives in the separate `primethink-app-templates` repository.
 
-Because this command only creates local source files and does not call the PrimeThink API, it has no MCP or `primethink-agent-tools` equivalent.
+Because this command only creates local source files and does not call the PrimeThink API, it has no MCP or agent-tools equivalent.
 
 #### 4. Agent Skill Installation
 
@@ -185,16 +188,18 @@ Key differences from the CLI, driven by MCP-over-stdio constraints:
 
 `mcp` is an optional dependency (the `[mcp]` extra, Python 3.10+); `pt mcp` imports `primethink_mcp` lazily and prints an install hint if the SDK is missing. Tests live in `tests/test_mcp_server.py` and `pytest.importorskip("mcp")` so they skip cleanly where the SDK isn't installed.
 
-#### 7. Agent Tools Plugin (`internal_tools/`)
+#### 7. Agent Tools Plugin (`primethink_agent_tools/`)
 
-`internal_tools/` is a **separate distribution** (`primethink-agent-tools`) that depends on `primethink-cli` and exposes the admin/management API as LangChain tools for PrimeThink agents, discovered via the `primethink.tools` entry point. It reuses the CLI's code rather than re-implementing it:
+`primethink_agent_tools/` ships **inside the `primethink-cli` wheel**, enabled by the optional `[agent-tools]` extra (`langchain-core`, `pydantic`; Python 3.9+). It exposes the admin/management API as LangChain tools for PrimeThink agents, discovered via the `primethink.tools` entry point that `pyproject.toml` declares (`primethink_admin = "primethink_agent_tools:register"`). It reuses the CLI's code rather than re-implementing it:
 
 - **Transport reuse without a rewrite.** Tools call `primethink._api_call` (the CLI's `requests` layer) through a small async wrapper (`client.api_json`) that runs it in `asyncio.to_thread` — the agent runtime is async, and `requests` is sync. No httpx dependency; `requests` comes transitively from `primethink-cli`.
 - **Payload reuse.** Tools import `_clean_payload`, `_TASK_PORTABLE_FIELDS`, `_VERSION_FIELDS`, etc. from `primethink`, so payload shaping matches `pt`/`pt mcp`. Only endpoint path strings are written locally (the accepted trade for not restructuring the CLI).
 - **Auth.** Per-user token from the `ADMIN_PRIMETHINK_API_TOKEN` setting, resolved via the injected `get_user_setting_value` context (`settings.PrimethinkSettingsProvider`), with a `StaticSettingsProvider` fallback for tests/standalone.
 - **Scope.** Admin/management only (tasks, agents, chats, collections + collection↔chat assignment). Excludes hot-path search, document byte transfer, messaging/orchestration, and destructive deletes — those stay native.
 
-This directory is **not** part of the `primethink-cli` wheel (the main `pyproject.toml` ships only `primethink`/`primethink_mcp`); it builds and tests independently (`pip install -e ./internal_tools[dev]`, `cd internal_tools && pytest`). When you add or change an API command that belongs in the agent surface, add/update the matching tool in `internal_tools/src/primethink_agent_tools/tools.py` and its test.
+Because the plugin and the private CLI helpers it imports (`_api_call`, `_clean_payload`, `_TASK_PORTABLE_FIELDS`, `_VERSION_FIELDS`) always ship in the same wheel, there is no cross-package version skew to guard against. The base CLI install is unaffected: the entry point is declared, but nothing loads it unless the PrimeThink API calls it, and `register()` imports langchain lazily — and when it is called without the extra, it raises a `ModuleNotFoundError` whose message names `pip install 'primethink-cli[agent-tools]'` (the API logs it and continues without the plugin). The API image installs `primethink-cli[agent-tools]==<version>`; see [`docs/agent-tools.md`](docs/agent-tools.md) for setup.
+
+Tests live in `tests/test_agent_tools.py` and `pytest.importorskip("langchain_core")`, so they skip where the extra isn't installed (the `dev` extra installs it); the packaging contract (entry point, `pyproject.toml` packages/extras, RECORD contents of a non-editable install, the `register()` install hint) lives in `tests/test_packaging.py` and needs no extra. When you add or change an API command that belongs in the agent surface, add/update the matching tool in `primethink_agent_tools/tools.py` and its test.
 
 ## Adding New Commands
 

{primethink_cli-1.4.1 → primethink_cli-1.5.0}/MANIFEST.in

@@ -7,6 +7,11 @@ recursive-include docs *.md *.txt
 recursive-include install *.sh *.ps1 *.cmd *.rb
 recursive-include scripts *.sh
 recursive-include skills *.md
+# setuptools auto-includes tests/test_*.py; add the package marker and shared
+# fixtures the test modules import (`from tests.conftest import ...`), plus the
+# pytest config, so a bare `pytest` inside an unpacked sdist collects `tests/`.
+recursive-include tests *.py
+include pytest.ini
 # Internal design/spec artifacts live under docs/ but must not ship in the sdist.
 prune docs/superpowers
 global-exclude __pycache__

{primethink_cli-1.4.1/primethink_cli.egg-info → primethink_cli-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: primethink-cli
-Version: 1.4.1
+Version: 1.5.0
 Summary: PrimeThink CLI - A powerful tool for interacting with PrimeThink AI API
 Author-email: PrimeThink <support@primethink.ai>
 License-Expression: MIT
@@ -26,10 +26,15 @@ Requires-Dist: click>=8.0.0
 Requires-Dist: requests>=2.25.0
 Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.2.0; extra == "mcp"
+Provides-Extra: agent-tools
+Requires-Dist: langchain-core>=0.3.0; extra == "agent-tools"
+Requires-Dist: pydantic>=2.0; extra == "agent-tools"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: mcp<2,>=1.2.0; python_version >= "3.10" and extra == "dev"
+Requires-Dist: langchain-core>=0.3.0; python_version >= "3.10" and extra == "dev"
+Requires-Dist: pydantic>=2.0; python_version >= "3.10" and extra == "dev"
 Dynamic: license-file
 
 # PrimeThink CLI
@@ -79,7 +84,7 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt profile remove` | Remove a profile |
 | `pt chat send` | Send a message to a chat (by ID/mention) or an agent |
 | `pt chat list` | List chats (paginated, filterable by star/archive/workspace) |
-| `pt chat create` | Create a new chat |
+| `pt chat create` | Create a new chat (`--from-task-id` launches a task into it) |
 | `pt chat rename` | Rename a chat |
 | `pt chat goal` | Update a chat's goal |
 | `pt chat type` | Switch a chat between `live-app` and `chat` mode |
@@ -158,7 +163,8 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt task delete` | Delete a task (asks for confirmation; `--yes` to skip) |
 | `pt task duplicate` | Duplicate a task |
 | `pt task set-public` / `pt task set-private` | Make a task public / private |
-| `pt task publish` | Create/update a task from a project directory |
+| `pt task publish` | Create/update a task from a project directory (`--type`, feature toggles, optional `task.json`) |
+| `pt task launch` | Launch a task into a new chat, optionally inside a workspace |
 | `pt task test` | Sync a task goal into a new or existing chat |
 | `pt task export` | Export a task's portable config as JSON (for `pt task import`) |
 | `pt task import` | Create a new task from an exported JSON file (deploy across environments with `--profile`) |
@@ -349,8 +355,12 @@ pt task import tasks/briefing.json --profile production
 
 # Publish a conventional task project (GOAL.md required); pass an ID to update
 pt task publish ./tasks/briefing --virtual-assistant-id 7
+pt task publish ./tasks/briefing --virtual-assistant-id 7 --type group --chat-history --docs-enabled --scheduled-jobs
 pt task publish ./tasks/briefing --task-id 99 --virtual-assistant-id 7
 
+# Launch a task into a chat (optionally inside a workspace), as the web app does
+pt task launch 99 --workspace-id 738
+
 # Make the resulting task public/private, or test its goal in a chat
 pt task set-public 99
 pt task set-private 99
@@ -439,21 +449,20 @@ for the full tool list.
 
 ## Agent Tools Plugin
 
-Beyond the CLI and MCP server, this repo also ships **[`primethink-agent-tools`](internal_tools/)**
-(under `internal_tools/`) — a plugin that exposes the PrimeThink admin/management
-API (tasks, agents, chats, collections) as **LangChain tools for PrimeThink
-agents**, reusing the same client code as `pt`. It's a separate distribution that
-depends on `primethink-cli`, so the CLI stays lean, and the plugin is installed
-only in the agent runtime:
+Beyond the CLI and MCP server, the package also ships the **agent tools plugin**
+(`primethink_agent_tools`) — it exposes the PrimeThink admin/management API
+(tasks, agents, chats, collections) as **LangChain tools for PrimeThink
+agents**, reusing the same client code as `pt`. It's enabled by the optional
+`agent-tools` extra, so plain CLI installs stay lean (no langchain) and the
+plugin is installed only in the agent runtime / API image:
 
 ```bash
-pip install primethink-cli primethink-agent-tools
+pip install 'primethink-cli[agent-tools]'
 ```
 
 The PrimeThink API discovers it automatically via the `primethink.tools` entry
 point. Authentication uses a per-user `ADMIN_PRIMETHINK_API_TOKEN` setting. See
-[`internal_tools/README.md`](internal_tools/README.md) for the tool list, auth,
-and setup.
+[`docs/agent-tools.md`](docs/agent-tools.md) for the tool list, auth, and setup.
 
 ## Agent Skills
 

{primethink_cli-1.4.1 → primethink_cli-1.5.0}/README.md

@@ -45,7 +45,7 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt profile remove` | Remove a profile |
 | `pt chat send` | Send a message to a chat (by ID/mention) or an agent |
 | `pt chat list` | List chats (paginated, filterable by star/archive/workspace) |
-| `pt chat create` | Create a new chat |
+| `pt chat create` | Create a new chat (`--from-task-id` launches a task into it) |
 | `pt chat rename` | Rename a chat |
 | `pt chat goal` | Update a chat's goal |
 | `pt chat type` | Switch a chat between `live-app` and `chat` mode |
@@ -124,7 +124,8 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt task delete` | Delete a task (asks for confirmation; `--yes` to skip) |
 | `pt task duplicate` | Duplicate a task |
 | `pt task set-public` / `pt task set-private` | Make a task public / private |
-| `pt task publish` | Create/update a task from a project directory |
+| `pt task publish` | Create/update a task from a project directory (`--type`, feature toggles, optional `task.json`) |
+| `pt task launch` | Launch a task into a new chat, optionally inside a workspace |
 | `pt task test` | Sync a task goal into a new or existing chat |
 | `pt task export` | Export a task's portable config as JSON (for `pt task import`) |
 | `pt task import` | Create a new task from an exported JSON file (deploy across environments with `--profile`) |
@@ -315,8 +316,12 @@ pt task import tasks/briefing.json --profile production
 
 # Publish a conventional task project (GOAL.md required); pass an ID to update
 pt task publish ./tasks/briefing --virtual-assistant-id 7
+pt task publish ./tasks/briefing --virtual-assistant-id 7 --type group --chat-history --docs-enabled --scheduled-jobs
 pt task publish ./tasks/briefing --task-id 99 --virtual-assistant-id 7
 
+# Launch a task into a chat (optionally inside a workspace), as the web app does
+pt task launch 99 --workspace-id 738
+
 # Make the resulting task public/private, or test its goal in a chat
 pt task set-public 99
 pt task set-private 99
@@ -405,21 +410,20 @@ for the full tool list.
 
 ## Agent Tools Plugin
 
-Beyond the CLI and MCP server, this repo also ships **[`primethink-agent-tools`](internal_tools/)**
-(under `internal_tools/`) — a plugin that exposes the PrimeThink admin/management
-API (tasks, agents, chats, collections) as **LangChain tools for PrimeThink
-agents**, reusing the same client code as `pt`. It's a separate distribution that
-depends on `primethink-cli`, so the CLI stays lean, and the plugin is installed
-only in the agent runtime:
+Beyond the CLI and MCP server, the package also ships the **agent tools plugin**
+(`primethink_agent_tools`) — it exposes the PrimeThink admin/management API
+(tasks, agents, chats, collections) as **LangChain tools for PrimeThink
+agents**, reusing the same client code as `pt`. It's enabled by the optional
+`agent-tools` extra, so plain CLI installs stay lean (no langchain) and the
+plugin is installed only in the agent runtime / API image:
 
 ```bash
-pip install primethink-cli primethink-agent-tools
+pip install 'primethink-cli[agent-tools]'
 ```
 
 The PrimeThink API discovers it automatically via the `primethink.tools` entry
 point. Authentication uses a per-user `ADMIN_PRIMETHINK_API_TOKEN` setting. See
-[`internal_tools/README.md`](internal_tools/README.md) for the tool list, auth,
-and setup.
+[`docs/agent-tools.md`](docs/agent-tools.md) for the tool list, auth, and setup.
 
 ## Agent Skills
 

{primethink_cli-1.4.1 → primethink_cli-1.5.0}/SPECS.md

@@ -38,7 +38,7 @@ To obtain an API key, go to `Settings > API Keys` in the PrimeThink app and gene
 | `pt chat send CHAT_ID` | `POST /api/v1/chats/{chat_id_or_mention}/messages` |
 | `pt chat send --agent ID` | `POST /api/v1/virtual-assistants/{agent_id}/messages` |
 | `pt chat list` | `GET /api/v1/chats` |
-| `pt chat create` | `POST /api/v1/chats` |
+| `pt chat create` | `POST /api/v1/chats` (`--from-task-id` adds `?copy_from_task_id=`) |
 | `pt chat rename` | `PUT /api/v1/chats/{chat_id}/name` |
 | `pt chat goal` | `PUT /api/v1/chats/{chat_id}/goal` |
 | `pt chat type` | `PUT /api/v1/chats/{chat_id}/page_type?page_type=html\|chat` |
@@ -114,7 +114,8 @@ To obtain an API key, go to `Settings > API Keys` in the PrimeThink app and gene
 | `pt task delete` | `DELETE /api/v1/tasks/{task_id}` |
 | `pt task duplicate` | `POST /api/v1/tasks/{task_id}/duplicate` |
 | `pt task set-public` / `set-private` | `PATCH /api/v1/tasks/{task_id}/public-status?task_type=public\|private` |
-| `pt task publish` | `POST /api/v1/tasks/` or `PATCH /api/v1/tasks/{task_id}` |
+| `pt task publish` | `POST /api/v1/tasks/` or `PATCH /api/v1/tasks/{task_id}` (type/toggles from options or the project's `task.json`) |
+| `pt task launch` | `POST /api/v1/chats?copy_from_task_id={task_id}[&task_version_number=N]` (body: optional `chat_workspace_id`, `name`) |
 | `pt task test` | `POST /api/v1/chats` (new only), `PUT /api/v1/chats/{chat_id}/page_type` (existing only), `PUT /api/v1/chats/{chat_id}/goal` |
 | `pt live-app publish` | task create/update + task version + task directory/document/version endpoints |
 | `pt live-app test` | chat create/page-type/goal + chat directory/document/version endpoints |
@@ -309,11 +310,13 @@ pt chat list [--page N] [--page-size N] [--search TEXT] [--starred/--no-starred]
 
 **Body**: JSON object; all fields optional and omitted unless set — `name`, `goal`, `virtual_assistant_id` (int), `chat_workspace_id`, `parent_chat_id` (int), `type` (`standard` | `direct_users`; server default `standard`), `public` (bool), `members` (int array).
 
+**Query parameters** (task launch): `copy_from_task_id` (int) makes the server copy that task's goal, default agent, settings, documents, collections and scheduled job into the new chat and post its initial prompt — the route the web app uses to open a task; `task_version_number` (int, optional) launches a specific version. A `task_id` in the body is ignored by the server. Exposed as `pt task launch` / `pt chat create --from-task-id` and the `launch_task` MCP tool.
+
 **Success statuses**: 200, 201
 
 **CLI Command**:
 ```bash
-pt chat create [--name TEXT] [--goal TEXT | --goal-file PATH] [--virtual-assistant-id ID] [--workspace-id ID] [--parent-chat-id ID] [--type TYPE] [--public/--no-public] [--member USER_ID]...
+pt chat create [--name TEXT] [--goal TEXT | --goal-file PATH] [--virtual-assistant-id ID] [--workspace-id ID] [--parent-chat-id ID] [--type TYPE] [--public/--no-public] [--member USER_ID]... [--from-task-id TASK_ID]
 ```
 
 ---

{primethink_cli-1.4.1 → primethink_cli-1.5.0}/USER_GUIDE.md

@@ -77,7 +77,7 @@ pt version
 
 You should see output like:
 ```
-PrimeThink CLI v1.3.3
+PrimeThink CLI v1.5.0
 ```
 
 ## Getting Started
@@ -977,8 +977,12 @@ pt task duplicate 99
 
 # Publish a conventional task project; GOAL.md is required
 pt task publish ./tasks/briefing --virtual-assistant-id 7
+pt task publish ./tasks/briefing --virtual-assistant-id 7 --type group --chat-history --docs-enabled --scheduled-jobs
 pt task publish ./tasks/briefing --task-id 99 --virtual-assistant-id 7
 
+# Launch a task into a new chat, optionally inside a workspace (prints the chat JSON + URL)
+pt task launch 99 --workspace-id 738
+
 # Sync the project goal into a new temporary chat or an existing chat
 pt task test ./tasks/briefing
 pt task test ./tasks/briefing --chat-id CHAT_UUID
@@ -994,7 +998,9 @@ pt task delete 99 --yes
 
 A project directory can override its folder name with `.name.config`, its description with `.description.config`, and its initial prompt with `INITIAL_PROMPT.md`. For type changes other than public/private (e.g. `group` or `catalog`), use `pt task update 99 --type group`.
 
-`pt task publish` prints progress lines rather than JSON, ending with `Task ID: 81`. It takes no task-field options — a created task is private and published with the optional features (memory, chat history, search, summary, documents and collections, scheduled jobs, email integration) switched off. Turn them on afterwards with `pt task update`; a later `pt task publish --task-id` only re-syncs name, description, goal, initial prompt, virtual assistant, and page type, so those settings are not overwritten.
+`pt task publish` prints progress lines rather than JSON, ending with `Task ID: 81`. Task type and feature toggles come from its options (`--type`, `--chat-history`, `--docs-enabled`, `--scheduled-jobs`, `--global-memory`, `--search-in-chat`, `--search-in-documents`, `--summary-enabled`, `--email-integration`, `--share-action`, `--public-chat`, `--run-immediately`), else from an optional `task.json` in the project directory (`{"type": "group", "chat_history": true, "documents_and_collections_enabled": true, "scheduled_jobs_enabled": true}`), else from the conservative defaults: a created task is **private** with memory, chat history, search, summary, documents and collections, scheduled jobs and email integration **switched off** — so a task that relies on its documents or on scheduling must enable them. A later `pt task publish --task-id` re-syncs name, description, goal, initial prompt, virtual assistant and page type plus every type/toggle given on the command line and every accepted field present in `task.json`; settings the project does not state are not overwritten.
+
+`pt task launch TASK_ID` starts a task the way the web app does when you open one: it creates a chat (inside `--workspace-id` when given) that inherits the task's goal, default agent, settings, documents, collections and scheduled job, posts the task's initial prompt, and prints the chat JSON followed by `Chat URL: …`. `pt chat create --from-task-id TASK_ID` does the same through the generic chat-create command.
 
 `pt task test` creates a **new** chat unless you pass `--chat-id`, and prints the chat URL as its last line. A test chat is temporary by default; pass `--permanent` when you mean to keep it. To keep re-testing in the same chat, record the ID on the first run:
 
@@ -1827,6 +1833,10 @@ pt mcp
 
 Point your MCP client at `pt mcp` and provide a `PRIMETHINK_TOKEN` in its server env. See the [MCP Server](#mcp-server) section for a full client-config example.
 
+### Q: What is the `agent-tools` extra?
+
+**A**: It enables the plugin that lets PrimeThink **agents** (not you) manage tasks, agents, chats, and collections through the same client code as `pt`. It's installed in the PrimeThink API image by platform operators, not on your machine — a plain `pip install primethink-cli` doesn't need it. See [docs/agent-tools.md](docs/agent-tools.md).
+
 ### Q: How do I uninstall the CLI?
 
 **A**:

primethink_cli-1.5.0/docs/agent-tools.md

@@ -0,0 +1,116 @@
+# Agent tools plugin (`primethink-cli[agent-tools]`)
+
+PrimeThink API tools for PrimeThink **agents**, packaged as a discoverable
+plugin. It exposes the admin/management surface of the PrimeThink API — tasks,
+agents, chats, and collections (including collection↔chat assignment) — as
+LangChain tools, **reusing the `primethink-cli` client code** so the tool
+encoding never drifts from `pt` / `pt mcp`.
+
+The plugin is the `primethink_agent_tools` package **inside the `primethink-cli`
+distribution**, enabled by the optional **`agent-tools` extra**. A plain
+`pip install primethink-cli` stays lean (no langchain); the extra pulls in
+`langchain-core` and `pydantic` and is installed only where the tools run — the
+agent runtime / API image. One wheel, one version: the plugin and the CLI
+helpers it imports always ship together.
+
+## What it provides
+
+A single capability, code **`primethink_admin`**, with 98 tools (every tool
+name is prefixed `primethink_`):
+
+- **Tasks** — list, create, update, get, export, import, duplicate, launch, publish/unpublish, create-version, upload-image
+- **Task evaluation** — list/add/update evaluation items, set evaluation settings, run an evaluation, list runs, get a run, get results, run a simulation, list simulations
+- **Agents** — list, get, create, update, list-types, resolve-capabilities, attach/detach collections, list documents
+- **Capabilities** — list, create, update, archive, duplicate; **model catalog** — list models, list embedding models
+- **Chats** — list, create (optionally from a task), rename, set-goal, archive/unarchive, list-messages, list-files, save-as-task
+- **Chat members & users** — list chat users, invite/remove members, list/search visible users
+- **Notifications** — list, unread-count, mark read/unread, mark-all-read
+- **Scheduled jobs** — list, create, update, set-status
+- **Chat workspaces** — list, create, rename, set-goal, archive, pin, add/remove chat
+- **Collections** — list, create, get, update, reindex, copy, list-files, assign-to-chat (bulk), list-chat-collections, remove-from-chat, set-collection-status
+- **Directories & document versions** — create/move/rename directory; list versions, create text version, set production version (chat/collection/task)
+- **Tags** — list, create, assign; **Groups** — list, get, create, update, list members, remove members, invite, add/remove agents
+
+### Deliberately *not* here
+
+Semantic search, document byte transfer (upload/download/sync), messaging/
+orchestration, and destructive deletes are **excluded** — those are hot-path,
+large-payload, or already covered by native platform capabilities, and should
+not round-trip through the public API. See the design notes in
+[`DEVELOPER.md`](../DEVELOPER.md).
+
+## Authentication
+
+The tools call the PrimeThink API with a **per-user token** read from PrimeThink
+settings under the name **`ADMIN_PRIMETHINK_API_TOKEN`**. When the API injects a
+plugin context providing `get_user_setting_value`, the token is resolved for the
+acting user (`logged_user_id` / `group_id` come from `RunnableConfig`). This is
+the same `${SETTING}` mechanism MCP capabilities use, so both surfaces share one
+auth story.
+
+The API base URL comes from the `PRIMETHINK_API_URL` setting or env var, falling
+back to the CLI's default (`https://api.primethink.ai`).
+
+## Install
+
+**Requires Python 3.9+** — the base CLI still supports 3.8, but the tool
+signatures use `typing.Annotated` (3.9+) and `langchain-core>=0.3.0` does not
+resolve on 3.8. The `dev` extra installs the plugin's test dependencies only on
+3.10+, so plugin tests skip on a 3.9 checkout.
+
+```bash
+# In the API image (production): one pinned line in requirements.txt
+primethink-cli[agent-tools]==1.5.0
+
+# From a checkout (dev): the dev extra already includes langchain-core
+pip install -e ".[dev]"
+```
+
+**Upgrading a dev environment that had the old standalone plugin** (installed
+with `pip install -e internal_tools` before 1.5.0; it was never published to
+PyPI): uninstall it first — `pip uninstall primethink-agent-tools` — and only
+then install `primethink-cli[agent-tools]`. Both distributions own the same
+`primethink_agent_tools` modules and declare the same `primethink_admin` entry
+point, so leaving both installed yields duplicate registrations, and removing
+the old one afterwards deletes files the new install relies on.
+
+The PrimeThink API discovers the plugin at startup via the `primethink.tools`
+entry point declared by `primethink-cli` — no code changes in the API repo.
+Verify discovery:
+
+```bash
+python -c "from importlib.metadata import entry_points; print(list(entry_points().select(group='primethink.tools')))"
+# [EntryPoint(name='primethink_admin', value='primethink_agent_tools:register', group='primethink.tools')]
+```
+
+Then, as a super-admin, convert the registered `primethink_admin` code into a
+capability (`POST /capabilities/from-registered-tool`, type `internal`), assign
+it to an agent, and set `ADMIN_PRIMETHINK_API_TOKEN` for each user who should be
+able to use it. The tools become available in that agent's chats.
+
+Installing the base CLI without the extra is harmless: the entry point is
+declared, but nothing loads it unless the PrimeThink API calls it, and
+`register()` imports langchain lazily. If the API *does* call it on an install
+without the extra, `register()` raises a `ModuleNotFoundError` that names the
+fix (`pip install 'primethink-cli[agent-tools]'`); the API logs it under
+"Failed to load tool plugin: primethink_admin" and starts without the plugin.
+The same message appears on Python 3.8 — the wheel installs there because the
+CLI supports 3.8, but the plugin's tool signatures need `typing.Annotated`
+(3.9+) and the extra's `langchain-core` does not resolve on 3.8, so `register()`
+checks the interpreter first rather than failing on an opaque `typing` import.
+
+## Develop / test
+
+Tests live in `tests/test_agent_tools.py` and run with the rest of the suite;
+they `pytest.importorskip("langchain_core")` so they skip cleanly where the
+extra isn't installed. The packaging contract (entry point, `pyproject.toml`
+packages/extras, RECORD of a non-editable install, the `register()` install
+hint) is covered by `tests/test_packaging.py`, which needs no extra:
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Tests mock `primethink.requests.request` (the reused transport) exactly like the
+main CLI tests, so no network access is needed.

{primethink_cli-1.4.1 → primethink_cli-1.5.0}/docs/cli-reference.md

@@ -1,6 +1,6 @@
 # PrimeThink CLI — Command Reference
 
-Complete reference for every command in the PrimeThink CLI (`pt`), version 1.3.3.
+Complete reference for every command in the PrimeThink CLI (`pt`), version 1.5.0.
 
 Commands are organized into noun groups: `profile`, `live-app`, `chat`, `collection`, `agent`, `task`, `search`, and `image`.
 
@@ -126,6 +126,7 @@ Commands are organized into noun groups: `profile`, `live-app`, `chat`, `collect
   - [`pt task set-public`](#pt-task-set-public)
   - [`pt task set-private`](#pt-task-set-private)
   - [`pt task publish`](#pt-task-publish)
+  - [`pt task launch`](#pt-task-launch)
   - [`pt task test`](#pt-task-test)
   - [`pt task export`](#pt-task-export)
   - [`pt task import`](#pt-task-import)
@@ -220,7 +221,7 @@ Display the CLI version.
 
 ```bash
 pt version
-# PrimeThink CLI v1.3.3
+# PrimeThink CLI v1.5.0
 ```
 
 ### `pt whoami`
@@ -650,11 +651,13 @@ pt chat create [OPTIONS]
 | `--type` | Chat type: `standard` or `direct_users` (server default: `standard`) |
 | `--public/--no-public` | Make the chat public |
 | `--member` | User ID to add as a member; repeat the flag for multiple members |
+| `--from-task-id` | Launch this task into the new chat: copies its goal, default agent, settings, documents, collections and scheduled job and posts its initial prompt (sent as the `copy_from_task_id` query parameter; see [`pt task launch`](#pt-task-launch)) |
 
 ```bash
 pt chat create --name "Q3 planning"
 pt chat create --name "Research" --goal-file ./research-goal.md --virtual-assistant-id 7
 pt chat create --name "Team room" --member 12 --member 15 --public
+pt chat create --workspace-id 738 --from-task-id 280
 ```
 
 ### `pt chat rename`
@@ -2227,20 +2230,46 @@ pt task set-private TASK_ID [--profile NAME] [--api-url URL]
 
 ### `pt task publish`
 
-Create a private task from a conventional project directory, or synchronize the metadata into an existing task when `--task-id` is passed.
+Create a task from a conventional project directory, or synchronize the metadata into an existing task when `--task-id` is passed.
 
 ```bash
-pt task publish DIRECTORY --virtual-assistant-id ID [--task-id ID] [--profile NAME] [--api-url URL]
+pt task publish DIRECTORY --virtual-assistant-id ID [--task-id ID] [--type TYPE] [TOGGLES] [--profile NAME] [--api-url URL]
 ```
 
-`GOAL.md` is required and must not be empty. The task name defaults to the directory name and can be overridden by `.name.config`; the description defaults to the name and can be overridden by `.description.config`; optional `INITIAL_PROMPT.md` supplies the initial prompt. Creation uses the same conservative defaults as the reference workflow (private, published, standard chat, optional features disabled). Updating synchronizes name, description, goal, initial prompt, and virtual assistant without replacing unrelated server fields.
+`GOAL.md` is required and must not be empty. The task name defaults to the directory name and can be overridden by `.name.config`; the description defaults to the name and can be overridden by `.description.config`; optional `INITIAL_PROMPT.md` supplies the initial prompt.
+
+| Option | Description |
+|---|---|
+| `--task-id` | Update this task instead of creating one |
+| `--virtual-assistant-id` | Virtual assistant ID (required) |
+| `--type` | Task type: `private`, `public`, `group`, `system`, `catalog` (default: `private`) |
+| `--global-memory/--no-global-memory` | Enable global memory |
+| `--chat-history/--no-chat-history` | Enable chat history |
+| `--search-in-chat/--no-search-in-chat` | Enable search in chat |
+| `--search-in-documents/--no-search-in-documents` | Enable search in documents |
+| `--summary-enabled/--no-summary-enabled` | Enable summary |
+| `--docs-enabled/--no-docs-enabled` | Enable documents and collections |
+| `--scheduled-jobs/--no-scheduled-jobs` | Enable scheduled jobs |
+| `--email-integration/--no-email-integration` | Enable email integration |
+| `--share-action/--no-share-action` | Enable share action |
+| `--public-chat/--no-public-chat` | Enable public chat |
+| `--run-immediately/--no-run-immediately` | Run the goal immediately when the task is launched |
+
+**Precedence:** an explicit option wins over the project's optional `task.json`, which wins over the conservative defaults. Without either, a created task is `private`, `published`, `standard` chat type, with global memory, chat history, search in chat, search in documents, summary, **documents and collections**, **scheduled jobs**, email integration, share action, and run-immediately all **disabled**, and with empty schedule, extra agents, action name, and mimetypes — so a task that needs its documents, chat history or scheduling must say so (or be fixed afterwards with [`pt task update`](#pt-task-update)).
+
+`task.json` is a JSON object of task fields using the portable field names of `pt task export`/`pt task import` (e.g. `type`, `chat_history`, `documents_and_collections_enabled`, `scheduled_jobs_enabled`, `global_memory`, `mimetypes`, `extra`). Keys that come from the project files or options (`name`, `description`, `goal`, `initial_prompt`, `page_type`, `virtual_assistant_id`), unknown keys and `null` values are ignored; a file that is not a JSON object is an error. Only `pt task publish` reads `task.json`: `pt live-app publish` ignores it, and it is never uploaded as an app asset (a `task.json` in the project root is skipped by the artifact scan). Payloads carrying `schedule_nl`/`schedule_prompt` use the long request timeout, like `pt task create`/`update`.
+
+```json
+{ "type": "group", "chat_history": true, "documents_and_collections_enabled": true, "scheduled_jobs_enabled": true }
+```
 
 ```bash
 pt task publish ./tasks/morning-briefing --virtual-assistant-id 7
+pt task publish ./tasks/morning-briefing --virtual-assistant-id 7 --type group --chat-history --docs-enabled --scheduled-jobs
 pt task publish ./tasks/morning-briefing --task-id 99 --virtual-assistant-id 7
 ```
 
-The command accepts no task-field options. A created task is always `private`, `published`, `standard` chat type, with global memory, chat history, search in chat, search in documents, summary, documents and collections, scheduled jobs, email integration, share action, and run-immediately disabled, and with empty schedule, extra agents, action name, and mimetypes. Use [`pt task update`](#pt-task-update) for anything else; because an update run only PATCHes name, description, goal, initial prompt, virtual assistant, and page type, those settings survive later re-publishing.
+Updating (`--task-id`) PATCHes name, description, goal, initial prompt, virtual assistant and page type, **plus** every type/toggle set on the command line and **every accepted field present in `task.json`** (not only toggles — e.g. `schedule_nl`, `mimetypes`, `extra`); server fields the project does not state are left alone, so settings changed in the UI survive later re-publishing unless the project now states them.
 
 Output is progress lines, not JSON; the task ID is on the last line.
 
@@ -2266,6 +2295,52 @@ publish command can print its ID line and still exit non-zero, because a fatal f
 failure is reported after the sync summary, so a non-empty ID may still come from a run that
 did not fully succeed.
 
+### `pt task launch`
+
+Launch a task into a new chat — what the web app does when you open a task, optionally inside a chat workspace. The new chat gets the task's goal, default agent, settings, documents, collections and scheduled job, and the task's initial prompt is posted.
+
+```bash
+pt task launch TASK_ID [--workspace-id ID|UUID] [--name NAME] [--version N] [--web-url URL] [--profile NAME] [--api-url URL]
+```
+
+| Option | Description |
+|---|---|
+| `--workspace-id` | Chat workspace (ID or UUID) to launch the task into; omit for a top-level chat |
+| `--name` | Chat name (default: the task name) |
+| `--version` | Task version number to launch (default: the current task) |
+| `--web-url` | Web application URL for the printed link (default: derived from the API URL, `api.` → `app.`) |
+
+```bash
+pt task launch 280 --workspace-id 738
+pt task launch 280 --workspace-id ca74dfc4-eb41-4c3f-ae53-b6b1c415617f --name "Collector (CTO)"
+```
+
+Output is the created chat as JSON (`id`, `uuid`, `task_id`, `default_virtual_assistant_id`, …) followed by a `Chat URL:` line:
+
+```text
+{
+  "id": 50020,
+  "uuid": "132f94b9-…",
+  "task_id": 280,
+  ...
+}
+Chat URL: https://app.primethink.ai/chats/132f94b9-…
+```
+
+The same launch is available as [`pt chat create --from-task-id`](#pt-chat-create) and as the `launch_task` MCP tool. Under the hood it is `POST /api/v1/chats?copy_from_task_id=TASK_ID` — the task cannot be passed in the body (the server ignores a body `task_id`). Provisioning example — start a task in every workspace that doesn't have it yet:
+
+```bash
+# Raise --page-size (or loop over --page) if you have more than 100 workspaces / 200 chats per workspace.
+for ws in $(pt workspace list --page-size 100 | jq -r 'if type == "array" then .[] else .items[] end | .id'); do
+  chats=$(pt chat list --workspace-id "$ws" --page-size 200) || { echo "chat lookup failed for workspace $ws, skipping" >&2; continue; }
+  present=$(printf '%s' "$chats" | jq 'if type == "array" then . else .items end | map(select(.task_id == 280)) | length') || { echo "unexpected chat list for workspace $ws, skipping" >&2; continue; }
+  if [ "$present" = "0" ]; then
+    pt task launch 280 --workspace-id "$ws"
+  fi
+done
+```
+A lookup or parsing failure skips the workspace instead of launching a duplicate.
+
 ### `pt task test`
 
 Apply a task project's required `GOAL.md` to a newly created chat or an explicit existing chat. Existing chats are switched to normal chat mode.
@@ -2683,7 +2758,7 @@ Core API management commands have tool equivalents; local scaffolding and the pr
 | Directories | `create_directory`, `delete_directory`, `move_directory`, `rename_directory` (each takes `owner_type` = chat/collection/task/agent) |
 | Document versions | `list_document_versions`, `create_document_version`, `create_document_text_version`, `set_production_version`, `delete_document_version` (each takes `owner_type` = chat/collection/task) |
 | Collections | `list_collections`, `create_collection`, `get_collection`, `update_collection`, `reindex_collection`, `copy_collection`, `delete_collection`, `delete_collection_file`, `list_collection_files`, `upload_collection_files`, `upload_collection_text`, `download_collection_file`, `sync_collection_to`, `sync_collection_from` |
-| Tasks | `list_tasks`, `create_task`, `update_task`, `get_task`, `upload_task_text`, `add_task_documents`, `delete_task_documents`, `export_task`, `delete_task`, `duplicate_task`, `publish_task`, `unpublish_task`, `import_task`, `create_task_version`, `upload_task_image` |
+| Tasks | `list_tasks`, `create_task`, `update_task`, `get_task`, `upload_task_text`, `add_task_documents`, `delete_task_documents`, `export_task`, `delete_task`, `duplicate_task`, `launch_task` (start a task in a new chat, optionally in a workspace — `create_chat` also takes `from_task_id`), `publish_task`, `unpublish_task`, `import_task`, `create_task_version`, `upload_task_image` |
 | Task evaluation | `list_task_evaluations`, `add_task_evaluation`, `update_task_evaluation`, `delete_task_evaluation`, `set_task_evaluation_settings`, `run_task_evaluation`, `list_task_evaluation_runs`, `get_task_evaluation_run`, `get_task_evaluation_results`, `download_task_evaluation_run`, `run_task_simulation`, `list_task_simulations`, `delete_task_simulation` |
 | Agents | `list_agents`, `get_agent`, `create_agent`, `update_agent`, `delete_agent`, `list_agent_types`, `list_agent_documents`, `upload_agent_documents`, `attach_agent_collections`, `detach_agent_collection`, `upload_agent_image`, `delete_agent_image` |
 | Capabilities | `list_capabilities`, `create_capability`, `update_capability`, `delete_capability`, `archive_capability`, `duplicate_capability`, `resolve_capabilities` |

{primethink_cli-1.4.1 → primethink_cli-1.5.0}/docs/install.md

@@ -45,6 +45,19 @@ pip install 'primethink-cli[mcp]'
 
 See the [CLI reference](cli-reference.md#mcp-server-pt-mcp) for details.
 
+#### Optional: agent tools plugin (for the PrimeThink API image)
+
+The `agent-tools` extra enables the LangChain tools plugin that PrimeThink
+agents use to manage tasks, agents, chats, and collections. It is meant for the
+agent runtime / API image, not for end users, and pulls in `langchain-core`
+(Python 3.9+):
+
+```bash
+pip install 'primethink-cli[agent-tools]'
+```
+
+See [agent-tools.md](agent-tools.md) for details.
+
 ### Homebrew (macOS & Linux)
 ```bash
 # Add our tap (one-time setup)
@@ -70,6 +83,7 @@ pt --help
 
 - **Python 3.8+** (required for pip installation)
 - **Python 3.10+** (only for the optional MCP server, `pip install 'primethink-cli[mcp]'`)
+- **Python 3.9+** (only for the optional agent tools plugin, `pip install 'primethink-cli[agent-tools]'`)
 - **Homebrew** (only for Homebrew installation)
 
 ## Getting Started