Make it rhyme
"}) +) +workspace.agent_runs.stop(run.id) # -> status "stopping"; 409 if it already ended + +# As the agent (PlaneClient(base_url=..., access_token=Write a poem about this work item
") + ) + + +@pytest.fixture +def run(workspace: LoadedWorkspace, agent_slug: str, thread: Any) -> LoadedAgentRun: + """A run the person started. Runs can't be deleted -- the work item's cleanup is the + only teardown there is.""" + return workspace.agent_runs.create( + CreateAgentRun(agent_slug=agent_slug, comment_id=thread.id, title=unique_name("run")) + ) + + +class TestRunsAsAPerson: + def test_create_takes_the_comments_work_item( + self, run: LoadedAgentRun, thread: Any, work_item: Any + ) -> None: + assert run.comment_id == thread.id + assert run.source_comment_id == thread.id + assert run.work_item_id == work_item.id + assert run.status in {"created", "in_progress"} + assert run.type == "comment_thread" + + def test_retrieve_expands_the_thread_comment_and_work_item( + self, workspace: LoadedWorkspace, run: LoadedAgentRun, thread: Any, work_item: Any + ) -> None: + fetched = workspace.agent_runs.retrieve(run.id, expand=["comment", "work_item"]) + + body = fetched.model_dump() + assert body["comment"]["id"] == thread.id + assert body["work_item"]["id"] == work_item.id + + def test_list_filters_by_work_item_and_status( + self, workspace: LoadedWorkspace, run: LoadedAgentRun, work_item: Any + ) -> None: + page = workspace.agent_runs.list( + work_item_id=work_item.id, status__in=["created", "in_progress", "awaiting"] + ) + assert [row.id for row in page.data] == [run.id] + + none = workspace.agent_runs.list(work_item_id=work_item.id, status="completed") + assert none.data == [] + + def test_a_cursor_walk_reaches_the_run_once_the_hold_back_passes( + self, workspace: LoadedWorkspace, run: LoadedAgentRun, work_item: Any + ) -> None: + time.sleep(SYNC_HOLD_BACK_SECONDS) + + rows = list( + workspace.agent_runs.iterate(work_item_id=work_item.id, paginate="cursor", per_page=1) + ) + + assert [row.id for row in rows] == [run.id] + assert rows[0].activities._ids[-1] == run.id + + def test_a_person_cannot_update_a_run( + self, workspace: LoadedWorkspace, run: LoadedAgentRun + ) -> None: + with pytest.raises(PlaneAPIError) as caught: + workspace.agent_runs.update(run.id, UpdateAgentRun(summary="forged")) + assert caught.value.status == 403 + + def test_stop_moves_the_run_to_stopping_and_only_once( + self, workspace: LoadedWorkspace, run: LoadedAgentRun + ) -> None: + stopped = workspace.agent_runs.stop(run.id) + assert stopped.status == "stopping" + + with pytest.raises(PlaneAPIError) as caught: + workspace.agent_runs.stop(run.id) + assert caught.value.status == 409 + + signals = [row.signal for row in stopped.activities.iterate(type="prompt")] + assert "stop" in signals + + def test_an_unknown_run_is_a_404(self, workspace: LoadedWorkspace) -> None: + with pytest.raises(PlaneAPIError) as caught: + workspace.agent_runs.retrieve("00000000-0000-4000-8000-000000000000") + assert caught.value.status == 404 + + +class TestActivitiesAsAPerson: + def test_a_prompt_is_logged_and_mirrored_into_the_thread( + self, workspace: LoadedWorkspace, run: LoadedAgentRun, work_item: Any + ) -> None: + prompt = run.activities.create( + CreateAgentRunActivity( + type="prompt", + content={"type": "prompt", "body": "Make it rhyme
"}, + content_metadata={"client_ref": "sdk-it"}, + ) + ) + + assert prompt.type == "prompt" + assert prompt.agent_run_id == run.id + assert prompt.content_metadata == {"client_ref": "sdk-it"} + assert prompt.comment_id is not None, "a person's prompt is mirrored as a thread reply" + + fetched = run.activities.retrieve(prompt.id, expand=["actor"]) + assert fetched.content == {"type": "prompt", "body": "Make it rhyme
"} + + logged = {row.id for row in run.activities.iterate(type="prompt")} + assert prompt.id in logged + + reply = work_item.comments.retrieve(prompt.comment_id) + assert "Make it rhyme" in (reply.comment_html or "") + + def test_the_workspace_feed_carries_the_runs_activity( + self, workspace: LoadedWorkspace, run: LoadedAgentRun + ) -> None: + prompt = run.activities.create( + CreateAgentRunActivity(type="prompt", content={"type": "prompt", "body": "Go
"}) + ) + + page = workspace.agent_run_activities.list(agent_run_id=run.id, type="prompt") + assert prompt.id in {row.id for row in page.data} + + assert prompt.created_at is not None + time.sleep(SYNC_HOLD_BACK_SECONDS) + polled = workspace.agent_run_activities.iterate( + agent_run_id=run.id, created_at__gte=prompt.created_at.isoformat(), paginate="cursor" + ) + assert prompt.id in {row.id for row in polled} + + def test_a_person_cannot_post_the_agents_output(self, run: LoadedAgentRun) -> None: + with pytest.raises(PlaneAPIError) as caught: + run.activities.create( + CreateAgentRunActivity( + type="response", content={"type": "response", "body": "forged"} + ) + ) + assert caught.value.status == 400 + + +class TestCommentsCarryTheRun: + def test_the_thread_comment_names_its_run( + self, run: LoadedAgentRun, thread: Any, work_item: Any + ) -> None: + fetched = work_item.comments.retrieve(thread.id, expand=["agent_run"]) + + assert fetched.agent_run_id == run.id + assert fetched.agent_run is not None + assert fetched.agent_run.id == run.id + assert fetched.agent_run.agent_user_id == run.agent_user_id + + def test_comments_filter_by_agent_run_id( + self, run: LoadedAgentRun, thread: Any, work_item: Any + ) -> None: + work_item.comments.create(CreateWorkItemComment(comment_html="unrelated
")) + + page = work_item.comments.list(agent_run_id=run.id, fields=["id", "agent_run_id"]) + + assert [(row.id, row.agent_run_id) for row in page.data] == [(thread.id, run.id)] + + +class TestRunsAsTheAgent: + def test_the_agent_reports_and_completes_its_run( + self, agent_client: PlaneClient, workspace_slug: str, run: LoadedAgentRun + ) -> None: + agent_runs = agent_client.v2.workspaces.agent_runs + mine = agent_runs.retrieve(workspace_slug, run.id) + + thought = mine.activities.create( + CreateAgentRunActivity( + type="thought", content={"type": "thought", "body": "Reading the work item"} + ) + ) + assert thought.type == "thought" + + done = agent_runs.update( + workspace_slug, + run.id, + UpdateAgentRun(status="completed", summary="Wrote the poem.", token_usage={"in": 7}), + ) + assert done.status == "completed" + assert done.summary == "Wrote the poem." + assert done.ended_at is not None + + def test_the_agent_lists_its_own_runs( + self, agent_client: PlaneClient, workspace_slug: str, run: LoadedAgentRun + ) -> None: + assert run.agent_user_id is not None and run.work_item_id is not None + page = agent_client.v2.workspaces.agent_runs.list( + workspace_slug, agent_user_id=run.agent_user_id, work_item_id=run.work_item_id + ) + assert [row.id for row in page.data] == [run.id] + + def test_the_agent_cannot_stop_its_run( + self, agent_client: PlaneClient, workspace_slug: str, run: LoadedAgentRun + ) -> None: + with pytest.raises(PlaneAPIError) as caught: + agent_client.v2.workspaces.agent_runs.stop(workspace_slug, run.id) + assert caught.value.status == 403 diff --git a/tests/v2/test_agent_runs_resource.py b/tests/v2/test_agent_runs_resource.py new file mode 100644 index 0000000..f28cf9f --- /dev/null +++ b/tests/v2/test_agent_runs_resource.py @@ -0,0 +1,374 @@ +"""Offline coverage for `AgentRuns`, its `activities` child and the workspace-wide +`agent_run_activities` feed: every operation's URL, method, query and body, the DTO +rules the API enforces, and navigation from a fetched run and a fetched workspace.""" + +import json +from urllib.parse import parse_qs, urlparse + +import pytest +import responses +from pydantic import ValidationError + +from plane.api.v2 import LoadedAgentRun, PlaneAPIError, V2Namespace +from plane.api.v2._kernel.transport import V2Transport +from plane.api.v2.agent_runs import AgentRuns, WorkspaceAgentRunActivities +from plane.config import Configuration +from plane.models.v2.agent_runs import ( + AgentRunActivity, + CreateAgentRun, + CreateAgentRunActivity, + UpdateAgentRun, +) + +ROOT = "https://api.example.com/api/v2/workspaces/acme" +RUNS = f"{ROOT}/runs" +RUN = { + "id": "r1", + "agent_user_id": "bot-1", + "comment_id": "c1", + "source_comment_id": "c1", + "work_item_id": "w1", + "project_id": "p1", + "status": "in_progress", + "type": "comment_thread", + "title": "Write a poem", + "token_usage": {}, + "started_at": "2026-11-10T09:00:00Z", + "updated_at": "2026-11-10T09:00:05Z", +} +PROMPT = { + "id": "a1", + "agent_run_id": "r1", + "type": "prompt", + "content": {"type": "prompt", "body": "Make it rhyme
"}, + "signal": "continue", + "ephemeral": False, + "comment_id": "c2", +} + + +@pytest.fixture +def runs(config: Configuration) -> AgentRuns: + return AgentRuns(V2Transport(config)) + + +@pytest.fixture +def feed(config: Configuration) -> WorkspaceAgentRunActivities: + return WorkspaceAgentRunActivities(V2Transport(config)) + + +def _query(call_index: int = 0) -> dict[str, list[str]]: + return parse_qs(urlparse(responses.calls[call_index].request.url).query) + + +def _body(call_index: int = 0) -> object: + body = responses.calls[call_index].request.body + return json.loads(body) if body else None + + +# -- Runs --------------------------------------------------------------------------- + + +@responses.activate +def test_list_sends_filters_expand_and_the_cursor_envelope(runs: AgentRuns) -> None: + responses.get( + f"{RUNS}/", + json={ + "data": [RUN], + "pagination": {"style": "cursor"}, + "has_more": False, + "next_cursor": None, + }, + ) + + page = runs.list( + "acme", + status__in=["in_progress", "awaiting"], + work_item_id="w1", + updated_at__gte="2026-11-10T09:00:00Z", + expand=["agent_user", "work_item"], + order_by="-updated_at", + paginate="cursor", + per_page=50, + ) + + assert _query() == { + "status__in": ["in_progress,awaiting"], + "work_item_id": ["w1"], + "updated_at__gte": ["2026-11-10T09:00:00Z"], + "expand": ["agent_user,work_item"], + "order_by": ["-updated_at"], + "paginate": ["cursor"], + "per_page": ["50"], + } + row = page.data[0] + assert isinstance(row, LoadedAgentRun) + assert row.status == "in_progress" + assert row.activities._ids == ("acme", "r1") + + +def test_list_rejects_options_the_golden_does_not_offer(runs: AgentRuns) -> None: + with pytest.raises(ValueError, match="Unknown order_by"): + runs.list("acme", order_by="title") # type: ignore[arg-type] + with pytest.raises(ValueError, match="Unknown expand"): + runs.list("acme", expand=["actor"]) + with pytest.raises(ValueError, match="Unknown field"): + runs.list("acme", fields=["name"]) # type: ignore[list-item] + + +@responses.activate +def test_iterate_follows_cursor_pages_and_threads_the_ids(runs: AgentRuns) -> None: + responses.get( + f"{RUNS}/", + json={ + "data": [{**RUN, "id": "r1"}], + "pagination": {"style": "cursor"}, + "has_more": True, + "next_cursor": "cur-2", + }, + ) + responses.get( + f"{RUNS}/", + json={ + "data": [{**RUN, "id": "r2"}], + "pagination": {"style": "cursor"}, + "has_more": False, + "next_cursor": None, + }, + ) + + rows = list(runs.iterate("acme", paginate="cursor", status="awaiting")) + + assert [row.id for row in rows] == ["r1", "r2"] + assert rows[1].activities._ids == ("acme", "r2") + assert _query(1) == {"paginate": ["cursor"], "status": ["awaiting"], "cursor": ["cur-2"]} + + +@responses.activate +def test_retrieve_passes_fields_and_expand(runs: AgentRuns) -> None: + responses.get( + f"{RUNS}/r1/", + json={"id": "r1", "status": "completed", "comment": {"id": "c1", "comment_html": ""}}, + ) + + row = runs.retrieve("acme", "r1", fields=["id", "status"], expand=["comment"]) + + assert row.status == "completed" + assert _query() == {"fields": ["id,status"], "expand": ["comment"]} + + +@responses.activate +def test_create_sends_only_the_fields_set(runs: AgentRuns) -> None: + responses.post(f"{RUNS}/", json={**RUN, "status": "created"}, status=201) + + created = runs.create( + "acme", CreateAgentRun(agent_slug="poem-agent", comment_id="c1", title="Write a poem") + ) + + assert created.status == "created" + assert created.activities._ids == ("acme", "r1") + assert _body() == {"agent_slug": "poem-agent", "comment_id": "c1", "title": "Write a poem"} + + +def test_create_needs_an_agent_slug_and_a_comment() -> None: + with pytest.raises(ValidationError): + CreateAgentRun(agent_slug="", comment_id="c1") + with pytest.raises(ValidationError): + CreateAgentRun(agent_slug="poem-agent") # type: ignore[call-arg] + + +@responses.activate +def test_update_patches_the_agents_report(runs: AgentRuns) -> None: + responses.patch(f"{RUNS}/r1/", json={**RUN, "status": "completed", "summary": "Done."}) + + updated = runs.update( + "acme", + "r1", + UpdateAgentRun(status="completed", summary="Done.", token_usage={"input": 12}), + ) + + assert updated.status == "completed" + assert responses.calls[0].request.method == "PATCH" + assert _body() == {"status": "completed", "summary": "Done.", "token_usage": {"input": 12}} + + +def test_update_only_settles_a_run_as_completed() -> None: + with pytest.raises(ValidationError): + UpdateAgentRun(status="stopped") # type: ignore[arg-type] + + +@responses.activate +def test_stop_posts_with_no_body_and_answers_the_run(runs: AgentRuns) -> None: + responses.post(f"{RUNS}/r1/stop/", json={**RUN, "status": "stopping"}) + + stopped = runs.stop("acme", "r1", fields=["id", "status"]) + + assert stopped.status == "stopping" + assert responses.calls[0].request.body is None + assert _query() == {"fields": ["id,status"]} + assert stopped.activities._ids == ("acme", "r1") + + +@responses.activate +def test_stopping_an_ended_run_raises_the_409(runs: AgentRuns) -> None: + responses.post( + f"{RUNS}/r1/stop/", + status=409, + json={ + "type": "https://developers.plane.so/errors/conflict", + "title": "Conflict", + "status": 409, + "code": "conflict", + "detail": "This agent run has already ended.", + }, + content_type="application/problem+json", + ) + + with pytest.raises(PlaneAPIError) as caught: + runs.stop("acme", "r1") + + assert caught.value.status == 409 + assert caught.value.code == "conflict" + + +def test_runs_cannot_be_deleted(runs: AgentRuns) -> None: + """The API has no DELETE for a run -- it is settled, not removed.""" + assert not hasattr(runs, "delete") + + +# -- Activities on one run ---------------------------------------------------------- + + +@responses.activate +def test_a_fetched_run_lists_its_activities_with_no_ids_repeated(runs: AgentRuns) -> None: + responses.get(f"{RUNS}/r1/", json=RUN) + responses.get( + f"{RUNS}/r1/activities/", + json={"data": [PROMPT], "pagination": {"style": "offset"}, "total_count": 1}, + ) + + run = runs.retrieve("acme", "r1") + page = run.activities.list(type__in=["prompt", "response"], expand=["actor"]) + + assert responses.calls[1].request.url.startswith(f"{RUNS}/r1/activities/?") + assert _query(1) == {"type__in": ["prompt,response"], "expand": ["actor"]} + activity = page.data[0] + assert isinstance(activity, AgentRunActivity) + assert activity.content == {"type": "prompt", "body": "Make it rhyme
"} + assert activity.comment_id == "c2" + + +@responses.activate +def test_activities_create_and_retrieve_on_the_flat_path(config: Configuration) -> None: + activities = V2Namespace(config).workspaces.agent_runs.activities + responses.post(f"{RUNS}/r1/activities/", json=PROMPT, status=201) + responses.get(f"{RUNS}/r1/activities/a1/", json=PROMPT) + + created = activities.create( + "acme", + "r1", + CreateAgentRunActivity( + type="prompt", + content={"type": "prompt", "body": "Make it rhyme
"}, + content_metadata={"idempotency_key": "k-1"}, + ), + ) + fetched = activities.retrieve("acme", "r1", "a1", fields=["id", "type"]) + + assert created.id == fetched.id == "a1" + assert _body() == { + "type": "prompt", + "content": {"type": "prompt", "body": "Make it rhyme
"}, + "content_metadata": {"idempotency_key": "k-1"}, + } + assert _query(1) == {"fields": ["id,type"]} + + +@responses.activate +def test_iterate_activities_follows_offset_pages(config: Configuration) -> None: + activities = V2Namespace(config).workspaces.agent_runs.activities + responses.get( + f"{RUNS}/r1/activities/", + json={"data": [PROMPT], "next": 1, "pagination": {"style": "offset"}}, + ) + responses.get( + f"{RUNS}/r1/activities/", + json={"data": [{**PROMPT, "id": "a2"}], "next": None, "pagination": {"style": "offset"}}, + ) + + assert [row.id for row in activities.iterate("acme", "r1", per_page=1)] == ["a1", "a2"] + + +def test_an_activity_needs_a_known_type() -> None: + with pytest.raises(ValidationError): + CreateAgentRunActivity(type="comment", content={"body": "x"}) # type: ignore[arg-type] + + +# -- The workspace-wide activity feed ----------------------------------------------- + + +@responses.activate +def test_feed_polls_with_the_sync_filters(feed: WorkspaceAgentRunActivities) -> None: + responses.get( + f"{RUNS}/activities/", + json={"data": [PROMPT], "pagination": {"style": "cursor"}, "has_more": False}, + ) + + page = feed.list( + "acme", + agent_run_id="r1", + created_at__gte="2026-11-10T09:00:00Z", + signal="stop", + paginate="cursor", + ) + + assert page.data[0].agent_run_id == "r1" + assert _query() == { + "agent_run_id": ["r1"], + "created_at__gte": ["2026-11-10T09:00:00Z"], + "signal": ["stop"], + "paginate": ["cursor"], + } + + +@responses.activate +def test_feed_iterate_walks_the_cursor(feed: WorkspaceAgentRunActivities) -> None: + responses.get( + f"{RUNS}/activities/", + json={ + "data": [PROMPT], + "pagination": {"style": "cursor"}, + "has_more": True, + "next_cursor": "c-2", + }, + ) + responses.get( + f"{RUNS}/activities/", + json={"data": [{**PROMPT, "id": "a2"}], "pagination": {"style": "cursor"}}, + ) + + assert [row.id for row in feed.iterate("acme", paginate="cursor")] == ["a1", "a2"] + assert _query(1)["cursor"] == ["c-2"] + + +# -- Navigation from a fetched workspace -------------------------------------------- + + +@responses.activate +def test_a_fetched_workspace_reaches_runs_and_the_feed(config: Configuration) -> None: + responses.get(f"{ROOT}/", json={"id": "ws-1", "slug": "acme"}) + responses.get(f"{RUNS}/r1/", json=RUN) + responses.get(f"{RUNS}/r1/activities/", json={"data": [], "pagination": {"style": "offset"}}) + responses.get(f"{RUNS}/activities/", json={"data": [], "pagination": {"style": "offset"}}) + + workspace = V2Namespace(config).workspaces.retrieve("acme") + run = workspace.agent_runs.retrieve("r1") + run.activities.list() + workspace.agent_run_activities.list() + + assert [call.request.url.split("?")[0] for call in responses.calls] == [ + f"{ROOT}/", + f"{RUNS}/r1/", + f"{RUNS}/r1/activities/", + f"{RUNS}/activities/", + ] diff --git a/tests/v2/test_tree.py b/tests/v2/test_tree.py index 06d40e1..72196cf 100644 --- a/tests/v2/test_tree.py +++ b/tests/v2/test_tree.py @@ -4,6 +4,7 @@ import responses from plane.api.v2 import V2Namespace +from plane.api.v2.agent_runs import AgentRunActivities, AgentRuns, WorkspaceAgentRunActivities from plane.api.v2.artifacts import Artifacts from plane.api.v2.assets import WorkspaceAssets from plane.api.v2.audit_logs import AuditLogs @@ -267,6 +268,19 @@ def test_every_resource_class_is_reachable_from_the_namespace(config: Configurat # `Wiki` (see `plane/api/v2/wiki_node.py`), with no `path` of its own -- its three # children each get their own row with a real URL instead. WORKSPACE_TREE_ATTACHMENTS = [ + ("agent_runs", lambda ws: ws.agent_runs, AgentRuns, "/workspaces/acme/runs/"), + ( + "agent_runs.activities", + lambda ws: ws.agent_runs.activities, + AgentRunActivities, + None, # its collection URL carries the run id -- see the test below + ), + ( + "agent_run_activities", + lambda ws: ws.agent_run_activities, + WorkspaceAgentRunActivities, + "/workspaces/acme/runs/activities/", + ), ("artifacts", lambda ws: ws.artifacts, Artifacts, "/workspaces/acme/artifacts/"), ("assets", lambda ws: ws.assets, WorkspaceAssets, "/workspaces/acme/assets/"), ("audit_logs", lambda ws: ws.audit_logs, AuditLogs, "/workspaces/acme/audit-logs/"), @@ -675,6 +689,10 @@ def test_the_newly_attached_workspace_children_reach_their_urls(config: Configur a wrongly-templated child would pass on the `isinstance` half of its row alone.""" ws = V2Namespace(config).workspaces + assert ( + ws.agent_runs.activities._collection_url(slug="acme", run_id="r1") + == "/workspaces/acme/runs/r1/activities/" + ) assert ( ws.customers.requests._collection_url(slug="acme", customer_id="c1") == "/workspaces/acme/customers/c1/requests/" diff --git a/tests/v2/test_work_items_resource.py b/tests/v2/test_work_items_resource.py index 8d8bc8e..f9b0e60 100644 --- a/tests/v2/test_work_items_resource.py +++ b/tests/v2/test_work_items_resource.py @@ -254,6 +254,63 @@ def test_comments_upsert(work_items: WorkItems) -> None: assert result.id == "c1" +@responses.activate +def test_comments_filter_and_expand_by_agent_run(work_items: WorkItems) -> None: + """A comment that started an agent run carries `agent_run_id`; `?agent_run_id=` finds + it, and `expand=["agent_run"]` inlines the run's id, status and agent.""" + responses.get( + f"{BASE}/wi-1/comments/", + json={ + "data": [ + { + "id": "c1", + "agent_run_id": "r1", + "agent_run": { + "id": "r1", + "status": "awaiting", + "agent_user_id": "bot-1", + "native_agent_id": None, + }, + } + ], + "pagination": {"style": "offset"}, + }, + ) + + page = work_items.comments.list( + "acme", + "ENG", + "wi-1", + agent_run_id="r1", + expand=["actor", "agent_run"], + fields=["id", "agent_run_id"], + ) + + query = responses.calls[0].request.url.split("?", 1)[1] + assert "agent_run_id=r1" in query + assert "expand=actor%2Cagent_run" in query + assert "fields=id%2Cagent_run_id" in query + comment = page.data[0] + assert comment.agent_run_id == "r1" + assert comment.agent_run is not None + assert (comment.agent_run.status, comment.agent_run.agent_user_id) == ("awaiting", "bot-1") + + +@responses.activate +def test_a_comment_without_a_run_reads_agent_run_id_as_none(work_items: WorkItems) -> None: + responses.get(f"{BASE}/wi-1/comments/c2/", json={"id": "c2", "agent_run_id": None}) + + comment = work_items.comments.retrieve("acme", "ENG", "wi-1", "c2", expand=["agent_run"]) + + assert comment.agent_run_id is None + assert comment.agent_run is None + + +def test_comments_reject_an_expand_the_golden_does_not_offer(work_items: WorkItems) -> None: + with pytest.raises(ValueError, match="Unknown expand"): + work_items.comments.list("acme", "ENG", "wi-1", expand=["agent_runs"]) + + @responses.activate def test_comments_have_their_own_bulk_operations(work_items: WorkItems) -> None: """Comments' bulk ops (`work_item_comments_bulk_*`) are distinct operationIds