mammoth-cli 2.1.6__tar.gz → 2.2.0__tar.gz

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.1.6
+Version: 2.2.0
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.9,>=0.8.2
+Requires-Dist: mammoth-io<0.9,>=0.8.3
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.1.6"
+__version__ = "2.2.0"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/app.py

@@ -30,6 +30,7 @@ from typer.core import TyperGroup
 from mammoth_cli import __version__
 from mammoth_cli.commands import BESPOKE
 from mammoth_cli.commands.registry import HANDLERS, Handler
+from mammoth_cli.commands.schema import IN_PLACE_RECIPE, edits_view_in_place
 from mammoth_cli.context import profiles
 from mammoth_cli.errors.envelope import EXIT_USAGE, CliError, not_implemented_error
 from mammoth_cli.manifest.loader import command_by_id, load_commands
@@ -60,7 +61,7 @@ OUTPUT_MODES = VALID_OUTPUTS
 _GROUP_DESCRIPTIONS = {
     "activity": "Inspect workspace activity and audit history.",
     "addon": "Manage workspace add-ons.",
-    "agent": "Work with Mammoth agent sessions and messages.",
+    "agent": "Work with Mammoth agent sessions, the changes a chat made, and its runs.",
     "ai": "Generate AI-assisted expressions and conditions.",
     "annotation": "Manage annotations on Mammoth resources.",
     "auth": "Sign in, sign out, and inspect credentials.",
@@ -556,6 +557,18 @@ def _shared_option_params() -> list[inspect.Parameter]:
                 ),
             ],
         ),
+        opt(
+            "session",
+            None,
+            Annotated[
+                str | None,
+                typer.Option(
+                    "--session",
+                    help="Agent chat session id for 'agent action' and 'agent run' commands.",
+                    rich_help_panel="Context and timeouts",
+                ),
+            ],
+        ),
         opt(
             "timeout",
             None,
@@ -929,6 +942,8 @@ def _command_help(command_id: str, record: dict[str, Any] | None) -> str | None:
         summary = doc.strip().splitlines()[0].strip().replace("``", "'")
         if summary:
             parts.append(summary)
+    if record is not None and edits_view_in_place(record):
+        parts.append(IN_PLACE_RECIPE)
     example = (record or {}).get("agent_example")
     if example:
         parts.append(f"Example: {example}")

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/bundled_skill/mammoth-cli/references/command-index.md

@@ -1,12 +1,12 @@
 # Published CLI command catalog
 
-This generated catalog is a lookup table for every command in the published CLI manifest, currently 580; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
+This generated catalog is a lookup table for every command in the published CLI manifest, currently 588; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
 
 Load only the applicable domain file:
 
 - [activity](commands/activity.md) — 2 published commands
 - [addon](commands/addon.md) — 7 published commands
-- [agent](commands/agent.md) — 5 published commands
+- [agent](commands/agent.md) — 13 published commands
 - [ai](commands/ai.md) — 5 published commands
 - [annotation](commands/annotation.md) — 5 published commands
 - [auth](commands/auth.md) — 3 published commands

mammoth_cli-2.2.0/mammoth_cli/bundled_skill/mammoth-cli/references/commands/agent.md

@@ -0,0 +1,133 @@
+# `agent` commands
+
+Every command returns the standard JSON envelope. On nonzero exit, read the error envelope and its `recovery_commands`; do not guess request fields. "Status on release" is joined from `docs/release-capability-matrix.json`: *ran once* means one bounded live run succeeded on the named CLI release, *untried* means nobody has run it, *not supported* means the backend refuses it. When this file disagrees with [capabilities](../capabilities.md) or a recipe, they win. Envelope shapes: [machine output](../machine-output.md).
+
+### `agent.action.delete`
+
+Run: `mammoth agent action delete`. Exact input fields: `mammoth schema get agent.action.delete`.
+
+Example: `mammoth agent action delete resource-123`. Illustrative only: append `--yes` after observing an owned target.
+
+Result: `AgentActionDeleteResult`; mutation `destructive`, confirmation `prompt_or_yes`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.action.list`
+
+Run: `mammoth agent action list`. Exact input fields: `mammoth schema get agent.action.list`.
+
+Example: `mammoth agent action list`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentActionListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.chat`
+
+Run: `mammoth agent chat`. Exact input fields: `mammoth schema get agent.chat`.
+
+Example: `mammoth agent chat --input '{"message": "Summarize revenue by region", "scope": {"sample_key": "Status"}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentChatResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.run.extend`
+
+Run: `mammoth agent run extend`. Exact input fields: `mammoth schema get agent.run.extend`.
+
+Example: `mammoth agent run extend resource-123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentRunExtendResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.run.list`
+
+Run: `mammoth agent run list`. Exact input fields: `mammoth schema get agent.run.list`.
+
+Example: `mammoth agent run list`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentRunListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.run.pause`
+
+Run: `mammoth agent run pause`. Exact input fields: `mammoth schema get agent.run.pause`.
+
+Example: `mammoth agent run pause resource-123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentRunPauseResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.run.resume`
+
+Run: `mammoth agent run resume`. Exact input fields: `mammoth schema get agent.run.resume`.
+
+Example: `mammoth agent run resume resource-123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentRunResumeResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.run.status`
+
+Run: `mammoth agent run status`. Exact input fields: `mammoth schema get agent.run.status`.
+
+Example: `mammoth agent run status`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentRunStatusResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.run.stop`
+
+Run: `mammoth agent run stop`. Exact input fields: `mammoth schema get agent.run.stop`.
+
+Example: `mammoth agent run stop resource-123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentRunStopResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.session.delete`
+
+Run: `mammoth agent session delete`. Exact input fields: `mammoth schema get agent.session.delete`.
+
+Example: `mammoth agent session delete resource-123`. Illustrative only: append `--yes` after observing an owned target.
+
+Result: `AgentSessionDeleteResult`; mutation `destructive`, confirmation `prompt_or_yes`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.session.list`
+
+Run: `mammoth agent session list`. Exact input fields: `mammoth schema get agent.session.list`.
+
+Example: `mammoth agent session list`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentSessionListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: ran once on CLI 2.0.11 — Read-only sweep 2026-09-18: exit 0 on release with CLI 2.0.11; result keys: sessions. Single read only; no fixture variants, error envelopes, or write paths assessed.
+
+### `agent.session.messages`
+
+Run: `mammoth agent session messages`. Exact input fields: `mammoth schema get agent.session.messages`.
+
+Example: `mammoth agent session messages resource-123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentSessionMessagesResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `agent.session.set-visibility`
+
+Run: `mammoth agent session set-visibility`. Exact input fields: `mammoth schema get agent.session.set-visibility`.
+
+Example: `mammoth agent session set-visibility resource-123 --input '{"visibility": "sample"}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `AgentSessionSetVisibilityResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/commands/agent.py

@@ -204,3 +204,62 @@ def agent_session_set_visibility(invocation: Invocation) -> HandlerResult:
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), session_id=session_id, visibility=visibility)
     return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def _require_session(invocation: Invocation) -> str:
