devops-bot-sdk 1.6.57__tar.gz → 1.6.60__tar.gz

{devops_bot_sdk-1.6.57 → devops_bot_sdk-1.6.60}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.57
+Version: 1.6.60
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.57 → devops_bot_sdk-1.6.60}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.57
+Version: 1.6.60
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.57 → devops_bot_sdk-1.6.60}/devops_bot_sdk.egg-info/SOURCES.txt

@@ -47,6 +47,7 @@ sdk/task_types.py
 sdk/test.py
 sdk/test_pipeline.py
 sdk/ticket_fields.py
+sdk/tickets.py
 sdk/updater.py
 sdk/url_access.py
 sdk/vps_health.py
@@ -207,6 +208,7 @@ tests/test_stale_panel_restart.py
 tests/test_swagger_command.py
 tests/test_task_file_and_plan_run.py
 tests/test_task_file_format_doc.py
+tests/test_ticket_cli.py
 tests/test_ticket_fields.py
 tests/test_ticket_run_resolve_by_id.py
 tests/test_ticket_speed_fixes.py

{devops_bot_sdk-1.6.57 → devops_bot_sdk-1.6.60}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.6.52
+Version: 1.6.60
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -34,7 +34,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.6.57"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
+__version__ = "1.6.60"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
 __author__  = "AgentOS"   # sdk.client.SDK_VERSION and the UI server version all read this.
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.6.57 → devops_bot_sdk-1.6.60}/sdk/cli.py

@@ -49,6 +49,21 @@ Command surface:
     agentos agent rm <name>
         De-register the agent from the backend and delete its local manifest.
 
+    agentos ticket create --project KEY --summary TEXT [--type T] [--priority P]
+            [--assignee EMAIL] [--description[-file] …] [--instructions[-file] …]
+            [--parent ID] [--status S] [--points N]
+        File one ticket (POST /tasks-ml) and print its Jira key. Type defaults to
+        Task, priority to Medium, assignee to the token owner. Validated locally
+        first; a gateway rejection prints the gateway's own messages.
+    agentos ticket update KEY_OR_ID [--summary …] [--description[-file] …]
+            [--instructions[-file] …] [--priority P] [--status S] [--points N]
+            [--assignee EMAIL] [--type T]
+        Change only the given fields (PUT /tasks-ml/{id}). Takes a Jira key or
+        the platform id. See sdk.tickets — the Tickets page uses the same code.
+    agentos ticket delete KEY_OR_ID [--yes]
+        Show the ticket and, after a y/N confirmation (skipped by --yes), delete it
+        (DELETE /tasks-ml/{id}). Cannot be undone.
+
     agentos integration add <path>
         Register an integration (MCP server, etc.) from a JSON file.
     agentos integration test <name>
@@ -162,6 +177,10 @@ def main() -> None:
         _integration_command(rest)
         return
 
+    if noun == "ticket":
+        _ticket_command(rest)
+        return
+
     if noun == "agentd":
         _agentd_command(rest)
         return
@@ -202,12 +221,13 @@ def main() -> None:
 
 
 def _print_usage() -> None:
-    print("usage: agentos <configure|chat|agent|integration|default-agents|agentd|github|report|browser|fallback|firewall|activity-setup|swagger> ...")
+    print("usage: agentos <configure|chat|agent|ticket|integration|default-agents|agentd|github|report|browser|fallback|firewall|activity-setup|swagger> ...")
     print()
     print("  agentos configure [--rotate]")
     print("  agentos chat [--product-id ID] [--pv-id ID] [--no-autorun]   # requirements → ticket")
     print("  agentos agent <list|run NAME|chat NAME MSG|logs NAME|enable NAME|disable NAME|rm NAME>")
     print("  agentos agent <set-key NAME KEY[=VALUE]…|keys NAME|rm-key NAME KEY…>   # persistent API keys (custom agents)")
