feat(agent-core): thread roleAdditional through the session API#2033
feat(agent-core): thread roleAdditional through the session API#2033TennyZhuang wants to merge 2 commits into
Conversation
The agent profile system already renders a {{ROLE_ADDITIONAL}} slot
(profile/resolve.ts + system.md) but there was no way to set it through
the SDK — the render half existed with no input path.
Thread an optional `roleAdditional` string parallel to `additionalDirs`
at every layer: node-sdk CreateSessionOptions/ResumeSessionInput ->
core CreateSessionPayload/ResumeSessionPayload -> Session/Agent ->
updateSystemPromptFromProfile. On resume, if `roleAdditional` differs
from the value that rendered an agent's persisted prompt (tracked via
AgentMeta.roleAdditional), re-render just that agent's system prompt
from the restored profile. Additive and optional; no behavior change
when unset.
🦋 Changeset detectedLatest commit: 2a04750 The changes in this PR will be included in the next version bump. This PR includes changesets to release 5 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7ca2a3c2d0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| // prompt using the restored profile and the fresh context. This keeps the | ||
| // persisted profile in sync with the new standing instructions without | ||
| // refreshing AGENTS.md/cwd on every resume. | ||
| if (this.roleAdditional !== meta.roleAdditional) { |
There was a problem hiding this comment.
When a session that was created or resumed with roleAdditional is later reloaded, the reload path calls resumeSessionWithOverrides({ sessionId }) without a way to pass the previous value, so this.roleAdditional is undefined here while meta.roleAdditional still contains the original text. This comparison then refreshes the system prompt with the {{ROLE_ADDITIONAL}} slot cleared and records undefined, silently dropping the standing prompt on SDK Session.reloadSession()//reload; either thread the value through reload or treat an omitted value as preserving the persisted prompt.
Useful? React with 👍 / 👎.
Session.reloadSession()/`/reload` (and a plain resume without the field)
call resume with no roleAdditional, so the session-level value was
undefined while the agent's persisted metadata still held the original
text. The resume-time comparison then re-rendered the system prompt with
an empty {{ROLE_ADDITIONAL}} slot and recorded undefined, silently
dropping the standing prompt.
Restore the persisted roleAdditional from the main agent's metadata on
resume when the caller omits it, so an omitted value preserves the
standing prompt (and newly-spawned agents keep inheriting it). An
explicit value still overrides, and an explicit empty string still
clears it.
1 participant
Related Issue
No prior issue — the problem is described below. Happy to open a tracking issue if preferred.
Problem
The agent profile system already renders a
{{ROLE_ADDITIONAL}}slot:profile/resolve.tsreadscontext.roleAdditionalas the highest-precedence source for it (profile/types.tstypes it,system.mdreferences it, and the default profiles set it viapromptVars). But nothing populatescontext.roleAdditional— there is no way to set it through the session API. The render half exists with no input path, so a caller cannot inject a standing/role prompt without editing profiles on disk.What changed
Thread an optional
roleAdditionalstring, parallel to the existingadditionalDirs, at every layer:CreateSessionOptions/ResumeSessionInputCreateSessionPayload/ResumeSessionPayloadupdateSystemPromptFromProfile, which passes it to the profile render context that already acceptsroleAdditionalResume/reload semantics: an explicit
roleAdditionalthat differs from the value that rendered an agent's persisted prompt (tracked viaAgentMeta.roleAdditional) re-renders that agent's system prompt from the restored profile — without refreshing AGENTS.md/cwd. An omitted value preserves the persisted standing prompt, soSession.reloadSession()//reload(which cannot pass one) no longer clears the slot; an explicit empty string still clears it.Additive and optional: no behavior change when
roleAdditionalis unset. Follows the existingadditionalDirsthreading pattern throughout.agent-coreandnode-sdktypecheck clean.Checklist
test/session/resume-roleadditional.test.ts(4 tests, passing)..changeset/roleadditional-session-api.md(minor).