alissa-tools-github-orcloop 0.3.6__tar.gz → 0.3.8__tar.gz

{alissa_tools_github_orcloop-0.3.6/src/main/alissa_tools_github_orcloop.egg-info → alissa_tools_github_orcloop-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-orcloop
-Version: 0.3.6
+Version: 0.3.8
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_orcloop-0.3.6 → alissa_tools_github_orcloop-0.3.8}/src/main/alissa/tools/github/orcloop/alissa_client.py

@@ -127,6 +127,37 @@ would then hold a task whose only dependency is fully validated -- forever,
 eventually paging ``release-blocked``. Deduplicating matches what the resolved
 view actually does.
 
+TASK CONTEXT ATTACHMENTS (O14)
+==============================
+An operator's decisions about a task do not all fit in the description that was
+written before the work started. Alissa's answer is the task's **context
+attachments** -- ``GET /v1/tasks/<ref>/context`` -> ``{"context": [...]}`` --
+and O14 makes them travel: orcloop renders them into the issue it files, so a
+decision recorded after authoring reaches the implementing worker (repo issue
+#34). Verified live against ``api.alissa.app``:
+
+* Each row carries ``_id``, ``title``, ``createdAt`` (ms), ``actorId``/
+  ``authorName``, and then AT MOST ONE payload of ``markdownContent`` /
+  ``link`` / a vault reference, plus an optional one-line ``note``. The
+  OpenAPI schema pins only ``_id`` and ``title`` (everything else is
+  ``additionalProperties``), so `get_task_context` treats every payload field
+  as optional and an item with none of them still renders as a titled,
+  empty subsection rather than being dropped -- a decision the operator
+  attached and orcloop silently discarded is the one outcome #34 exists to
+  prevent.
+* The task DETAIL payload carries ``contextCount`` (an int), which is what
+  lets the release path skip this read entirely for the common zero-context
+  task -- see `Task.context_count`.
+
+Note for a future reader: the detail payload ALSO embeds the attachments
+themselves under an undocumented ``contextAttachments`` key, so the second
+call could in principle be avoided. orcloop deliberately does not read it. The
+dedicated route is the documented, access-gated one (the OpenAPI ``Task``
+schema pins neither the key nor its item shape), and the release path's
+conservatism depends on being able to tell "there are N attachments" from "I
+read them": a silently-absent embedded array would read as "no context" on
+exactly the payload that declares some.
+
 WHO AM I (O8)
 =============
 ``GET /v1/ping`` -- ``{"pong", "timestamp", "userId", "actorId",
@@ -266,6 +297,29 @@ class Dependency:
     status: str
 
 
+@dataclass(frozen=True)
+class ContextItem:
+    """One knowledge/reference attachment on a task (O14).
+
+    The operator's decision channel: whatever was decided AFTER the task was
+    authored lands here rather than being rewritten into the description. Every
+    field but `id` is optional in the payload, so every one but `id` defaults
+    to empty -- an attachment is identified by its title and rendered from
+    whichever payload it carries.
+
+    `markdown` is the write-up, `link` a bare URL, `note` the one-line "why
+    this is relevant"; an attachment may carry any combination, including none
+    (a vault reference the REST payload does not inline). `created_at` is ms
+    since epoch, 0 when the payload omits it -- the renderer orders on it."""
+
+    id: str
+    title: str = ""
+    markdown: str = ""
+    link: str = ""
+    note: str = ""
+    created_at: int = 0
+
+
 @dataclass(frozen=True)
 class Task:
     """A task as the DETAIL endpoint reports it -- full description and DoD,
@@ -293,6 +347,13 @@ class Task:
     # len(dependencies) when an upstream is invisible to this actor -- the gate
     # treats that mismatch as "not provably clear".
     depends_on_count: int = 0
+    # How many context attachments the DETAIL payload declares (`contextCount`,
+    # O14). Purely a "is the second read worth making" hint for the release
+    # path: 0/absent skips `get_task_context` entirely, which is the common
+    # case. It is NOT a length contract -- attachments can be added or deleted
+    # between the two reads -- so nothing keys on it agreeing with what the
+    # context endpoint returns. Only "declares some" vs "declares none" matters.
+    context_count: int = 0
 
 
 def _query(params: dict) -> str:
@@ -625,6 +686,17 @@ class AlissaClient:
         created_raw = task.get("createdAt")
         created_at = int(created_raw) if isinstance(created_raw, (int, float)) else 0
 
+        # A bool IS an int in Python; `contextCount: true` would read as 1 and
+        # buy a context read on a payload that declared nothing countable, so
+        # it is excluded explicitly. Negatives clamp to 0 -- "fewer than none"
+        # is not a reason to make the read.
+        count_raw = task.get("contextCount")
+        context_count = (
+            max(0, int(count_raw))
+            if isinstance(count_raw, (int, float)) and not isinstance(count_raw, bool)
+            else 0
+        )
+
         number = task.get("taskNumber")
         return Task(
             ref=f"TASK-{number}" if isinstance(number, int) else str(ref),
@@ -638,7 +710,58 @@ class AlissaClient:
             created_at=created_at,
             dependencies=tuple(dependencies),
             depends_on_count=depends_on_count,
+            context_count=context_count,
+        )
+
+    def get_task_context(self, ref: str) -> list[ContextItem]:
+        """The task's context attachments, in the order the endpoint returns
+        them (`GET /v1/tasks/<ref>/context`).
+
+        Ordering is the CALLER's to impose (the renderer sorts on
+        `created_at`); this stays a faithful read of the payload. Rows without
+        an `_id` are dropped -- an attachment that cannot be addressed cannot be
+        cited or edited -- but a row with an id and nothing else is KEPT: the
+        payload pins only `_id` and `title`, so treating a shape this adapter
+        does not recognise as "no context" would drop the very decisions the
+        feature exists to carry.
+
+        A 2xx whose `context` key is not an array is a contract violation, not
+        an empty list, and surfaces as the base `AlissaError` -- the same way
+        `get_task` refuses to fabricate a Task. That distinction is load-
+        bearing on the release path: it holds the release instead of filing an
+        issue that silently lost the operator's decisions.
+        """
+        payload = self._request(
+            "GET", f"/v1/tasks/{urllib.parse.quote(str(ref), safe='')}/context"
         )
+        rows = payload.get("context") if isinstance(payload, dict) else None
+        if not isinstance(rows, list):
+            raise AlissaError(200, f"no context array in response for {ref!r}")
+
+        out: list[ContextItem] = []
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            item_id = row.get("_id")
+            if not isinstance(item_id, str) or not item_id:
+                continue
+            created_raw = row.get("createdAt")
+            out.append(
+                ContextItem(
+                    id=item_id,
+                    title=str(row.get("title") or ""),
+                    markdown=str(row.get("markdownContent") or ""),
+                    link=str(row.get("link") or ""),
+                    note=str(row.get("note") or ""),
+                    created_at=(
+                        int(created_raw)
+                        if isinstance(created_raw, (int, float))
+                        and not isinstance(created_raw, bool)
+                        else 0
+                    ),
+                )
+            )
+        return out
 
     def add_evidence(self, ref: str, title: str, markdown: str, *, item_type: str = "evidence") -> None:
         """Attach an evidence/deliverable item (outputs surface, not context).