+    """Return the agent chat session id, raising when none was given.
+
+    An embedded call gets the embedding chat's session as ``--session`` from
+    :func:`mammoth_cli.embed.invoke`; outside that, the caller passes it.
+
+    Raises:
+        CliError: ``missing_argument`` when no session id is set.
+    """
+    if not invocation.session:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message="This command requires a session id.",
+            exit_status=EXIT_USAGE,
+            hint="Pass --session SESSION_ID (see 'mammoth agent session list').",
+        )
+    return invocation.session
+
+
+def _session_call(invocation: Invocation, **ids: str) -> HandlerResult:
+    """Call this command's SDK method on the session plus any extra ids."""
+    session_id = _require_session(invocation)
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), session_id=session_id, **ids)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def agent_action_list(invocation: Invocation) -> HandlerResult:
+    """List the changes one agent chat session made."""
+    return _session_call(invocation)
+
+
+def agent_action_delete(invocation: Invocation) -> HandlerResult:
+    """Delete one object the chat created, by action id. Prompt or ``--yes`` required."""
+    action_id = _require_string_positional(invocation, "action id")
+    enforce_confirmation(
+        invocation, policy=POLICY_PROMPT_OR_YES, action=f"delete what agent action {action_id} made"
+    )
+    return _session_call(invocation, action_id=action_id)
+
+
+def agent_run_status(invocation: Invocation) -> HandlerResult:
+    """Show the current run of one agent chat session."""
+    return _session_call(invocation)
+
+
+def agent_run_list(invocation: Invocation) -> HandlerResult:
+    """List the runs of one agent chat session."""
+    return _session_call(invocation)
+
+
+def _run_control(invocation: Invocation) -> HandlerResult:
+    """Pause, resume, stop or extend one run; the SDK method is the manifest's."""
+    return _session_call(invocation, run_id=_require_string_positional(invocation, "run id"))
+
+
+agent_run_pause = agent_run_resume = agent_run_stop = agent_run_extend = _run_control

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/commands/registry.py

@@ -535,7 +535,15 @@ HANDLERS: dict[str, Handler] = {
     "schedule.update": schedule_cmd.schedule_update,
     "schedule.delete": schedule_cmd.schedule_delete,
     # agent family
+    "agent.action.delete": agent_cmd.agent_action_delete,
+    "agent.action.list": agent_cmd.agent_action_list,
     "agent.chat": agent_cmd.agent_chat,
+    "agent.run.extend": agent_cmd.agent_run_extend,
+    "agent.run.list": agent_cmd.agent_run_list,
+    "agent.run.pause": agent_cmd.agent_run_pause,
+    "agent.run.resume": agent_cmd.agent_run_resume,
+    "agent.run.status": agent_cmd.agent_run_status,
+    "agent.run.stop": agent_cmd.agent_run_stop,
     "agent.session.delete": agent_cmd.agent_session_delete,
     "agent.session.list": agent_cmd.agent_session_list,
     "agent.session.messages": agent_cmd.agent_session_messages,

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/commands/schema.py

@@ -469,6 +469,28 @@ _SCOPE_REQUIREMENTS: dict[str, dict[str, Any]] = {
 }
 
 _MAX_FIND_RESULTS = 20
+# View transform/task commands add a step to the GIVEN view. An agent asked for
+# a NEW dataset must know that before calling, so the statement is carried by
+# every such command's contract (schema get ``preconditions``, find, --help).
+_IN_PLACE_PREFIXES = ("view.transform.", "view.task.")
+IN_PLACE_RECIPE = (
+    "EDITS THE GIVEN VIEW IN PLACE: this adds a step to the view and changes that view "
+    "and its dataset's output. To make a NEW dataset and leave the source untouched: "
+    "`mammoth view create SOURCE_DATASET_ID` (working view), do the steps on that working "
+    'view, then `mammoth view export dataset WORKING_VIEW_ID --input \'{"dataset_name": "..."}\'`.'
+)
+_IN_PLACE_KEYWORDS = (
+    "new dataset create make in place edits given view working view source untouched"
+)
+
+
+def edits_view_in_place(record: dict[str, Any]) -> bool:
+    """True for a view transform/task command that changes an existing view."""
+    return bool(record.get("edits_target")) and str(record.get("command_id", "")).startswith(
+        _IN_PLACE_PREFIXES
+    )
+
+
 # Outranks any word-overlap score: a command named by its full path comes first.
 _NAMED_COMMAND_BOOST = 10_000
 # Bag-of-words scoring cannot tell "create a NEW VIEW from an existing
@@ -944,7 +966,9 @@ def _compact_contract(record: dict[str, Any]) -> dict[str, Any]:
             "the intended postcondition."
         )
     restrictions = record.get("known_restrictions")
