unique-sdk 2026.32.0.dev0__tar.gz → 2026.32.0.dev2__tar.gz

{unique_sdk-2026.32.0.dev0 → unique_sdk-2026.32.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.32.0.dev0
+Version: 2026.32.0.dev2
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.32.0.dev0 → unique_sdk-2026.32.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.32.0.dev0"
+version = "2026.32.0.dev2"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.32.0.dev0 → unique_sdk-2026.32.0.dev2}/unique_sdk/cli/cli.py

@@ -9,6 +9,15 @@ from typing import Any
 import click
 
 from unique_sdk.cli import __version__
+from unique_sdk.cli.commands.agentic_table import (
+    cmd_cell_history,
+    cmd_get_cell,
+    cmd_get_sheet,
+    cmd_list_exports,
+)
+from unique_sdk.cli.commands.agentic_table import (
+    is_error_output as _is_agentic_table_error_output,
+)
 from unique_sdk.cli.commands.browser import (
     cmd_browser_action,
     cmd_browser_control,
@@ -167,6 +176,7 @@ Examples:
   unique-cli web-search crawl URL   Crawl a URL via the public API
   unique-cli dynamic-frontend list  List manageable Dynamic Frontend spaces
   unique-cli browser get-dom        Read the user's live Chrome tab (a11y tree)
+  unique-cli agentic-table get-sheet mt_abc123  Show a magic-table sheet summary
 """
 
 
@@ -2240,3 +2250,200 @@ def web_search_crawl_cmd(
         config_path=resolved_config,
     )
     _emit_web_search(ctx, output)
+
+
+# -- Agentic Table ---------------------------------------------------------
+
+
+_AGENTIC_TABLE_HELP = """\
+Read Agentic Table (magic table) sheets, cells, and cell history.
+
+\b
+These are Tier 0 reads over the public magic-table API: no confirmation,
+no writes. Every call is scoped to the current user/company; sheet-role
+access (Owner / Can manage / Can edit) is enforced server-side and a denial
+is reported as `agentic-table: permission denied`.
+
+\b
+Subcommands:
+  get-sheet      Show a sheet summary (state, row count, metadata, cells)
+  get-cell       Show a single cell by row/column order
+  cell-history   Show a single cell's log/edit history
+  list-exports   List a sheet's export artifacts (reports, question exports)
+
+\b
+Examples:
+  unique-cli agentic-table get-sheet mt_abc123
+  unique-cli agentic-table get-sheet mt_abc123 --cells --metadata
+  unique-cli agentic-table get-cell mt_abc123 --row 1 --col 2
+  unique-cli agentic-table cell-history mt_abc123 --row 1 --col 2 --json
+  unique-cli agentic-table list-exports mt_abc123
+"""
+
+
+@main.group("agentic-table", help=_AGENTIC_TABLE_HELP)
+def agentic_table() -> None:
+    pass
+
+
+@agentic_table.command(name="get-sheet")
+@click.argument("table_id")
+@click.option(
+    "--cells",
+    "include_cells",
+    is_flag=True,
+    default=False,
+    help="Include cell values in the output.",
+)
+@click.option(
+    "--metadata",
+    "include_metadata",
+    is_flag=True,
+    default=False,
+    help="Include sheet-level metadata entries.",
+)
+@click.option(
+    "--json", "output_json", is_flag=True, default=False, help="Print raw JSON."
+)
+@click.pass_context
+def agentic_table_get_sheet(
+    ctx: click.Context,
+    table_id: str,
+    include_cells: bool,
+    include_metadata: bool,
+    output_json: bool,
+) -> None:
+    """Show a magic-table sheet summary.
+
+    \b
+    TABLE_ID is the magic-table sheet id. By default only the summary
+    (name, state, row count) is shown; add --metadata for sheet metadata
+    and --cells to include cell values.
+
+    \b
+    Examples:
+      unique-cli agentic-table get-sheet mt_abc123
+      unique-cli agentic-table get-sheet mt_abc123 --cells --metadata
+    """
+    emit(
+        cmd_get_sheet(
+            LazyState.get(ctx),
+            table_id,
+            include_cells=include_cells,
+            include_metadata=include_metadata,
+            output_json=output_json,
+        ),
+        is_error=_is_agentic_table_error_output,
+    )
+
+
+@agentic_table.command(name="get-cell")
+@click.argument("table_id")
+@click.option(
+    "--row", "row_order", type=int, required=True, help="Row order (0-based)."
+)
+@click.option(
+    "--col", "column_order", type=int, required=True, help="Column order (0-based)."
+)
+@click.option(
+    "--json", "output_json", is_flag=True, default=False, help="Print raw JSON."
+)
+@click.pass_context
+def agentic_table_get_cell(
+    ctx: click.Context,
+    table_id: str,
+    row_order: int,
+    column_order: int,
+    output_json: bool,
+) -> None:
+    """Show a single cell by row/column order.
+
+    \b
+    Examples:
+      unique-cli agentic-table get-cell mt_abc123 --row 1 --col 2
+      unique-cli agentic-table get-cell mt_abc123 --row 1 --col 2 --json
+    """
+    emit(
+        cmd_get_cell(
+            LazyState.get(ctx),
+            table_id,
+            row_order=row_order,
+            column_order=column_order,
+            output_json=output_json,
+        ),
+        is_error=_is_agentic_table_error_output,
+    )
+
+
+@agentic_table.command(name="cell-history")
+@click.argument("table_id")
+@click.option(
+    "--row", "row_order", type=int, required=True, help="Row order (0-based)."
+)
+@click.option(
+    "--col", "column_order", type=int, required=True, help="Column order (0-based)."
+)
+@click.option(
+    "--json", "output_json", is_flag=True, default=False, help="Print raw JSON."
+)
+@click.pass_context
+def agentic_table_cell_history(
+    ctx: click.Context,
+    table_id: str,
+    row_order: int,
+    column_order: int,
+    output_json: bool,
+) -> None:
+    """Show a single cell's log/edit history.
+
+    \b
+    Lists the cell's log entries (actor, timestamp, source message id, and
+    the logged text) as recorded by prior edits.
+
+    \b
+    Examples:
+      unique-cli agentic-table cell-history mt_abc123 --row 1 --col 2
+      unique-cli agentic-table cell-history mt_abc123 --row 1 --col 2 --json
+    """
+    emit(
+        cmd_cell_history(
+            LazyState.get(ctx),
+            table_id,
+            row_order=row_order,
+            column_order=column_order,
+            output_json=output_json,
+        ),
+        is_error=_is_agentic_table_error_output,
+    )
+
+
+@agentic_table.command(name="list-exports")
+@click.argument("table_id")
+@click.option(
+    "--json", "output_json", is_flag=True, default=False, help="Print raw JSON."
+)
+@click.pass_context
+def agentic_table_list_exports(
+    ctx: click.Context,
+    table_id: str,
+    output_json: bool,
+) -> None:
+    """List a sheet's export artifacts.
+
+    \b
+    Shows generated exports (full report, question export, agentic report)
+    with their state and, once ready, the content id to download.
+
+    \b
+    Examples:
+      unique-cli agentic-table list-exports mt_abc123
+      unique-cli agentic-table list-exports mt_abc123 --json
+    """
+    emit(
+        cmd_list_exports(
+            LazyState.get(ctx),
+            table_id,
+            output_json=output_json,
+        ),
+        is_error=_is_agentic_table_error_output,
+    )

unique_sdk-2026.32.0.dev2/unique_sdk/cli/commands/agentic_table.py

@@ -0,0 +1,150 @@
+"""Agentic Table (magic table) read commands for the Unique CLI.
+
+Tier 0 reads over the public magic-table API (``2023-12-06``): fetch a sheet
+summary, a single cell, or a cell's edit history. Every call is scoped to the
+runner-injected user/company; sheet-role enforcement (Owner / Can manage /
+Can edit) happens server-side via the platform's access guard, and a 403 is
+surfaced as ``agentic-table: permission denied``.
+
+These reads require no confirmation. Later write commands live in their own
+module so the audit/activity-status plumbing lands with its first caller.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from unique_sdk._error import UniqueError
+from unique_sdk.api_resources._agentic_table import AgenticTable
+from unique_sdk.cli.formatting import (
+    format_agentic_table_artifacts,
+    format_agentic_table_cell,
+    format_agentic_table_cell_history,
+    format_agentic_table_sheet,
+)
+from unique_sdk.cli.state import ShellState
+
+AGENTIC_TABLE_ERROR_PREFIX = "agentic-table:"
+
+
+def is_error_output(output: str) -> bool:
+    """Return ``True`` when *output* is an error message from an ``agentic-table`` command."""
+    return output.startswith(AGENTIC_TABLE_ERROR_PREFIX)
+
+
+def _error(exc: UniqueError) -> str:
+    """Render an SDK error as a CLI error line.
+
+    A 403 (the platform's sheet-access guard) is collapsed to a stable
+    ``permission denied`` message so agent ``&&`` chains stop cleanly and the
+    wording does not leak backend detail; other errors pass through verbatim.
+    """
+    if exc.http_status == 403:
+        return f"{AGENTIC_TABLE_ERROR_PREFIX} permission denied"
+    return f"{AGENTIC_TABLE_ERROR_PREFIX} {exc}"
+
+
+def cmd_get_sheet(
+    state: ShellState,
+    table_id: str,
+    *,
+    include_cells: bool = False,
+    include_metadata: bool = False,
+    output_json: bool = False,
+) -> str:
+    """Fetch a sheet summary: name, state, row count, and (optionally) metadata/cells."""
+    try:
+        sheet = asyncio.run(
+            AgenticTable.get_sheet_data(
+                user_id=state.config.user_id,
+                company_id=state.config.company_id,
+                tableId=table_id,
+                includeCells=include_cells,
+                includeRowCount=True,
+                includeSheetMetadata=include_metadata,
+            )
+        )
+    except UniqueError as exc:
+        return _error(exc)
+
+    if output_json:
+        return json.dumps(sheet, indent=2, default=str)
+    return format_agentic_table_sheet(sheet, include_cells=include_cells)
+
+
+def cmd_get_cell(
+    state: ShellState,
+    table_id: str,
+    *,
+    row_order: int,
+    column_order: int,
+    output_json: bool = False,
+) -> str:
+    """Fetch a single cell by row/column order."""
+    try:
+        cell = asyncio.run(
+            AgenticTable.get_cell(
+                user_id=state.config.user_id,
+                company_id=state.config.company_id,
+                tableId=table_id,
+                rowOrder=row_order,
+                columnOrder=column_order,
+            )
+        )
+    except UniqueError as exc:
+        return _error(exc)
+
+    if output_json:
+        return json.dumps(cell, indent=2, default=str)
+    return format_agentic_table_cell(cell)
+
+
+def cmd_cell_history(
+    state: ShellState,
+    table_id: str,
+    *,
+    row_order: int,
+    column_order: int,
+    output_json: bool = False,
+) -> str:
+    """Fetch a single cell's log/edit history (``logEntries`` on the cell record)."""
+    try:
+        cell = asyncio.run(
+            AgenticTable.get_cell(
+                user_id=state.config.user_id,
+                company_id=state.config.company_id,
+                tableId=table_id,
+                rowOrder=row_order,
+                columnOrder=column_order,
+            )
+        )
+    except UniqueError as exc:
+        return _error(exc)
+
+    if output_json:
+        return json.dumps(cell.get("logEntries") or [], indent=2, default=str)
+    return format_agentic_table_cell_history(cell)
+
+
+def cmd_list_exports(
+    state: ShellState,
+    table_id: str,
+    *,
+    output_json: bool = False,
+) -> str:
+    """List a sheet's export artifacts (reports, question exports)."""
+    try:
+        artifacts = asyncio.run(
+            AgenticTable.list_artifacts(
+                user_id=state.config.user_id,
+                company_id=state.config.company_id,
+                tableId=table_id,
+            )
+        )
+    except UniqueError as exc:
+        return _error(exc)
+
+    if output_json:
+        return json.dumps(artifacts, indent=2, default=str)
+    return format_agentic_table_artifacts(artifacts)

