Skip to content

Refactor working directory capabilities and remove primary directory references #359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
DonJayamanne wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Refactor working directory capabilities and remove primary directory references #359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions clients/go/ahptypes/actions.generated.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -898,8 +898,8 @@ type SessionWorkingDirectorySetAction struct {
// Removes `directory` from the set; a no-op when it is not present. There is no
// atomic backend "remove one" primitive — a host reconfigures its agent to the
// reduced set — so this action is safe to model as idempotent. A host MAY
// decline to apply the removal (e.g. a directory still designated as some
// chat's {@link ChatState.primaryWorkingDirectory | primary}); it then leaves
// decline to apply the removal (e.g. an immutable primary directory, see
// {@link MultipleWorkingDirectoriesCapability.immutablePrimary}); it then leaves
// the set unchanged.
type SessionWorkingDirectoryRemovedAction struct {
Type ActionType `json:"type"`
Expand Down
33 changes: 2 additions & 31 deletions clients/go/ahptypes/commands.generated.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -318,9 +318,8 @@ type CreateSessionParams struct {
// The working directories the session's agent is granted tool access to.
// A session may span multiple directories; they are equal peers except when
// the agent advertises
// {@link MultipleWorkingDirectoriesCapability.requiresPrimary}, in which case
// one of them should be designated the primary via
// {@link primaryWorkingDirectory}.
// {@link MultipleWorkingDirectoriesCapability.immutablePrimary} (in which case
// the first entry is a fixed process root).
//
// A client MUST NOT supply more than one entry unless the agent advertises
// {@link AgentCapabilities.multipleWorkingDirectories}; a server without that
Expand All @@ -332,24 +331,6 @@ type CreateSessionParams struct {
// Ignored for forked sessions — a fork inherits its working directories
// from the source session identified by `fork`.
WorkingDirectories []URI `json:"workingDirectories,omitempty"`
// The primary working directory for the session's **default chat**.
//
// A session has no primary of its own — primary is a per-chat notion (see
// {@link ChatState.primaryWorkingDirectory}). But `createSession` implicitly
// creates the session's default chat, and there is no separate `createChat`
// call to carry that chat's create-time fields. This field is therefore the
// only place a client can designate the **default chat's** primary at birth;
// it is copied into that chat's read-only `primaryWorkingDirectory`. For any
// non-default chat, pass {@link CreateChatParams.primaryWorkingDirectory}
// instead.
//
// When set, it MUST be one of {@link workingDirectories}. A client SHOULD
// supply this when the agent advertises
// {@link MultipleWorkingDirectoriesCapability.requiresPrimary}; a host MAY
// reject creation that omits it, or fall back to the first entry of
// `workingDirectories`. Ignored for forked sessions (a fork inherits the
// source session's chats and their primaries).
PrimaryWorkingDirectory *URI `json:"primaryWorkingDirectory,omitempty"`
// Fork from an existing session. The new session is populated with content
// from the source session up to and including the specified turn's response.
Fork *SessionForkSource `json:"fork,omitempty"`
Expand Down Expand Up @@ -452,16 +433,6 @@ type CreateChatParams struct {
// A client MUST NOT supply this field unless the agent advertises
// {@link AgentCapabilities.multipleWorkingDirectories}.
WorkingDirectories []URI `json:"workingDirectories,omitempty"`
// The chat's primary working directory — the distinguished root this chat is
// centered on. When set, it MUST be one of the chat's effective working
// directories ({@link workingDirectories}, or the session's set when that is
// omitted). A client SHOULD supply this when the agent advertises
// {@link MultipleWorkingDirectoriesCapability.requiresPrimary}; a host MAY
// reject creation that omits it, or fall back to the first of the chat's
// directories. Fixed at creation and reported (read-only) on
// {@link ChatState.primaryWorkingDirectory}. Ignored for forks (a chat whose
// `source.kind` is `"fork"` inherits the source chat's primary).
PrimaryWorkingDirectory *URI `json:"primaryWorkingDirectory,omitempty"`
}

// Disposes a chat and cleans up server-side resources.
Expand Down
2 changes: 0 additions & 2 deletions clients/go/ahptypes/common.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,6 @@ type PartialChatSummary struct {
Origin *ChatOrigin `json:"origin,omitempty"`
// The subset of the session's working directories this chat uses.
WorkingDirectories []URI `json:"workingDirectories,omitempty"`
// The chat's primary working directory.
PrimaryWorkingDirectory *URI `json:"primaryWorkingDirectory,omitempty"`
}

// ─── StringOrMarkdown ────────────────────────────────────────────────────
Expand Down
13 changes: 7 additions & 6 deletions clients/go/ahptypes/notifications.generated.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,12 +219,13 @@ type PartialSessionSummary struct {
Project *ProjectInfo `json:"project,omitempty"`
// The working directories the session's agent has tool access to, as
// maintained by the `session/workingDirectorySet` /
// `session/workingDirectoryRemoved` actions. Directories are **equal peers** —
// the session has no primary. Individual chats MAY restrict to a subset via
// {@link ChatSummary.workingDirectories | their own `workingDirectories`} and
// designate one of their own directories as primary (see
// {@link ChatState.primaryWorkingDirectory}); a chat that sets no subset
// operates against this full set.
// `session/workingDirectoryRemoved` actions. Directories are equal peers
// except when the agent advertises
// {@link MultipleWorkingDirectoriesCapability.immutablePrimary} (the first
// entry is then a fixed process root). Individual chats MAY restrict to a
// subset via {@link ChatSummary.workingDirectories | their own
// `workingDirectories`}; a chat that sets none operates against this full
// set.
WorkingDirectories []URI `json:"workingDirectories,omitempty"`
// Lightweight summary of this session's inline annotations channel
// (`ahp-session:/<uuid>/annotations`). Surfaced so badge UI can render
Expand Down
68 changes: 26 additions & 42 deletions clients/go/ahptypes/state.generated.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -590,8 +590,8 @@ type AgentCapabilities struct {
MultipleChats *MultipleChatsCapability `json:"multipleChats,omitempty"`
// The session's agent can be granted tool access to more than one working
// directory. The directories are treated as equal peers except where the
// agent advertises {@link MultipleWorkingDirectoriesCapability.requiresPrimary}
// (some backends need one directory designated as a primary root).
// agent advertises {@link MultipleWorkingDirectoriesCapability.immutablePrimary}
// (some backends pin their first directory as a fixed process root).
//
// When absent, clients MUST NOT mutate a session's or chat's working-directory
// set and MUST NOT set more than one entry in
Expand Down Expand Up @@ -621,19 +621,17 @@ type MultipleChatsCapability struct {

// Options for the {@link AgentCapabilities.multipleWorkingDirectories} capability.
type MultipleWorkingDirectoriesCapability struct {
// The agent requires each chat to designate one of its working directories as
// the **primary** — a distinguished root the chat is centered on (e.g. the
// agent's process root for that chat, the default location for relative
// paths). Primary is a **per-chat** notion, fixed at chat creation. When
// `true`, a client SHOULD supply {@link CreateChatParams.primaryWorkingDirectory}
// (and {@link CreateSessionParams.primaryWorkingDirectory}, which seeds the
// session's default chat); a host MAY reject creation that omits it, or fall
// back to the first entry of the chat's working directories. The chosen
// primary is reported (read-only) on {@link ChatState.primaryWorkingDirectory}.
// The agent's **first** working directory (index `0` of
// {@link CreateSessionParams.workingDirectories}) is an immutable primary:
// it is fixed for the lifetime of the session — clients MUST NOT remove or
// reorder it. Additional directories after it remain equal peers that can be
// added and removed freely.
//
// When absent or `false`, the agent has no primary — all directories are
// equal peers and clients need not designate one.
RequiresPrimary *bool `json:"requiresPrimary,omitempty"`
// Advertised by backends whose agent process is rooted at a single directory
// that cannot change once the session has started (e.g. the SDK's primary
// `workingDirectory`). When absent or `false`, all directories are equal
// peers and any of them may be removed.
ImmutablePrimary *bool `json:"immutablePrimary,omitempty"`
}

type SessionModelInfo struct {
Expand Down Expand Up @@ -758,12 +756,13 @@ type SessionState struct {
Project *ProjectInfo `json:"project,omitempty"`
// The working directories the session's agent has tool access to, as
// maintained by the `session/workingDirectorySet` /
// `session/workingDirectoryRemoved` actions. Directories are **equal peers** —
// the session has no primary. Individual chats MAY restrict to a subset via
// {@link ChatSummary.workingDirectories | their own `workingDirectories`} and
// designate one of their own directories as primary (see
// {@link ChatState.primaryWorkingDirectory}); a chat that sets no subset
// operates against this full set.
// `session/workingDirectoryRemoved` actions. Directories are equal peers
// except when the agent advertises
// {@link MultipleWorkingDirectoriesCapability.immutablePrimary} (the first
// entry is then a fixed process root). Individual chats MAY restrict to a
// subset via {@link ChatSummary.workingDirectories | their own
// `workingDirectories`}; a chat that sets none operates against this full
// set.
WorkingDirectories []URI `json:"workingDirectories,omitempty"`
// Lightweight summary of this session's inline annotations channel
// (`ahp-session:/<uuid>/annotations`). Surfaced so badge UI can render
Expand Down Expand Up @@ -1023,12 +1022,13 @@ type SessionSummary struct {
Project *ProjectInfo `json:"project,omitempty"`
// The working directories the session's agent has tool access to, as
// maintained by the `session/workingDirectorySet` /
// `session/workingDirectoryRemoved` actions. Directories are **equal peers** —
// the session has no primary. Individual chats MAY restrict to a subset via
// {@link ChatSummary.workingDirectories | their own `workingDirectories`} and
// designate one of their own directories as primary (see
// {@link ChatState.primaryWorkingDirectory}); a chat that sets no subset
// operates against this full set.
// `session/workingDirectoryRemoved` actions. Directories are equal peers
// except when the agent advertises
// {@link MultipleWorkingDirectoriesCapability.immutablePrimary} (the first
// entry is then a fixed process root). Individual chats MAY restrict to a
// subset via {@link ChatSummary.workingDirectories | their own
// `workingDirectories`}; a chat that sets none operates against this full
// set.
WorkingDirectories []URI `json:"workingDirectories,omitempty"`
// Lightweight summary of this session's inline annotations channel
// (`ahp-session:/<uuid>/annotations`). Surfaced so badge UI can render
Expand Down Expand Up @@ -1108,19 +1108,6 @@ type ChatState struct {
// Dispatch `chat/workingDirectorySet` / `chat/workingDirectoryRemoved` to
// update the subset on a running chat.
WorkingDirectories []URI `json:"workingDirectories,omitempty"`
// The chat's primary working directory — the distinguished root this chat is
// centered on (e.g. the agent's process root for this chat, the default
// location for relative paths). MUST be one of this chat's effective working
// directories ({@link workingDirectories}, or the session's set when that is
// absent). Present when the agent advertises
// {@link MultipleWorkingDirectoriesCapability.requiresPrimary}.
//
// **Read-only and fixed at creation.** It is set from
// {@link CreateChatParams.primaryWorkingDirectory} (or, for the session's
// default chat, {@link CreateSessionParams.primaryWorkingDirectory}) and does
// not change over the chat's lifetime — there is no action to mutate it, and
// it does not participate in `session/chatUpdated`.
PrimaryWorkingDirectory *URI `json:"primaryWorkingDirectory,omitempty"`
// Completed turns
Turns []Turn `json:"turns"`
// Cursor for loading older completed turns into this chat state.
Expand Down Expand Up @@ -1177,9 +1164,6 @@ type ChatSummary struct {
// The subset of the session's working directories this chat uses.
// See {@link ChatState.workingDirectories} for the full semantics.
WorkingDirectories []URI `json:"workingDirectories,omitempty"`
// The chat's primary working directory.
// See {@link ChatState.primaryWorkingDirectory} for the full semantics.
PrimaryWorkingDirectory *URI `json:"primaryWorkingDirectory,omitempty"`
}

// Immutable selected-text snapshot captured when a side chat is created.
Expand Down
7 changes: 1 addition & 6 deletions ...nts/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Actions.generated.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1510,12 +1510,7 @@ data class PartialChatSummary(
* The subset of the session's working directories this chat uses.
* See {@link ChatState.workingDirectories} for the full semantics.
*/
val workingDirectories: List<String>? = null,
/**
* The chat's primary working directory.
* See {@link ChatState.primaryWorkingDirectory} for the full semantics.
*/
val primaryWorkingDirectory: String? = null
val workingDirectories: List<String>? = null
)

// ─── StateAction Union ──────────────────────────────────────────────────────
Expand Down
39 changes: 3 additions & 36 deletions ...ts/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Commands.generated.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -505,9 +505,8 @@ data class CreateSessionParams(
* The working directories the session's agent is granted tool access to.
* A session may span multiple directories; they are equal peers except when
* the agent advertises
* {@link MultipleWorkingDirectoriesCapability.requiresPrimary}, in which case
* one of them should be designated the primary via
* {@link primaryWorkingDirectory}.
* {@link MultipleWorkingDirectoriesCapability.immutablePrimary} (in which case
* the first entry is a fixed process root).
*
* A client MUST NOT supply more than one entry unless the agent advertises
* {@link AgentCapabilities.multipleWorkingDirectories}; a server without that
Expand All @@ -520,26 +519,6 @@ data class CreateSessionParams(
* from the source session identified by `fork`.
*/
val workingDirectories: List<String>? = null,
/**
* The primary working directory for the session's **default chat**.
*
* A session has no primary of its own — primary is a per-chat notion (see
* {@link ChatState.primaryWorkingDirectory}). But `createSession` implicitly
* creates the session's default chat, and there is no separate `createChat`
* call to carry that chat's create-time fields. This field is therefore the
* only place a client can designate the **default chat's** primary at birth;
* it is copied into that chat's read-only `primaryWorkingDirectory`. For any
* non-default chat, pass {@link CreateChatParams.primaryWorkingDirectory}
* instead.
*
* When set, it MUST be one of {@link workingDirectories}. A client SHOULD
* supply this when the agent advertises
* {@link MultipleWorkingDirectoriesCapability.requiresPrimary}; a host MAY
* reject creation that omits it, or fall back to the first entry of
* `workingDirectories`. Ignored for forked sessions (a fork inherits the
* source session's chats and their primaries).
*/
val primaryWorkingDirectory: String? = null,
/**
* Fork from an existing session. The new session is populated with content
* from the source session up to and including the specified turn's response.
Expand Down Expand Up @@ -623,19 +602,7 @@ data class CreateChatParams(
* A client MUST NOT supply this field unless the agent advertises
* {@link AgentCapabilities.multipleWorkingDirectories}.
*/
val workingDirectories: List<String>? = null,
/**
* The chat's primary working directory — the distinguished root this chat is
* centered on. When set, it MUST be one of the chat's effective working
* directories ({@link workingDirectories}, or the session's set when that is
* omitted). A client SHOULD supply this when the agent advertises
* {@link MultipleWorkingDirectoriesCapability.requiresPrimary}; a host MAY
* reject creation that omits it, or fall back to the first of the chat's
* directories. Fixed at creation and reported (read-only) on
* {@link ChatState.primaryWorkingDirectory}. Ignored for forks (a chat whose
* `source.kind` is `"fork"` inherits the source chat's primary).
*/
val primaryWorkingDirectory: String? = null
val workingDirectories: List<String>? = null
)

@Serializable
Expand Down
13 changes: 7 additions & 6 deletions ...tlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Notifications.generated.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,12 +198,13 @@ data class PartialSessionSummary(
/**
* The working directories the session's agent has tool access to, as
* maintained by the `session/workingDirectorySet` /
* `session/workingDirectoryRemoved` actions. Directories are **equal peers** —
* the session has no primary. Individual chats MAY restrict to a subset via
* {@link ChatSummary.workingDirectories | their own `workingDirectories`} and
* designate one of their own directories as primary (see
* {@link ChatState.primaryWorkingDirectory}); a chat that sets no subset
* operates against this full set.
* `session/workingDirectoryRemoved` actions. Directories are equal peers
* except when the agent advertises
* {@link MultipleWorkingDirectoriesCapability.immutablePrimary} (the first
* entry is then a fixed process root). Individual chats MAY restrict to a
* subset via {@link ChatSummary.workingDirectories | their own
* `workingDirectories`}; a chat that sets none operates against this full
* set.
*/
val workingDirectories: List<String>? = null,
/**
Expand Down
Loading
Loading