-    if restrictions is None:
+    if edits_view_in_place(record):
+        restrictions = f"{IN_PLACE_RECIPE} {restrictions or ''}".strip()
+    elif restrictions is None:
         required_positionals = [
             str(item.get("metavar") or item.get("name"))
             for item in record.get("positionals", [])
@@ -1664,6 +1688,7 @@ def find_schemas(
             (30, f"{record.get('human_example', '')} {record.get('agent_example', '')}"),
             (20, positional_help),
             (15, _operation_hints_by_command().get(command_id, "")),
+            (15, _IN_PLACE_KEYWORDS if edits_view_in_place(record) else ""),
             (60, _COMMAND_DISCOVERY_PURPOSES.get(command_id, "")),
             (3, _GROUP_DISCOVERY_PURPOSES.get(command_path.split()[0], "")),
         )

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/embed.py

@@ -39,6 +39,7 @@ def invoke(
     *,
     login: ExplicitLogin,
     project_id: int | None = None,
+    session_id: str | None = None,
     timeout: float | None = None,
     pipeline_timeout: float | None = None,
     job_timeout: float | None = None,
@@ -52,6 +53,9 @@ def invoke(
         login: The credentials, endpoint and extra headers for this call.
         project_id: The active project, sent as ``--project`` unless ``args``
             already names one.
+        session_id: The embedding chat's session, sent as ``--session`` unless
+            ``args`` already names one; ``agent action`` and ``agent run``
+            commands act on it, so the model never has to know its id.
         timeout: Per-request timeout in seconds, sent as ``--timeout`` unless
             ``args`` already sets one.
         pipeline_timeout: Pipeline wait timeout in seconds, sent as
@@ -68,6 +72,7 @@ def invoke(
     argv = _argv(
         args,
         project_id=project_id,
+        session_id=session_id,
         timeout=timeout,
         pipeline_timeout=pipeline_timeout,
         job_timeout=job_timeout,
@@ -92,11 +97,14 @@ def _argv(
     pipeline_timeout: float | None,
     job_timeout: float | None,
     return_running: bool,
+    session_id: str | None = None,
 ) -> list[str]:
     """``args`` plus the options an embedded call always runs with."""
     argv = list(args)
     if project_id is not None and not _has_option(argv, "--project"):
         argv += ["--project", str(project_id)]
+    if session_id is not None and not _has_option(argv, "--session"):
+        argv += ["--session", session_id]
     if timeout is not None and not _has_option(argv, "--timeout"):
         argv += ["--timeout", str(timeout)]
     if pipeline_timeout is not None and not _has_option(argv, "--pipeline-timeout"):

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/runtime/invocation.py

@@ -50,6 +50,7 @@ class Invocation:
     output: str = "table"
     profile: str | None = None
     project: int | None = None
+    session: str | None = None
     timeout: float | None = None
     job_timeout: float | None = None
     pipeline_timeout: float | None = None

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/services/input_fields.py

@@ -7,6 +7,20 @@ from typing import Any
 from mammoth_cli.services.positionals import resolve_positionals
 
 _HANDLER_OWNED_FIELDS: dict[str, frozenset[str]] = {
+    # The chat session comes from the global ``--session`` option.
+    **{
+        f"agent.{command}": frozenset({"session_id"})
+        for command in (
+            "action.list",
+            "action.delete",
+            "run.status",
+            "run.list",
+            "run.pause",
+            "run.resume",
+            "run.stop",
+            "run.extend",
+        )
+    },
     # Skill handlers deliberately derive filesystem roots from the running
     # process and generate their own backup timestamp.  User input must not
     # claim to control values that the handlers replace or omit.

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/services/positionals.py

@@ -127,6 +127,30 @@ def _optional_project_id() -> tuple[PositionalSpec, ...]:
 # Commands whose positionals the signature cannot express correctly. Each entry
 # replaces the derivation wholesale; the drift test proves the union is right.
 POSITIONAL_OVERRIDES: dict[str, tuple[PositionalSpec, ...]] = {
+    # The chat session is the global ``--session`` option, never a positional or
+    # an --input field; only the action or run being addressed is positional.
+    "agent.action.list": (),
+    "agent.run.status": (),
+    "agent.run.list": (),
+    "agent.action.delete": (
+        PositionalSpec(
+            name="action_id",
+            type=str,
+            required=True,
+            help="ID of the recorded action (from agent action list).",
+        ),
+    ),
+    **{
+        f"agent.run.{verb}": (
+            PositionalSpec(
+                name="run_id",
+                type=str,
+                required=True,
+                help="ID of the run (from agent run status or agent run list).",
+            ),
+        )
+        for verb in ("pause", "resume", "stop", "extend")
+    },
     "dashboard.assess-twb": (
         PositionalSpec(
             name="file",

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/mammoth_cli/services/sdk_service.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 import asyncio
 import inspect
+import os
 import re
 import threading
 from collections.abc import Callable
@@ -73,6 +74,10 @@ def _unrecognized_expression_token(message: str, expression: Any) -> str:
     return token or expression
 
 
+AGENT_RUN_ENV = "MAMMOTH_AGENT_RUN"
+AGENT_RUN_HEADER = "X-Mammoth-Agent-Run"
+
+
 class SdkMammothService:
     """Production :class:`~mammoth_cli.services.protocol.MammothService`."""
 
@@ -141,6 +146,11 @@ class SdkMammothService:
             # After construction: the client sets its credential headers in
             # ``__init__``, and a forwarded session must replace them.
             self._client.session.headers.update(auth.headers)
+        run_id = os.environ.get(AGENT_RUN_ENV, "").strip()
+        if run_id:
+            # A leg of a durable agent run names its run, so the server can
+            # refuse the run's own resume and extend.
+            self._client.session.headers[AGENT_RUN_HEADER] = run_id
         if project_id is not None:
             self._client.set_project_id(project_id)
 

{mammoth_cli-2.1.6 → mammoth_cli-2.2.0}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.1.6"
+version = "2.2.0"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.12,<3.15"
 dependencies = [
-    "mammoth-io (>=0.8.2,<0.9)",
+    "mammoth-io (>=0.8.3,<0.9)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",