{unique_sdk-2026.32.0.dev0 → unique_sdk-2026.32.0.dev2}/unique_sdk/cli/commands/elicitation.py

@@ -687,9 +687,19 @@ def cmd_elicit_wait(
                 if final_status in TERMINAL_STATUSES:
                     terminal_status = final_status
                     return format_elicitation(final)
+                # Non-terminal timeout: this is the one output every harness
+                # (Claude Code, Codex, ...) reads after every poll. Make it an
+                # explicit instruction to poll again, not just a description of
+                # what happened — a model that stops here has nowhere else to
+                # look for "what do I do next" (see UN-23181).
                 return (
-                    f"elicit: timed out after {timeout}s waiting for "
-                    f"{elicitation_id} (last status: {final_status or 'UNKNOWN'})\n\n"
+                    f"elicit: still PENDING after {timeout}s waiting for "
+                    f"{elicitation_id} (last status: {final_status or 'UNKNOWN'}) "
+                    "— this is NOT a stopping condition.\n"
+                    f"Call again now: unique-cli elicit wait {elicitation_id} "
+                    f"--timeout {timeout} --poll-interval {poll_interval}\n"
+                    "Do not tell the user you stopped waiting; keep polling "
+                    "until a terminal status or expiry.\n\n"
                     f"{format_elicitation(last)}"
                 )
             time.sleep(poll_interval)

{unique_sdk-2026.32.0.dev0 → unique_sdk-2026.32.0.dev2}/unique_sdk/cli/formatting.py

@@ -11,6 +11,11 @@ from unique_sdk.api_resources._content import Content
 from unique_sdk.api_resources._folder import Folder
 
 if TYPE_CHECKING:
+    from unique_sdk.api_resources._agentic_table import (
+        AgenticTableCell,
+        AgenticTableSheet,
+        MagicTableArtifact,
+    )
     from unique_sdk.api_resources._mcp import MCP
     from unique_sdk.api_resources._scheduled_task import ScheduledTask
 
@@ -37,6 +42,14 @@ def _format_date(iso_str: str | None) -> str:
         return iso_str[:16] if len(iso_str) >= 16 else iso_str
 
 
+def _snippet(text: str | None, limit: int = 80) -> str:
+    """Collapse *text* to a single-line snippet no longer than *limit* chars."""
+    collapsed = (text or "").replace("\n", " ").strip()
+    if len(collapsed) <= limit:
+        return collapsed
+    return collapsed[:limit] + "..."
+
+
 def _pad_columns(rows: list[list[str]]) -> list[str]:
     """Pad columns to align output."""
     if not rows:
@@ -332,3 +345,126 @@ def format_mcp_response(response: MCP, *, tool_name: str | None = None) -> str:
             lines.append(f"[{content_type}] (unsupported content type)")
 
     return "\n".join(lines)
+
+
+def format_agentic_table_sheet(
+    sheet: AgenticTableSheet,
+    *,
+    include_cells: bool = False,
+) -> str:
+    """Format an Agentic Table sheet summary as a key-value display.
+
+    Sheet-level metadata and cell values are only rendered when the caller
+    requested them (``includeSheetMetadata`` / ``includeCells``); absent
+    sections are skipped rather than shown empty.
+    """
+    rows = [
+        ["Sheet:", sheet.get("name", "?")],
+        ["ID:", sheet.get("sheetId", "?")],
+        ["State:", str(sheet.get("state", "?"))],
+    ]
+    if "magicTableRowCount" in sheet:
+        rows.append(["Rows:", str(sheet.get("magicTableRowCount"))])
+    chat_id = sheet.get("chatId")
+    if chat_id:
+        rows.append(["Chat:", chat_id])
+    rows.append(["Created by:", sheet.get("createdBy", "?")])
+    rows.append(["Created:", _format_date(sheet.get("createdAt"))])
+    lines = _pad_columns(rows)
+
+    metadata = sheet.get("magicTableSheetMetadata") or []
+    if metadata:
+        lines.append("")
+        lines.append("Metadata:")
+        meta_rows = [
+            [f"  {entry.get('key', '?')}:", entry.get("value", "")]
+            for entry in metadata
+        ]
+        lines.extend(_pad_columns(meta_rows))
+
+    cells = sheet.get("magicTableCells") or []
+    if include_cells and cells:
+        lines.append("")
+        lines.append(f"Cells ({len(cells)}):")
+        cell_rows: list[list[str]] = [["ROW", "COL", "TEXT"]]
+        for cell in cells:
+            cell_rows.append(
+                [
+                    str(cell.get("rowOrder", "?")),
+                    str(cell.get("columnOrder", "?")),
+                    _snippet(cell.get("text", "")),
+                ]
+            )
+        lines.extend(_pad_columns(cell_rows))
+
+    return "\n".join(lines)
+
+
+def format_agentic_table_cell(cell: AgenticTableCell) -> str:
+    """Format a single Agentic Table cell (text + lock state)."""
+    rows = [
+        ["Sheet:", cell.get("sheetId", "?")],
+        ["Row:", str(cell.get("rowOrder", "?"))],
+        ["Column:", str(cell.get("columnOrder", "?"))],
+        ["Locked:", "yes" if cell.get("rowLocked") else "no"],
+    ]
+    lines = _pad_columns(rows)
+    lines.append("")
+    lines.append("Text:")
+    lines.append(cell.get("text", ""))
+    return "\n".join(lines)
+
+
+def format_agentic_table_cell_history(cell: AgenticTableCell) -> str:
+    """Format an Agentic Table cell's log/edit history newest-to-oldest.
+
+    Each entry shows its timestamp, actor, optional source message id, and the
+    logged text (the actor + reason recorded by writes). The order is whatever
+    the API returns; no client-side sorting is imposed.
+    """
+    entries = cell.get("logEntries") or []
+    row = cell.get("rowOrder", "?")
+    col = cell.get("columnOrder", "?")
+    plural = "entry" if len(entries) == 1 else "entries"
+    header = f"Cell history (row {row}, col {col}) — {len(entries)} {plural}"
+    if not entries:
+        return f"{header}\n(no log entries)"
+
+    lines = [header, ""]
+    for entry in entries:
+        actor = entry.get("actorType", "?")
+        when = _format_date(entry.get("createdAt"))
+        message_id = entry.get("messageId")
+        suffix = f"  [{message_id}]" if message_id else ""
+        lines.append(f"- {when}  {actor}{suffix}")
+        text = (entry.get("text") or "").strip()
+        for text_line in text.splitlines():
+            lines.append(f"    {text_line}")
+    return "\n".join(lines)
+
+
+def format_agentic_table_artifacts(artifacts: list[MagicTableArtifact]) -> str:
+    """Format a sheet's export artifacts as a table.
+
+    ``contentId`` is only populated once an artifact reaches the ``DONE`` state;
+    pending/in-progress artifacts show ``-`` in the CONTENT column.
+    """
+    if not artifacts:
+        return "No export artifacts found."
+
+    header = ["TYPE", "STATE", "ID", "CONTENT", "UPDATED"]
+    rows: list[list[str]] = [header]
+    for artifact in artifacts:
+        rows.append(
+            [
+                str(artifact.get("artifactType", "?")),
+                str(artifact.get("artifactState", "?")),
+                artifact.get("id", "?"),
+                artifact.get("contentId") or "-",
+                _format_date(artifact.get("updatedAt")),
+            ]
+        )
+
+    lines = [f"{len(artifacts)} export artifact(s):\n"]
+    lines.extend(_pad_columns(rows))
+    return "\n".join(lines)

unique_sdk-2026.32.0.dev2/unique_sdk/cli/skills/unique-cli-agentic-table/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: unique-cli-agentic-table
+description: >-
+  Read Agentic Table (magic table / due-diligence) sheets through the
+  unique-cli agentic-table command. Use when the user or task involves
+  inspecting an Agentic Table: a sheet's state and metadata, a specific
+  cell's value or lock state, a cell's edit/answer history, or the sheet's
+  generated export artifacts (reports, question exports). These are
+  read-only (Tier 0) commands — they never modify the sheet and never
+  require confirmation. Access to each sheet is enforced by the platform;
+  a denial is reported as `agentic-table: permission denied`.
+---
+
+# Unique CLI -- Agentic Table (read)
+
+Inspect Agentic Table (a.k.a. magic table) sheets over the public magic-table
+API. Every command is scoped to the current user/company automatically; you
+never pass credentials. Sheet-role access (Owner / Can manage / Can edit) is
+enforced **server-side** — if you are not entitled to a sheet the command exits
+with `agentic-table: permission denied` rather than returning data.
+
+All commands here are **reads only**. There are no write commands in this skill.
+
+## Commands
+
+### Sheet summary
+
+```bash
+unique-cli agentic-table get-sheet <table_id>
+```
+
+Shows the sheet name, state, and row count. Add flags for more detail:
+
+| Flag | Effect |
+|------|--------|
+| `--metadata` | Include sheet-level metadata entries |
+| `--cells` | Include cell values (row, column, text snippet) |
+| `--json` | Print the raw sheet JSON instead of the formatted view |
+
+```bash
+unique-cli agentic-table get-sheet mt_abc123 --metadata --cells
+```
+
+### Single cell
+
+```bash
+unique-cli agentic-table get-cell <table_id> --row N --col N
+```
+
+Shows one cell's text and lock state. `--row`/`--col` are 0-based orders.
+Add `--json` for the raw cell record.
+
+```bash
+unique-cli agentic-table get-cell mt_abc123 --row 1 --col 2
+```
+
+### Cell history
+
+```bash
+unique-cli agentic-table cell-history <table_id> --row N --col N
+```
+
+Shows a single cell's log/edit history (actor, timestamp, source message id,
+and the logged text) newest-to-oldest as returned by the API. Add `--json`
+to get the raw log entries.
+
+```bash
+unique-cli agentic-table cell-history mt_abc123 --row 1 --col 2
+```
+
+### Export artifacts
+
+```bash
+unique-cli agentic-table list-exports <table_id>
+```
+
+Lists the sheet's generated exports (full report, question export, agentic
+report) with their state. The content id needed to download a file is only
+present once an artifact reaches the `DONE` state. Add `--json` for the raw
+list.
+
+```bash
+unique-cli agentic-table list-exports mt_abc123
+```
+
+## Rules
+
+1. Treat these as read-only diagnostics. To answer a question about a sheet,
+   fetch exactly what you need (`get-cell` for one value, `get-sheet --cells`
+   for an overview) rather than dumping the whole sheet unless asked.
+2. `--row` and `--col` are **0-based** orders. Row 0 is the header row.
+3. A `agentic-table: permission denied` line means the current user cannot
+   access that sheet. Do not retry with different ids to probe access — report
+   the denial and stop.
+4. Use `--json` when you need to parse fields programmatically (e.g. to read a
+   `contentId` before downloading an export); use the default formatted output
+   when summarising for the user.
+
+## Prerequisites
+
+The platform sets these environment variables automatically:
+
+```bash
+UNIQUE_USER_ID
+UNIQUE_COMPANY_ID
+UNIQUE_API_KEY
+UNIQUE_APP_ID
+```
+
+Install: `pip install unique-sdk`

{unique_sdk-2026.32.0.dev0 → unique_sdk-2026.32.0.dev2}/unique_sdk/cli/skills/unique-cli-elicitation/SKILL.md

@@ -52,6 +52,13 @@ default — comfortably under Claude Code's ~120s):
 2. **Poll in short bursts**, each well under your harness's Bash foreground
    timeout:
 
+   **You MUST NOT stop after a single `PENDING` result.** If `elicit wait`
+   returns `PENDING`, immediately call `elicit wait` again (same elicitation
+   id) — as its own new tool call if you are not running the loop below —
+   and keep doing so until you see a terminal status or the elicitation
+   reaches its `--expires-in` deadline. Never tell the user you "stopped
+   waiting" or "gave up" while `PENDING` is the last known status.
+
    ```bash
    status="PENDING"
    elapsed=0