1
>
/*---------------------------------------------------------------------------------------------
agentCompletionAttachmentMeta.ts
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import type { SimpleMessageAttachment } from '../state/protocol/state.js';
7
>
8
>
/**
9
>
* Well-known typed views over a `SimpleMessageAttachment`'s `_meta` bag as
10
>
* produced by the `completions` command, populated by the slash-command and
11
>
* skill completion providers and read by the session handler. Read the bag
12
>
* through {@link readCompletionAttachmentMeta} rather than indexing `_meta`
13
>
* directly. Two variants are distinguished by which discriminating key is
14
>
* present: a slash command (`command`) or a skill (`uri`).
15
>
*/
16
>
17
>
/**
18
>
* A client-side side effect a command completion carries. When present, the
19
>
* workbench interprets it on accept (see the shared agent-host completion action
20
>
* handler) rather than treating the item as a plain text/reference insertion.
21
>
*
22
>
* Used by Copilot agent-host permission/mode toggles (e.g. `/yolo`,
23
>
* `/autopilot on`): the item applies a well-known session-config change. Whether
24
>
* the item leaves text behind is expressed by its `insertText` (empty for a pure
25
>
* toggle; `/command ` for an item that keeps the text so an argument can be
26
>
* typed, with {@link ICommandCompletionAttachmentMeta.argumentHint} as ghost text).
27
>
*/
28
>
export interface IAgentHostCompletionAction {
29
>
/**
30
>
* A partial agent-host session-config change to apply when the completion is
31
>
* accepted, keyed by well-known session-config property (e.g. `autoApprove`,
32
>
* `mode`) to the string-enum value. Applied via the active session's provider
33
>
* so the corresponding picker updates reactively.
34
>
*/
35
>
readonly applyConfig?: Readonly<Record<string, string>>;
36
>
}
37
>
38
>
/**
39
>
* The `_meta` shape attached to a `completions` result that resolves to a slash
40
>
* command.
41
>
*/
42
>
export interface ICommandCompletionAttachmentMeta {
43
>
/** The slash command name (without the leading `/`). */
44
>
readonly command: string;
45
>
/** Optional human-readable description of the command. */
46
>
readonly description?: string;
47
>
/**
48
>
* Optional hint describing the argument the command expects. Rendered as
49
>
* inline placeholder (ghost text) after an accepted command completion.
50
>
*/
51
>
readonly argumentHint?: string;
52
>
/**
53
>
* Optional client-side action to run when the completion is accepted (e.g. a
54
>
* permission/mode session-config toggle). See {@link IAgentHostCompletionAction}.
55
>
*/
56
>
readonly action?: IAgentHostCompletionAction;
57
>
}
58
>
59
>
/**
60
>
* The `_meta` shape attached to a `completions` result that resolves to a skill.
61
>
*/
62
>
export interface ISkillCompletionAttachmentMeta {
63
>
/** The skill resource URI as a string. */
64
>
readonly uri: string;
65
>
/** Optional internal name of the skill. */
66
>
readonly name?: string;
67
>
/** Optional human-readable display name (e.g. the slash-command name). */
68
>
readonly displayName?: string;
69
>
/** Optional human-readable description of the skill. */
70
>
readonly description?: string;
71
>
}
72
>
73
>
/**
74
>
* A typed, discriminated view over the well-known `completions` attachment
75
>
* `_meta` variants. The `kind` discriminant is computed by
76
>
* {@link readCompletionAttachmentMeta} from which key is present on the wire; it
77
>
* is not itself carried in `_meta`.
78
>
*/
79
>
export type CompletionAttachmentMeta =
80
>
| ({ readonly kind: 'command' } & ICommandCompletionAttachmentMeta)
81
>
| ({ readonly kind: 'skill' } & ISkillCompletionAttachmentMeta);
82
>
83
>
/**
84
>
* Reads the well-known `completions` attachment `_meta` keys, classifying the
85
>
* bag into a {@link CompletionAttachmentMeta} variant by its discriminating key
86
>
* (`command` for a slash command, `uri` for a skill). Returns `undefined` when
87
>
* the bag is absent or matches neither variant; wrong-typed keys are dropped.
88
>
*/
89
>
export function readCompletionAttachmentMeta(attachment: SimpleMessageAttachment): CompletionAttachmentMeta | undefined {
90
const meta = attachment._meta;
91
if (!meta || typeof meta !== 'object' || Array.isArray(meta)) {