Skip to content

Pass single-session options to Matching task-add hooks - #12840

Draft
Shivs11 wants to merge 3 commits into
shivam/agentcore-single-sessionfrom
shivam/agentcore-session-wci-hooks
Draft

Shivs11 wants to merge 3 commits into
shivam/agentcore-single-sessionfrom
shivam/agentcore-session-wci-hooks

Conversation

@Shivs11

@Shivs11 Shivs11 commented Oct 30, 2026 •

Copy link
Copy Markdown
Member

Summary

Stacked on #12770, which builds on #12630.

History now sends the bound session's stable identity with workflow tasks and opted-in activity tasks. Matching passes it to task-add hooks with the task's actual deployment version and existing match outcome.

History: bound workflow + resolved sticky destination S
  → AddWorkflowTask / AddActivityTask: SingleSessionOptions{StableIdentity: S}
  → Matching task-add hook: session S + task WDV + match outcome

Things to do

  • have to ponder a bit about workflow + activity task retries
  • note: this PR is just describing the happy path at it's finest

return "", false, err
}

hookVersion := syncMatchQueue.QueueKey().Version().WorkerDeploymentVersionS()

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

used an existing helper here but seems to be a typo....capital S at the very end (shall change it in a future commit)

// Stamp value from when the workflow task was scheduled. Used to validate the task is still relevant.
int32 stamp = 13;
// Identifies the bound single-session destination for this task, if any.
temporal.api.session.v1.SingleSessionOptions single_session_options = 14;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's kinda weird to me that the workflow (i.e. the session) deal with SingleSessionOptions and has to pass it as part of tasks to matching.

The mutable state and history->protocol should not use SingleSessionOptions IMO, because that proto is a worker options proto.

When we look from session/workflow POV they would have info/options about their "exclusive worker". When we look from the sticky TQ it has info about it's single assigned session. When looked from worker it has options to state single session preferences.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was thinking of the SingleSessionOptions being a proto that can be used in places where deemed necessary; i look at the worker options as the ones that are specifically defined on the worker, under WorkerSessionOptions.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but this is the same SingleSessionOptions that is used in WorkerSessionOptions. I'm not sure the options wf wants to have for single-session mode will be always the same as the info that workflow wants to remember.

// embedded activities.
bytes component_ref = 14;
// Identifies the bound single-session destination for this task, if any.
temporal.api.session.v1.SingleSessionOptions single_session_options = 15;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

obviously, the more we put in history the better. Ideally, these APIs don't have to change.

Is there any reason matching needs to get this info from history? why not use the info stored in TQ metadata to know about single-session mode?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

information stored on the task queue metadata can't be used here because that bit is set once you have the task being assigned to a worker. For example, think about the first workflow task of a workflow. On being assigned to a session S1, we set the bit in the task queue metadata. However, we only do this for the 'workflow' task queue partition and not the activity one.

Thus, if the next thing to do for the workflow is to schedule an activity task, then the corresponding activity task queue partition would not know from matching solely that it has been assigned to the session -- which is why i was thinking that we pass this information from history itself.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the activity case makes sense. but should the proto be something more generic? thinking something like:

message TaskSessionOptions {
   WorkerAddress worker_address;
   bool exclusive_worker_bound;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or maybe TaskSessionDirective consistent with TaskVersionDirective

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as discussed in our call, i agree.

Merge shivam/agentcore-single-session and derive hook context from SessionState.ExclusiveWorker. Preserve the updated timeout and fallback behavior, and omit the redundant standby workflow snapshot.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants