From aa20d94db530e7770f148654423405c243b9a4c9 Mon Sep 17 00:00:00 2001 From: sdharavath Date: Wed, 4 Nov 2026 13:54:15 +0530 Subject: [PATCH] hosted agents: decode trigger pause reason and waiting execution fields (MARSOHS-2624) Co-authored-by: Cursor --- hosted_agent_triggers.go | 35 ++++++++++++++++++++++++----------- hosted_agent_triggers_test.go | 32 ++++++++++++++++++++++++++++++++ hosted_agents.go | 3 +++ hosted_agents_test.go | 12 ++++++++++++ 4 files changed, 71 insertions(+), 11 deletions(-) diff --git a/hosted_agent_triggers.go b/hosted_agent_triggers.go index 1d3374b9..b07d5cc0 100644 --- a/hosted_agent_triggers.go +++ b/hosted_agent_triggers.go @@ -102,6 +102,17 @@ const ( HostedAgentTriggerExecutionStatusFailed HostedAgentTriggerExecutionStatus = "failed" ) +// HostedAgentTriggerExecutionStatusReason is why a non-terminal execution is +// held. The API may add reasons, so an unrecognized value stays an opaque +// string. Status itself stays running while one of these is set. +type HostedAgentTriggerExecutionStatusReason string + +const ( + // HostedAgentTriggerExecutionWaitingForBoundSession means a reuse firing is + // waiting for its bound session to pause. Status stays running. + HostedAgentTriggerExecutionWaitingForBoundSession HostedAgentTriggerExecutionStatusReason = "waiting_for_bound_session" +) + // HostedAgentWebhookSignatureScheme is how an external system authenticates a delivery. type HostedAgentWebhookSignatureScheme string @@ -272,17 +283,19 @@ type HostedAgentTriggerRotateSecretResponse struct { // HostedAgentTriggerExecution is one row per firing. type HostedAgentTriggerExecution struct { - ExecutionID string `json:"execution_id,omitempty"` - TriggerID string `json:"trigger_id,omitempty"` - Status HostedAgentTriggerExecutionStatus `json:"status,omitempty"` - SessionID string `json:"session_id,omitempty"` - RunID string `json:"run_id,omitempty"` - FailureReason string `json:"failure_reason,omitempty"` - CreatedAt Timestamp `json:"created_at,omitempty"` - UpdatedAt Timestamp `json:"updated_at,omitempty"` - Payload string `json:"payload,omitempty"` - OutputText string `json:"output_text,omitempty"` - OutputTruncated bool `json:"output_truncated,omitempty"` + ExecutionID string `json:"execution_id,omitempty"` + TriggerID string `json:"trigger_id,omitempty"` + Status HostedAgentTriggerExecutionStatus `json:"status,omitempty"` + SessionID string `json:"session_id,omitempty"` + RunID string `json:"run_id,omitempty"` + StatusReason HostedAgentTriggerExecutionStatusReason `json:"status_reason,omitempty"` + StatusMessage string `json:"status_message,omitempty"` + FailureReason string `json:"failure_reason,omitempty"` + CreatedAt Timestamp `json:"created_at,omitempty"` + UpdatedAt Timestamp `json:"updated_at,omitempty"` + Payload string `json:"payload,omitempty"` + OutputText string `json:"output_text,omitempty"` + OutputTruncated bool `json:"output_truncated,omitempty"` } // HostedAgentTriggerExecutionListOptions specifies optional execution list filters. diff --git a/hosted_agent_triggers_test.go b/hosted_agent_triggers_test.go index 309fc42b..ac35147c 100644 --- a/hosted_agent_triggers_test.go +++ b/hosted_agent_triggers_test.go @@ -509,6 +509,38 @@ func TestHostedAgentTriggers_GetExecution(t *testing.T) { assert.Equal(t, http.StatusOK, resp.StatusCode) } +func TestHostedAgentTriggerExecution_DecodesWaitingDetail(t *testing.T) { + const raw = `{ + "execution_id": "exec-wait", + "status": "running", + "status_reason": "waiting_for_bound_session", + "status_message": "Waiting for the bound session to pause." + }` + + var exec HostedAgentTriggerExecution + require.NoError(t, json.Unmarshal([]byte(raw), &exec)) + assert.Equal(t, HostedAgentTriggerExecutionStatusRunning, exec.Status) + assert.Equal(t, HostedAgentTriggerExecutionWaitingForBoundSession, exec.StatusReason) + assert.Equal(t, "Waiting for the bound session to pause.", exec.StatusMessage) + + body, err := json.Marshal(&exec) + require.NoError(t, err) + var fields map[string]any + require.NoError(t, json.Unmarshal(body, &fields)) + assert.Equal(t, "waiting_for_bound_session", fields["status_reason"]) + assert.Equal(t, "Waiting for the bound session to pause.", fields["status_message"]) + + // An unknown reason stays opaque, and an execution with no detail omits both fields. + var unknown HostedAgentTriggerExecution + require.NoError(t, json.Unmarshal([]byte(`{"status_reason":"some_future_reason"}`), &unknown)) + assert.Equal(t, HostedAgentTriggerExecutionStatusReason("some_future_reason"), unknown.StatusReason) + + empty, err := json.Marshal(&HostedAgentTriggerExecution{ExecutionID: "exec-plain", Status: HostedAgentTriggerExecutionStatusRunning}) + require.NoError(t, err) + assert.NotContains(t, string(empty), "status_reason") + assert.NotContains(t, string(empty), "status_message") +} + func TestHostedAgentTriggers_Cancel(t *testing.T) { setup() defer teardown() diff --git a/hosted_agents.go b/hosted_agents.go index d8d30026..a57bff34 100644 --- a/hosted_agents.go +++ b/hosted_agents.go @@ -300,6 +300,9 @@ const ( // Deprecated: Use HostedAgentSessionPauseReasonZeroBalance. Servers now return // "zero_balance"; this constant is kept for backward compatibility with older API responses. HostedAgentSessionPauseReasonLowBalance HostedAgentSessionPauseReason = "low_balance" + // HostedAgentSessionPauseReasonTrigger is a pause recorded after a reuse + // trigger firing, rather than one the customer requested. + HostedAgentSessionPauseReasonTrigger HostedAgentSessionPauseReason = "trigger" ) // HostedAgentProviderAuthState tracks OAuth authorization for an external provider. diff --git a/hosted_agents_test.go b/hosted_agents_test.go index 8d98758b..1b99a56a 100644 --- a/hosted_agents_test.go +++ b/hosted_agents_test.go @@ -326,6 +326,18 @@ func TestHostedAgentSession_DecodesPauseReason(t *testing.T) { assert.Equal(t, HostedAgentSessionPauseReasonLowBalance, session.PauseReason) } +func TestHostedAgentSession_DecodesTriggerPauseReason(t *testing.T) { + const sessionJSON = `{ + "session_id": "sess-trigger", + "status": "SESSION_STATUS_PAUSED", + "pause_reason": "trigger" + }` + + var session HostedAgentSession + require.NoError(t, json.Unmarshal([]byte(sessionJSON), &session)) + assert.Equal(t, HostedAgentSessionPauseReasonTrigger, session.PauseReason) +} + // The API reserves the right to add reasons, so a value this client has no // constant for still has to survive decoding intact. func TestHostedAgentSession_KeepsUnknownPauseReasonVerbatim(t *testing.T) {