unique-sdk 2026.26.0.dev10__tar.gz → 2026.26.0.dev11__tar.gz

{unique_sdk-2026.26.0.dev10 → unique_sdk-2026.26.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.26.0.dev10
+Version: 2026.26.0.dev11
 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.26.0.dev10 → unique_sdk-2026.26.0.dev11}/pyproject.toml

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

{unique_sdk-2026.26.0.dev10 → unique_sdk-2026.26.0.dev11}/unique_sdk/cli/cli.py

@@ -13,6 +13,7 @@ from unique_sdk.cli.commands.dynamic_frontend import (
     cmd_dynamic_frontend_list,
 )
 from unique_sdk.cli.commands.elicitation import (
+    DEFAULT_WAIT_TIMEOUT_SECONDS,
     cmd_elicit_ask,
     cmd_elicit_create,
     cmd_elicit_get,
@@ -1059,19 +1060,16 @@ def elicit() -> None:
 )
 @click.option("--chat-id", "-c", default=None, help="Associated chat ID.")
 @click.option("--message-id", "-m", default=None, help="Associated message ID.")
-@click.option(
-    "--expires-in",
-    "expires_in_seconds",
-    type=int,
-    default=None,
-    help="Expire the elicitation after N seconds if not answered.",
-)
 @click.option(
     "--timeout",
     type=int,
-    default=300,
+    default=DEFAULT_WAIT_TIMEOUT_SECONDS,
     show_default=True,
-    help="Max seconds to block waiting for the user's response.",
+    help=(
+        "Max seconds to block waiting for the user's response. This also "
+        "sets when the elicitation expires, so the request expires exactly "
+        "when we stop waiting and the chat UI can offer a way to continue."
+    ),
 )
 @click.option(
     "--poll-interval",
@@ -1130,7 +1128,6 @@ def elicit_ask(
     schema: str | None,
     chat_id: str | None,
     message_id: str | None,
-    expires_in_seconds: int | None,
     timeout: int,
     poll_interval: float,
     metadata: tuple[str, ...],
@@ -1167,7 +1164,6 @@ def elicit_ask(
         "schema": schema,
         "chat_id": chat_id,
         "message_id": message_id,
-        "expires_in_seconds": expires_in_seconds,
         "timeout": timeout,
         "poll_interval": poll_interval,
         "metadata": parsed_metadata or None,
@@ -1351,7 +1347,7 @@ def elicit_get(ctx: click.Context, elicitation_id: str) -> None:
 @click.option(
     "--timeout",
     type=int,
-    default=300,
+    default=DEFAULT_WAIT_TIMEOUT_SECONDS,
     show_default=True,
     help="Max seconds to wait for a terminal state.",
 )

{unique_sdk-2026.26.0.dev10 → unique_sdk-2026.26.0.dev11}/unique_sdk/cli/commands/elicitation.py

@@ -26,7 +26,7 @@ from unique_sdk.cli.formatting import (
 from unique_sdk.cli.state import ShellState
 
 DEFAULT_POLL_INTERVAL_SECONDS = 2.0
-DEFAULT_WAIT_TIMEOUT_SECONDS = 300
+DEFAULT_WAIT_TIMEOUT_SECONDS = 7200
 TERMINAL_STATUSES = {
     "RESPONDED",
     "ACCEPTED",
@@ -669,9 +669,27 @@ def cmd_elicit_wait(
                 terminal_status = status
                 return format_elicitation(elicitation)
             if time.monotonic() >= deadline:
+                # One last read on the deadline. When the caller coupled
+                # ``--expires-in`` to ``--timeout`` (the default for
+                # ``elicit ask``), the record's ``expiresAt`` lands at this
+                # same instant; this fetch forces the backend's lazy expiry to
+                # run so we report a clean EXPIRED — and publish it to the chat
+                # subscription — instead of a stale PENDING.
+                final = dict(
+                    unique_sdk.Elicitation.get_elicitation(
+                        user_id=state.config.user_id,
+                        company_id=state.config.company_id,
+                        elicitation_id=elicitation_id,
+                    )
+                )
+                last = final
+                final_status = str(final.get("status", "")).upper()
+                if final_status in TERMINAL_STATUSES:
+                    terminal_status = final_status
+                    return format_elicitation(final)
                 return (
                     f"elicit: timed out after {timeout}s waiting for "
-                    f"{elicitation_id} (last status: {status or 'UNKNOWN'})\n\n"
+                    f"{elicitation_id} (last status: {final_status or 'UNKNOWN'})\n\n"
                     f"{format_elicitation(last)}"
                 )
             time.sleep(poll_interval)
@@ -715,7 +733,6 @@ def cmd_elicit_ask(
     schema: str | None = None,
     chat_id: str | None = None,
     message_id: str | None = None,
-    expires_in_seconds: int | None = None,
     timeout: int = DEFAULT_WAIT_TIMEOUT_SECONDS,
     poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
     metadata: list[tuple[str, str]] | None = None,
@@ -751,6 +768,17 @@ def cmd_elicit_ask(
                 "required": ["answer"],
             }
 
+        # `ask` exposes a single knob: `--timeout` is both how long we wait and
+        # when the record expires. The two are always the same here, so the
+        # backend's default (5 minutes) never leaves the record PENDING after
+        # we have stopped waiting — which would otherwise prevent the chat UI
+        # from flipping the prompt to EXPIRED and offering the user a way to
+        # continue. The poll loop below reads the freshly EXPIRED record and the
+        # elicitation subscription delivers the terminal status to the chat.
+        # (Use `elicit create --expires-in` if you need expiry decoupled from a
+        # local wait.)
+        expires_in_seconds = timeout
+
         user_metadata = _parse_metadata_pairs(metadata)
         effective_message_id = message_id
         placeholder_message_id: str | None = None

{unique_sdk-2026.26.0.dev10 → unique_sdk-2026.26.0.dev11}/unique_sdk/cli/shell.py

@@ -9,6 +9,7 @@ from typing import Any
 
 from unique_sdk.cli import __version__
 from unique_sdk.cli.commands.elicitation import (
+    DEFAULT_WAIT_TIMEOUT_SECONDS,
     cmd_elicit_ask,
     cmd_elicit_create,
     cmd_elicit_get,
@@ -87,8 +88,8 @@ OVERVIEW_HELP = textwrap.dedent("""\
         --schema <json>                JSON schema (default: single 'answer' field)
         --chat-id / -c <id>            Associated chat ID
         --message-id / -m <id>         Associated message ID
-        --expires-in <seconds>         Auto-expire the request
-        --timeout <seconds>            Max wait time (default: 300)
+        --timeout <seconds>            Max wait time, also sets when the
+                                       request expires (default: 7200)
         --poll-interval <seconds>      Poll frequency (default: 2.0)
         --metadata key=value           Metadata (repeatable)
         --no-visible                   Skip the UN-19815 visibility workaround
@@ -112,7 +113,7 @@ OVERVIEW_HELP = textwrap.dedent("""\
       elicit pending                 List pending elicitations
       elicit get <id>                Show one elicitation
       elicit wait <id> [opts]        Poll until answered / expired
-        --timeout <seconds>            Max wait (default: 300)
+        --timeout <seconds>            Max wait (default: 7200)
         --poll-interval <seconds>      Poll frequency (default: 2.0)
       elicit respond <id> [opts]     Respond on behalf of the user
         --action ACCEPT|DECLINE|CANCEL|REJECT Response action (required)
@@ -788,8 +789,9 @@ class UniqueShell(cmd.Cmd):
           --mode FORM|URL              Display mode (create only, required)
           --chat-id / -c <id>          Associated chat ID
           --message-id / -m <id>       Associated message ID
-          --expires-in <seconds>       Auto-expire the request
-          --timeout <seconds>          (ask / wait) max wait time, default 300
+          --expires-in <seconds>       Auto-expire the request (create only)
+          --timeout <seconds>          (ask / wait) max wait time, default 7200;
+                                       for ask this also sets when it expires
           --poll-interval <seconds>    (ask / wait) poll frequency, default 2
           --external-id <id>           External identifier (create only)
           --metadata key=value         Metadata (repeatable)
@@ -863,7 +865,7 @@ class UniqueShell(cmd.Cmd):
             "message_id": None,
             "expires_in_seconds": None,
             "external_elicitation_id": None,
-            "timeout": 300,
+            "timeout": DEFAULT_WAIT_TIMEOUT_SECONDS,
             "poll_interval": 2.0,
             "action": None,
             "content": None,
@@ -972,6 +974,13 @@ class UniqueShell(cmd.Cmd):
         if not message:
             self._print("Usage: elicit ask <message> [options]")
             return
+        if opts["expires_in_seconds"] is not None:
+            self._print(
+                "No such option: --expires-in for 'elicit ask'. Use --timeout "
+                "(it also sets when the request expires). For expiry decoupled "
+                "from a local wait, use 'elicit create --expires-in'."
+            )
+            return
 
         ask_kwargs: dict[str, Any] = {
             "message": message,
@@ -979,7 +988,6 @@ class UniqueShell(cmd.Cmd):
             "schema": opts["schema"],
             "chat_id": opts["chat_id"],
             "message_id": opts["message_id"],
-            "expires_in_seconds": opts["expires_in_seconds"],
             "timeout": opts["timeout"],
             "poll_interval": opts["poll_interval"],
             "metadata": opts["metadata"] or None,

{unique_sdk-2026.26.0.dev10 → unique_sdk-2026.26.0.dev11}/unique_sdk/cli/skills/unique-cli-elicitation/SKILL.md

@@ -133,8 +133,7 @@ unique-cli elicit ask "Please provide report settings" \
 | `--message-id` | `-m` | none | **MANDATORY.** The current assistant message ID. Always pass `"$UNIQUE_MESSAGE_ID"`. Anchors the elicitation to the correct message in the conversation thread. |
 | `--tool-name` | `-t` | `agent_question` | Short snake_case label shown to the user (e.g. `clarify`, `confirm_delete`, `choose_report`). |
 | `--schema` | | single `answer` string | JSON Schema for the form body. |
-| `--expires-in` | | none | Seconds before the request auto-expires on the platform. |
-| `--timeout` | | `300` | Max seconds to block locally before giving up. |
+| `--timeout` | | `7200` | Max seconds to block locally before giving up. This is the single knob for `ask`: it also sets when the request expires on the platform, so the prompt expires exactly when you stop waiting and the chat UI can offer the user a way to continue. |
 | `--poll-interval` | | `2.0` | Seconds between status polls. |
 | `--metadata` | | none | `key=value` metadata (repeatable). |
 | `--assistant-id` | | `$UNIQUE_ASSISTANT_ID`, else latest assistant in chat | Assistant id for the placeholder message created by the visibility workaround. Set this (or export `UNIQUE_ASSISTANT_ID`) only if the chat is brand-new with no prior assistant messages. |
@@ -159,9 +158,34 @@ Terminal statuses:
 | `RESPONDED` / `COMPLETED` | User answered | Parse `Response:` JSON and proceed. |
 | `DECLINED` | User explicitly declined | Do not proceed. Acknowledge and stop. |
 | `CANCELLED` | Cancelled (by user or system) | Do not proceed. |
-| `EXPIRED` | Timed out on the platform (via `--expires-in`) | Ask again only if the task still needs it. |
+| `EXPIRED` | Timed out on the platform — the user did not answer within `--timeout` | Ask again only if the task still needs it; do not treat the expiry as approval. |
 
-If the CLI itself times out locally (`elicit: timed out after Ns ...`), raise `--timeout` and try again. If this happens repeatedly, double-check that you passed `--chat-id` and did not pass `--no-visible` — an invisible elicitation is the most common cause of a local timeout.
+Because `ask` derives the request's expiry from `--timeout`, when the user does not answer in time the platform expires the request and `elicit ask` returns a clean `EXPIRED` status (rather than a local-only timeout). If you instead see `elicit: timed out after Ns ...`, raise `--timeout` and try again. If this happens repeatedly, double-check that you passed `--chat-id` and did not pass `--no-visible` — an invisible elicitation is the most common cause of a local timeout.
+
+### Repeat the answer back in chat
+
+After a `RESPONDED` / `COMPLETED` elicitation, always repeat the user's answer back in the normal chat before you continue. This keeps the decision in the chat history and makes it clear what the user said.
+
+Write this as a user-readable summary, not as raw JSON. Use the field descriptions and option labels from the schema to translate the response into plain language:
+
+```markdown
+Got it — you chose Markdown for the report format and asked me to include the appendix.
+```
+
+If the exact structured response is useful for auditing or debugging, put it behind a collapsed details block after the readable summary instead of leading with it:
+
+````markdown
+<details>
+<summary>Structured elicitation response</summary>
+
+```json
+{"format":"Markdown","include_appendix":true}
+```
+
+</details>
+````
+
+Do not expose raw JSON by default when a natural-language confirmation would be clearer.
 
 ## Scripting pattern
 
@@ -192,7 +216,7 @@ esac
 - Use `enum` for closed choices so the UI can render a selector.
 - Use `"type": "boolean"` for confirmations; treat `true` as "go ahead", everything else as "stop".
 - Add short `description` strings -- they are shown as help text next to each field.
-- Keep schemas small. Break long flows into several sequential `elicit ask` calls instead of one giant form.
+- Keep schemas small. Ask at most 5 questions in a single elicitation; if you need more, split the flow so the user is not confused by an oversized form.
 
 ## Agent workflow rules
 
@@ -203,9 +227,11 @@ esac
 5. **Never run destructive CLI commands without a confirmation elicitation.** This includes `rm`, `rmdir -r`, bulk renames, large uploads, schedule deletion, etc.
 6. **Pick a meaningful `--tool-name`.** `confirm_delete`, `choose_region`, `pick_report` -- short snake_case describing the intent.
 7. **Constrain answers with a schema** whenever the valid set is finite -- don't rely on parsing free text when `enum` is an option.
-8. **Handle non-`RESPONDED` outcomes explicitly.** If the status is `DECLINED` / `CANCELLED` / `EXPIRED`, tell the user you stopped and ask what they want to do next instead of silently proceeding.
-9. **Don't spam elicitations.** One well-designed form with several fields is better than five sequential yes/no questions.
-10. **Respect timeouts.** The default `--timeout` is 5 minutes -- raise it only if you genuinely expect the user to take longer.
+8. **Repeat answered elicitations back in chat.** Summarize what the user chose in natural language before acting on it; hide raw JSON in a collapsible details block only when it adds value.
+9. **Handle non-`RESPONDED` outcomes explicitly.** If the status is `DECLINED` / `CANCELLED` / `EXPIRED`, tell the user you stopped and ask what they want to do next instead of silently proceeding.
+10. **Don't spam elicitations.** One well-designed form with a few related fields is better than five sequential yes/no questions.
+11. **Cap each elicitation at 5 questions.** If you need more than 5 answers, split them into multiple focused elicitations so the user can respond confidently.
+12. **Respect timeouts.** The default `--timeout` is 2 hours -- override it only when the task needs a shorter or longer wait.
 
 ## Prerequisites