+    print("  agentos ticket <create|update KEY_OR_ID|delete KEY_OR_ID|help>")
     print("  agentos integration <add PATH|test NAME|list|rm NAME>")
     print("  agentos default-agents list [--department-id UUID]   # read-only; agents are created in the web app")
     print("  agentos agentd <start [--foreground]|status>")
@@ -625,6 +645,153 @@ def _pop_department_id(args: list[str]) -> tuple[str | None, list[str]]:
     return dept_id, out
 
 
+# `agentos ticket` flag → POST/PUT /tasks-ml wire name. Text flags have a
+# `-file` twin that reads the value from a file instead.
+_TICKET_FLAGS = {
+    "--project": "projectKey", "--type": "type", "--summary": "summary",
+    "--priority": "priority", "--assignee": "assigneeEmail", "--status": "status",
+    "--points": "points", "--parent": "parentTaskId",
+    "--description": "description", "--instructions": "humanInstructions",
+}
+_TICKET_FILE_FLAGS = {"--description-file": "--description",
+                      "--instructions-file": "--instructions"}
+# Create-only: neither is editable through PUT /tasks-ml/{id}.
+_TICKET_CREATE_ONLY = {"--project", "--parent"}
+
+
+def _ticket_usage() -> None:
+    print("usage: agentos ticket <create|update KEY_OR_ID|delete KEY_OR_ID|help>")
+    print()
+    print("  agentos ticket create --project KEY --summary TEXT [--type TYPE] [--priority P]")
+    print("      [--assignee EMAIL] [--description TEXT | --description-file PATH]")
+    print("      [--instructions TEXT | --instructions-file PATH] [--parent ID] [--status S] [--points N]")
+    print("  agentos ticket update KEY_OR_ID [--summary TEXT] [--description TEXT | --description-file PATH]")
+    print("      [--instructions TEXT | --instructions-file PATH] [--priority P] [--status S]")
+    print("      [--points N] [--assignee EMAIL] [--type TYPE]")
+    print("  agentos ticket delete KEY_OR_ID [--yes]   # asks to confirm unless --yes")
+    print()
+    print("  TYPE: Epic|Story|Task|Bug|Sub-task (default Task)   P: Lowest|Low|Medium|High|Highest (default Medium)")
+    print("  --assignee defaults to the configured token's owner.")
+
+
+def _parse_ticket_flags(args: list[str], *, creating: bool) -> dict[str, str]:
+    """Flags → wire fields. Exits 1 on an unknown flag, a missing value, both a
+    text flag and its -file twin, or an unreadable file."""
+    fields: dict[str, str] = {}
+    seen: set[str] = set()
+    i = 0
+    while i < len(args):
+        flag = args[i]
+        known = flag in _TICKET_FLAGS or flag in _TICKET_FILE_FLAGS
+        if not known or (not creating and flag in _TICKET_CREATE_ONLY):
+            print(f"error: unknown option for `agentos ticket {'create' if creating else 'update'}`: {flag}")
+            sys.exit(1)
+        if i + 1 >= len(args):
+            print(f"error: expected a value after {flag}")
+            sys.exit(1)
+        value = args[i + 1]
+        text_flag = _TICKET_FILE_FLAGS.get(flag, flag)
+        if text_flag in seen:
+            print(f"error: pass {text_flag} or {text_flag}-file once, not both")
+            sys.exit(1)
+        seen.add(text_flag)
+        if flag in _TICKET_FILE_FLAGS:
+            path = Path(value).expanduser()
+            try:
+                value = path.read_text(encoding="utf-8")
+            except OSError as exc:
+                print(f"error: {flag}: cannot read {path}: {exc.strerror or exc}")
+                sys.exit(1)
+        fields[_TICKET_FLAGS[text_flag]] = value
+        i += 2
+    return fields
+
+
+def _ticket_command(args: list[str]) -> None:
+    """`agentos ticket create|update` — see sdk.tickets for the rules."""
+    verb = args[0] if args else "help"
+    if verb in {"help", "-h", "--help"}:
+        _ticket_usage()
+        sys.exit(0 if args else 1)
+    if verb not in {"create", "update", "delete"}:
+        _ticket_usage()
+        sys.exit(1)
+    if verb in {"update", "delete"} and (len(args) < 2 or args[1].startswith("--")):
+        _ticket_usage()
+        sys.exit(1)
+
+    from sdk import tickets
+    from sdk.client import BackendClient
+
+    if verb == "delete":
+        _ticket_delete(args[1], args[2:])
+        return
+
+    if verb == "create":
+        fields = _parse_ticket_flags(args[1:], creating=True)
+        if not fields.get("projectKey") or not fields.get("summary"):
+            print("error: --project and --summary are required")
+            sys.exit(1)
+    else:
+        fields = _parse_ticket_flags(args[2:], creating=False)
+        if not fields:
+            print("error: nothing to update: pass at least one field")
+            _ticket_usage()
+            sys.exit(1)
+    # Validate before building a client, so a bad flag never needs a token.
+    err = tickets.validate_fields(fields)
+    if err:
+        print(f"error: {err}")
+        sys.exit(1)
+
+    client = BackendClient.from_config()
+    if verb == "create":
+        res = asyncio.run(tickets.create_ticket(client, fields))
+    else:
+        res = asyncio.run(tickets.update_ticket(client, args[1], fields))
+    if not res["ok"]:
+        print(f"error: {res['error']}")
+        sys.exit(1)
+    label = res["key"] or res["id"]
+    if verb == "create":
+        print(f"created {label}  (id {res['id']})")
+    else:
+        print(f"updated {label}: {', '.join(sorted(fields))}")
+    sys.exit(0)
+
+
+def _ticket_delete(target: str, flags: list[str]) -> None:
+    """`agentos ticket delete KEY_OR_ID [--yes]` — shows the ticket, then asks."""
+    from sdk import tickets
+    from sdk.client import BackendClient
+
+    unknown = [f for f in flags if f not in {"--yes", "-y"}]
+    if unknown:
+        print(f"error: unknown option for `agentos ticket delete`: {unknown[0]}")
+        sys.exit(1)
+    client = BackendClient.from_config()
+    rec = asyncio.run(tickets.get_ticket(client, target))
+    if rec is None:
+        print(f"error: ticket not found: {target}")
+        sys.exit(1)
+    label = rec.get("key") or rec.get("id")
+    if not flags:
+        print(f"{label}  [{rec.get('status') or '?'}]  {rec.get('summary') or ''}")
+        try:
+            answer = input(f"Delete {label}? This cannot be undone. [y/N] ")
+        except EOFError:
+            answer = ""
+        if answer.strip().lower() not in {"y", "yes"}:
+            print("not deleted")
+            sys.exit(1)
+    res = asyncio.run(tickets.delete_ticket(client, str(rec.get("id") or target)))
+    if not res["ok"]:
+        print(f"error: {res['error']}")
+        sys.exit(1)
+    print(f"deleted {label}")
+    sys.exit(0)
+
+
 def _resolve_department_id(explicit: str | None) -> str:
     """Use the explicit --department-id, else the caller's own from bootstrap()."""
     if explicit:

{devops_bot_sdk-1.6.57 → devops_bot_sdk-1.6.60}/sdk/client.py

@@ -249,6 +249,7 @@ class BackendClient:
         # busy backend (retry in 30 min) from a rejected request (wait for the
         # next slot). Empty dict means "no failure recorded".
         self.last_ingest_error: dict = {}
+        self.last_task_ml_error: dict = {}
         self._headers  = {
             "Authorization": token,          # co_<uuid>_<hex> — no Bearer prefix
             "X-SDK-Version": SDK_VERSION,
@@ -1274,6 +1275,48 @@ class BackendClient:
             logger.warning("client.get_task_status list failed task=%s err=%s", task_id, exc)
         return None
 
+    async def get_task_ml(self, task_id: str) -> dict | None:
+        """GET {BE}/tasks-ml/{id} → the full RAW record (jiraIssueKey, summary, …), or None.
+
+        Same read as ``get_task_status`` — direct single-record read, then a scan
+        of the list endpoint for a backend that doesn't serve it — but returns the
+        whole record. Matches `id` or the Jira key. Best-effort: never raises.
+        """
+        from sdk.config import BE_DEFAULT_URL
+
+        if not task_id:
+            return None
+        base = BE_DEFAULT_URL.rstrip("/")
+        headers = {**self._headers, "accept": "*/*", "developer-name": "null", "product": ""}
+        try:
+            async with httpx.AsyncClient(timeout=20.0) as client:
+                resp = await client.get(f"{base}/tasks-ml/{task_id}", headers=headers)
+            if resp.status_code < 400:
+                data = (resp.json() or {}).get("data") or {}
+                if isinstance(data, dict):
+                    rec = data.get("record") if isinstance(data.get("record"), dict) else data
+                    if rec.get("id"):
+                        return rec
+        except Exception as exc:  # noqa: BLE001 — fall through to the list scan
+            logger.warning("client.get_task_ml direct failed task=%s err=%s", task_id, exc)
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                resp = await client.get(f"{base}/tasks-ml", params={"limit": 10000},
+                                        headers=headers)
+            if resp.status_code >= 400:
+                return None
+            records = ((resp.json() or {}).get("data") or {}).get("records") or []
+            want = str(task_id).strip().upper()
+            for rec in records:
+                if isinstance(rec, dict) and want in {
+                    str(rec.get(k) or "").strip().upper()
+                    for k in ("id", "jiraIssueKey", "jiraKey")
+                }:
+                    return rec
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("client.get_task_ml list failed task=%s err=%s", task_id, exc)
+        return None
+
     async def set_task_status(self, task_id: str, status: str) -> bool:
         """PUT {BE}/tasks-ml/{id} status=<status> (best-effort, arbitrary target).
 
@@ -1435,11 +1478,17 @@ class BackendClient:
             async with httpx.AsyncClient(timeout=30.0) as client:
                 resp = await client.put(url, files=files, headers=headers)
             if resp.status_code >= 400:
+                try:
+                    self.last_task_ml_error = resp.json() or {}
+                except Exception:  # noqa: BLE001
+                    self.last_task_ml_error = {"error": resp.text or "request failed"}
                 logger.warning("client.update_task_ml failed task=%s status=%s body=%s",
                                task_id, resp.status_code, resp.text[:200])
                 return False
+            self.last_task_ml_error = {}
             return True
         except Exception as exc:  # noqa: BLE001
+            self.last_task_ml_error = {"error": str(exc)}
             logger.warning("client.update_task_ml error task=%s err=%s", task_id, exc)
             return False
 
@@ -1458,6 +1507,7 @@ class BackendClient:
         from sdk.config import BE_DEFAULT_URL
         from sdk.ticket_fields import to_multipart
 
+        self.last_task_ml_error = {}
         url = f"{BE_DEFAULT_URL.rstrip('/')}/tasks-ml"
         headers = {k: v for k, v in self._headers.items() if k.lower() != "content-type"}
         headers.update({"accept": "*/*", "developer-name": "null", "product": ""})
@@ -1468,9 +1518,14 @@ class BackendClient:
             async with httpx.AsyncClient(timeout=30.0) as client:
                 resp = await client.post(url, files=files, headers=headers)
             if resp.status_code >= 400:
+                try:
+                    self.last_task_ml_error = resp.json() or {}
+                except Exception:  # noqa: BLE001
+                    self.last_task_ml_error = {"error": resp.text or "request failed"}
                 logger.warning("client.create_task_ml failed status=%s body=%s",
                                resp.status_code, resp.text[:300])
                 return None
+            self.last_task_ml_error = {}
             body = resp.json() or {}
             rec = body.get("data") or body
             # The created record's id may sit at data.id or data.record.id.
@@ -1478,9 +1533,39 @@ class BackendClient:
                 return rec.get("id") or ((rec.get("record") or {}).get("id"))
             return None
         except Exception as exc:  # noqa: BLE001
+            self.last_task_ml_error = {"error": str(exc)}
             logger.warning("client.create_task_ml error err=%s", exc)
             return None
 
+    async def delete_task_ml(self, task_id: str) -> bool:
+        """DELETE {BE}/tasks-ml/{id} — remove a ticket. True on 2xx.
+
+        On failure the gateway's JSON body (e.g. ``{"message": "Task not found"}``)
+        is kept in ``last_task_ml_error``, as for create/update. Never raises.
+        """
+        from sdk.config import BE_DEFAULT_URL
+
+        url = f"{BE_DEFAULT_URL.rstrip('/')}/tasks-ml/{task_id}"
+        headers = {k: v for k, v in self._headers.items() if k.lower() != "content-type"}
+        headers.update({"accept": "*/*", "developer-name": "null", "product": ""})
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                resp = await client.delete(url, headers=headers)
+            if resp.status_code >= 400:
+                try:
+                    self.last_task_ml_error = resp.json() or {}
+                except Exception:  # noqa: BLE001
+                    self.last_task_ml_error = {"error": resp.text or "request failed"}
+                logger.warning("client.delete_task_ml failed task=%s status=%s body=%s",
+                               task_id, resp.status_code, resp.text[:200])
+                return False
+            self.last_task_ml_error = {}
+            return True
+        except Exception as exc:  # noqa: BLE001
+            self.last_task_ml_error = {"error": str(exc)}
+            logger.warning("client.delete_task_ml error task=%s err=%s", task_id, exc)
+            return False
+
     # ── Jira projects ──────────────────────────────────────────────────
     # A Jira project is the container a ticket's `projectKey` points at, so these
     # sit next to create_task_ml: a flow that has no projectKey yet resolves one

{devops_bot_sdk-1.6.57 → devops_bot_sdk-1.6.60}/sdk/ticket_fields.py

@@ -23,6 +23,10 @@ from __future__ import annotations
 MultipartPart = tuple[str, tuple[None, str]]
 MultipartBody = list[MultipartPart]
 
+VALID_TICKET_TYPES = frozenset({"Epic", "Story", "Task", "Bug", "Sub-task"})
+VALID_PRIORITIES = frozenset({"Lowest", "Low", "Medium", "High", "Highest"})
+MAX_SUMMARY_LENGTH = 255
+
 # The field names the SDK sends to POST /tasks-ml, from the real call sites in
 # sdk/ipc/handlers.py (_epic_inherited_fields, and the child-story `fields` dict
 # in the Epic decomposition loop). Documentation and an assertion target for
@@ -90,6 +94,46 @@ def is_sla_field(key: str) -> bool:
     return _normalise(key) in SLA_FIELDS
 
 
+def validate_ticket_type(value: str) -> str | None:
+    """Return an error string when `value` is not an allowed ticket type."""
+    if value in VALID_TICKET_TYPES:
+        return None
+    return (
+        "invalid type: "
+        f"{value!r}. Expected one of: {', '.join(sorted(VALID_TICKET_TYPES))}"
+    )
+
+
+def validate_priority(value: str) -> str | None:
+    """Return an error string when `value` is not an allowed priority."""
+    if value in VALID_PRIORITIES:
+        return None
+    return (
+        "invalid priority: "
+        f"{value!r}. Expected one of: {', '.join(sorted(VALID_PRIORITIES))}"
+    )
+
+
+def validate_email(value: str) -> str | None:
+    """Return an error string when `value` is not shaped like an email."""
+    text = str(value or "").strip()
+    if text and "@" in text and not text.startswith("@") and not text.endswith("@"):
+        local, _, domain = text.partition("@")
+        if local and domain and "." in domain and not domain.startswith(".") and not domain.endswith("."):
+            return None
+    return f"invalid assignee email: {value!r}"
+
+
+def validate_summary_length(value: str) -> str | None:
+    """Return an error string when `summary` exceeds the backend limit."""
+    if len(value) <= MAX_SUMMARY_LENGTH:
+        return None
+    return (
+        f"summary must be {MAX_SUMMARY_LENGTH} characters or fewer "
+        f"(got {len(value)})"
+    )
+
+
 def to_multipart(
     fields: dict[str, object],
     model_used: list[str] | None = None,
@@ -141,9 +185,16 @@ def to_multipart(
 # The field contract itself. The MultipartPart/MultipartBody aliases above are
 # importable annotation helpers, not part of the contract, so they stay out.
 __all__ = [
+    "MAX_SUMMARY_LENGTH",
     "OMITTED_FIELDS",
     "SLA_FIELDS",
     "TASKS_ML_FIELDS",
+    "VALID_PRIORITIES",
+    "VALID_TICKET_TYPES",
     "is_sla_field",
     "to_multipart",
+    "validate_email",
+    "validate_priority",
+    "validate_summary_length",
+    "validate_ticket_type",
 ]

devops_bot_sdk-1.6.60/sdk/tickets.py

@@ -0,0 +1,177 @@
+"""Create, edit and delete tickets — the one implementation behind `agentos ticket` and
+the control panel's Tickets page.
+
+Both front ends gather the same flags/fields, so the rules live here once:
+validation against the gateway's POST /tasks-ml contract (``sdk.ticket_fields``),
+the assignee default (the token owner's email), Jira-key → platform-id
+resolution, and reading the created ticket's Jira key back. Every function
+returns a result dict instead of printing or raising, so the CLI can print it
+and the HTTP layer can turn it into a status code.
+
+Result shape: ``{"ok": bool, "id": str, "key": str, "error": str}``, plus
+``"details"`` (the gateway's JSON error body) when the backend rejected the call.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from sdk.ticket_fields import (
+    validate_email,
+    validate_priority,
+    validate_summary_length,
+    validate_ticket_type,
+)
+
+# PROJ-123. A platform id is a UUID, which also contains dashes, so "has a dash"
+# is not enough to tell the two apart.
+_JIRA_KEY_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]*-\d+$")
+
+# Editable fields, by wire name. `None` drops a field; anything else is sent.
+EDITABLE_FIELDS = (
+    "summary", "description", "humanInstructions", "priority", "status",
+    "points", "assigneeEmail", "type",
+)
+
+
+def is_jira_key(value: str) -> bool:
+    return bool(_JIRA_KEY_RE.match(str(value or "").strip()))
+
+
+def _fail(error: str, **extra: Any) -> dict:
+    return {"ok": False, "id": "", "key": "", "error": error, **extra}
+
+
+def validate_fields(fields: dict[str, Any]) -> str | None:
+    """The first validation error in `fields` (only the fields present), or None."""
+    if fields.get("summary") is not None:
+        if not str(fields["summary"]).strip():
+            return "summary must not be empty"
+        err = validate_summary_length(str(fields["summary"]))
+        if err:
+            return err
+    if fields.get("type") is not None and (err := validate_ticket_type(str(fields["type"]))):
+        return err
+    if fields.get("priority") is not None and (err := validate_priority(str(fields["priority"]))):
+        return err
+    if fields.get("assigneeEmail") is not None and (err := validate_email(str(fields["assigneeEmail"]))):
+        return err
+    if fields.get("projectKey") is not None and len(str(fields["projectKey"])) > 50:
+        return "project key must be 50 characters or fewer"
+    points = fields.get("points")
+    if points is not None and str(points).strip() != "":
+        try:
+            if int(str(points)) < 0:
+                raise ValueError
+        except ValueError:
+            return f"points must be a whole number of 0 or more (got {points!r})"
+    return None
+
+
+async def owner_email(client) -> str:
+    """The configured token owner's email, or "" when it can't be read."""
+    try:
+        return str((await client.profile()).email or "").strip()
+    except Exception:  # noqa: BLE001
+        return ""
+
+
+async def resolve_id(client, key_or_id: str) -> str | None:
+    """Platform task id for a Jira key (AP2-123) or an id; None when not found."""
+    target = str(key_or_id or "").strip()
+    if not target:
+        return None
+    if not is_jira_key(target):
+        return target
+    rows = await client.list_tasks_by_keys([target])
+    if not rows:
+        return None
+    return str(rows[0].get("id") or "") or None
+
+
+async def create_ticket(client, fields: dict[str, Any]) -> dict:
+    """POST /tasks-ml. `fields` uses wire names; type/priority default to Task/Medium
+    and assigneeEmail to the token owner. Validates before any HTTP call."""
+    body = {k: v for k, v in fields.items() if v is not None and v != ""}
+    body.setdefault("type", "Task")
+    body.setdefault("priority", "Medium")
+    if not str(body.get("projectKey") or "").strip():
+        return _fail("project is required")
+    if not str(body.get("summary") or "").strip():
+        return _fail("summary is required")
+    err = validate_fields(body)
+    if err:
+        return _fail(err)
+    if not body.get("assigneeEmail"):
+        email = await owner_email(client)
+        if not email:
+            return _fail("assignee is required: the token owner's email could not be read")
+        body["assigneeEmail"] = email
+
+    task_id = await client.create_task_ml(body)
+    if not task_id:
+        details = getattr(client, "last_task_ml_error", None) or {}
+        return _fail(_error_text(details) or "ticket create failed", details=details)
+    record = await client.get_task_ml(task_id) or {}
+    return {"ok": True, "id": str(task_id), "key": str(record.get("jiraIssueKey") or ""),
+            "error": ""}
+
+
+async def update_ticket(client, key_or_id: str, fields: dict[str, Any]) -> dict:
+    """PUT /tasks-ml/{id} with only the given fields. Validates before any HTTP call."""
+    body = {k: v for k, v in fields.items() if k in EDITABLE_FIELDS and v is not None}
+    if not body:
+        return _fail("nothing to update: pass at least one field")
+    err = validate_fields(body)
+    if err:
+        return _fail(err)
+    task_id = await resolve_id(client, key_or_id)
+    if not task_id:
+        return _fail(f"ticket not found: {key_or_id}")
+    ok = await client.update_task_ml(task_id, body)
+    if not ok:
+        details = getattr(client, "last_task_ml_error", None) or {}
+        return _fail(_error_text(details) or "ticket update failed", details=details)
+    return {"ok": True, "id": task_id,
+            "key": key_or_id if is_jira_key(key_or_id) else "", "error": ""}
+
+
+async def delete_ticket(client, key_or_id: str) -> dict:
+    """DELETE /tasks-ml/{id}. Irreversible — callers confirm with the person first."""
+    task_id = await resolve_id(client, key_or_id)
+    if not task_id:
+        return _fail(f"ticket not found: {key_or_id}")
+    if not await client.delete_task_ml(task_id):
+        details = getattr(client, "last_task_ml_error", None) or {}
+        error = _error_text(details) or "ticket delete failed"
+        if error.lower() == "task not found":
+            error = f"ticket not found: {key_or_id}"
+        return _fail(error, details=details)
+    return {"ok": True, "id": task_id,
+            "key": key_or_id if is_jira_key(key_or_id) else "", "error": ""}
+
+
+async def get_ticket(client, key_or_id: str) -> dict | None:
+    """The editable view of one ticket, or None when it can't be found."""
+    task_id = await resolve_id(client, key_or_id)
+    record = await client.get_task_ml(task_id) if task_id else None
+    if not record:
+        return None
+    out = {k: record.get(k) for k in EDITABLE_FIELDS if k != "assigneeEmail"}
+    out.update({"id": record.get("id") or task_id,
+                "key": record.get("jiraIssueKey") or record.get("jiraKey") or "",
+                "projectKey": record.get("projectKey") or ""})
+    return out
+
+
+def _error_text(details: Any) -> str:
+    """One line from the gateway's error body: `{"message": [...]}` / `{"errors": ...}`."""
+    if not isinstance(details, dict):
+        return str(details or "")
+    for key in ("message", "errors", "error", "detail"):
+        val = details.get(key)
+        if isinstance(val, list) and val:
+            return "; ".join(str(v) for v in val)
+        if val:
+            return str(val)
+    return ""