@astralform/js 8.3.0 → 8.4.0

package/dist/index.d.cts

@@ -756,6 +756,43 @@ interface SkillInfo {
     description: string;
     isEnabled: boolean;
 }
+/**
+ * A slash command the active agent offers — the system commands (`/new`,
+ * `/goal`, `/plan`, …) followed by its enabled skills, from
+ * `GET /v1/skills/commands`.
+ *
+ * The backend builds this list once and every surface reads it, so the web
+ * composer's "/" menu and the Telegram bot's command menu cannot drift.
+ */
+interface SlashCommand {
+    /** What the user types after the slash, and what the backend parses. */
+    name: string;
+    /** Human-readable label for the menu row. May be empty. */
+    displayName: string;
+    /** One line describing what the command does. May be empty. */
+    description: string;
+    /**
+     * The argument shape a row shows after the name, e.g. `"[goal]"`. Empty
+     * when the command takes none — never undefined, so a renderer can
+     * concatenate it without a guard.
+     */
+    argsHint: string;
+    /**
+     * Which surfaces can run this command (`"web"`, `"telegram"`).
+     *
+     * Always populated, whatever surface was asked for — a scoped list has
+     * already filtered on it, so every row there names at least the surface
+     * requested. It carries information only for `"all"`, where rows that
+     * cannot run everywhere sit next to rows that can. Empty rather than
+     * undefined for the same reason as `argsHint`.
+     */
+    surfaces: string[];
+}
+/**
+ * Who will execute the commands {@link AstralformClient.listSkillCommands}
+ * returns. `"web"` is the server's default: what `POST /v1/jobs` runs itself.
+ */
+type SlashCommandSurface = "web" | "telegram" | "all";
 interface JobCreateResponse {
     job_id: string;
     conversation_id: string;
@@ -1467,6 +1504,22 @@ declare class AstralformClient {
      */
     getModels(): Promise<ModelOption[]>;
     getSkills(): Promise<SkillInfo[]>;
+    /**
+     * List the slash commands the active agent offers — the system commands
+     * followed by its enabled skills. Backs the composer's "/" menu.
+     *
+     * @param surface Who will execute them. Omit for the server's default,
+     *   `"web"`: what `POST /v1/jobs` runs itself. `"telegram"` returns the
+     *   bot's commands under Telegram-valid names; `"all"` returns every
+     *   command, including those the other surfaces filter out — `surfaces` is
+     *   set on every row either way, and is what tells them apart here.
+     *
+     * The default surface is not sent as a query parameter. The server already
+     * defaults to `web`, so omitting it keeps the request byte-identical to
+     * what clients that call the raw path send today — same reasoning as
+     * {@link getConversationEvents}'s `toolOutputs`.
+     */
+    listSkillCommands(surface?: SlashCommandSurface): Promise<SlashCommand[]>;
     getConversationEvents(conversationId: string, jobId?: string, options?: {
         toolOutputs?: ToolOutputMode;
     }): Promise<ConversationEvent[]>;
@@ -2494,4 +2547,4 @@ declare function isEmbeddedResource(value: unknown): value is {
  */
 declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
 
-export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type AvailableRepositories, type AvailableRepository, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, type CodeProject, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EffortRung, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryProviderErrorPayload, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type NestedLlmUsagePayload, type NoteUpdatePayload, type PlanUpdatePayload, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type ThinkingDescriptor, type ThinkingRungOption, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolOutputMode, type ToolOutputStub, type ToolPermissionDeniedPayload, type ToolProgressPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, VOICE_POLISH_MODES, type VoiceConfig, type VoiceLLMMode, type VoicePolishEvent, type VoicePolishMode, type VoicePolishRequest, type VoiceTranscribeOptions, type VoiceTranscript, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, isToolOutputStub, isVoiceLLMMode, isVoicePolishMode, mapSseToChat, parseEmbeddedResource, parseVoicePolishFrame, replayEvents, streamJobSSE, translateDelta };
+export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type AvailableRepositories, type AvailableRepository, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, type CodeProject, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EffortRung, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryProviderErrorPayload, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type NestedLlmUsagePayload, type NoteUpdatePayload, type PlanUpdatePayload, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, type SlashCommand, type SlashCommandSurface, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type ThinkingDescriptor, type ThinkingRungOption, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolOutputMode, type ToolOutputStub, type ToolPermissionDeniedPayload, type ToolProgressPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, VOICE_POLISH_MODES, type VoiceConfig, type VoiceLLMMode, type VoicePolishEvent, type VoicePolishMode, type VoicePolishRequest, type VoiceTranscribeOptions, type VoiceTranscript, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, isToolOutputStub, isVoiceLLMMode, isVoicePolishMode, mapSseToChat, parseEmbeddedResource, parseVoicePolishFrame, replayEvents, streamJobSSE, translateDelta };

package/dist/index.d.ts

@@ -756,6 +756,43 @@ interface SkillInfo {
     description: string;
     isEnabled: boolean;
 }
+/**
+ * A slash command the active agent offers — the system commands (`/new`,
+ * `/goal`, `/plan`, …) followed by its enabled skills, from
+ * `GET /v1/skills/commands`.
+ *
+ * The backend builds this list once and every surface reads it, so the web
+ * composer's "/" menu and the Telegram bot's command menu cannot drift.
+ */
+interface SlashCommand {
+    /** What the user types after the slash, and what the backend parses. */
+    name: string;
+    /** Human-readable label for the menu row. May be empty. */
+    displayName: string;
+    /** One line describing what the command does. May be empty. */
+    description: string;
+    /**
+     * The argument shape a row shows after the name, e.g. `"[goal]"`. Empty
+     * when the command takes none — never undefined, so a renderer can
+     * concatenate it without a guard.
+     */
+    argsHint: string;
+    /**
+     * Which surfaces can run this command (`"web"`, `"telegram"`).
+     *
+     * Always populated, whatever surface was asked for — a scoped list has
+     * already filtered on it, so every row there names at least the surface
+     * requested. It carries information only for `"all"`, where rows that
+     * cannot run everywhere sit next to rows that can. Empty rather than
+     * undefined for the same reason as `argsHint`.
+     */
+    surfaces: string[];
+}
+/**
+ * Who will execute the commands {@link AstralformClient.listSkillCommands}
+ * returns. `"web"` is the server's default: what `POST /v1/jobs` runs itself.
+ */
+type SlashCommandSurface = "web" | "telegram" | "all";
 interface JobCreateResponse {
     job_id: string;
     conversation_id: string;
@@ -1467,6 +1504,22 @@ declare class AstralformClient {
      */
     getModels(): Promise<ModelOption[]>;
     getSkills(): Promise<SkillInfo[]>;
+    /**
+     * List the slash commands the active agent offers — the system commands
+     * followed by its enabled skills. Backs the composer's "/" menu.
+     *
+     * @param surface Who will execute them. Omit for the server's default,
+     *   `"web"`: what `POST /v1/jobs` runs itself. `"telegram"` returns the
+     *   bot's commands under Telegram-valid names; `"all"` returns every
+     *   command, including those the other surfaces filter out — `surfaces` is
+     *   set on every row either way, and is what tells them apart here.
+     *
+     * The default surface is not sent as a query parameter. The server already
+     * defaults to `web`, so omitting it keeps the request byte-identical to
+     * what clients that call the raw path send today — same reasoning as
+     * {@link getConversationEvents}'s `toolOutputs`.
+     */
+    listSkillCommands(surface?: SlashCommandSurface): Promise<SlashCommand[]>;
     getConversationEvents(conversationId: string, jobId?: string, options?: {
         toolOutputs?: ToolOutputMode;
     }): Promise<ConversationEvent[]>;
@@ -2494,4 +2547,4 @@ declare function isEmbeddedResource(value: unknown): value is {
  */
 declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
 
-export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type AvailableRepositories, type AvailableRepository, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, type CodeProject, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EffortRung, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryProviderErrorPayload, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type NestedLlmUsagePayload, type NoteUpdatePayload, type PlanUpdatePayload, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type ThinkingDescriptor, type ThinkingRungOption, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolOutputMode, type ToolOutputStub, type ToolPermissionDeniedPayload, type ToolProgressPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, VOICE_POLISH_MODES, type VoiceConfig, type VoiceLLMMode, type VoicePolishEvent, type VoicePolishMode, type VoicePolishRequest, type VoiceTranscribeOptions, type VoiceTranscript, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, isToolOutputStub, isVoiceLLMMode, isVoicePolishMode, mapSseToChat, parseEmbeddedResource, parseVoicePolishFrame, replayEvents, streamJobSSE, translateDelta };
+export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type AvailableRepositories, type AvailableRepository, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, type CodeProject, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EffortRung, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryProviderErrorPayload, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type NestedLlmUsagePayload, type NoteUpdatePayload, type PlanUpdatePayload, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, type SlashCommand, type SlashCommandSurface, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type ThinkingDescriptor, type ThinkingRungOption, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolOutputMode, type ToolOutputStub, type ToolPermissionDeniedPayload, type ToolProgressPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, VOICE_POLISH_MODES, type VoiceConfig, type VoiceLLMMode, type VoicePolishEvent, type VoicePolishMode, type VoicePolishRequest, type VoiceTranscribeOptions, type VoiceTranscript, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, isToolOutputStub, isVoiceLLMMode, isVoicePolishMode, mapSseToChat, parseEmbeddedResource, parseVoicePolishFrame, replayEvents, streamJobSSE, translateDelta };

package/dist/index.js

@@ -803,6 +803,37 @@ var AstralformClient = class {
     const raw = await this.get("/v1/skills");
     return raw.map((s) => camelizeKeys(s));
   }
+  /**
+   * List the slash commands the active agent offers — the system commands
+   * followed by its enabled skills. Backs the composer's "/" menu.
+   *
+   * @param surface Who will execute them. Omit for the server's default,
+   *   `"web"`: what `POST /v1/jobs` runs itself. `"telegram"` returns the
+   *   bot's commands under Telegram-valid names; `"all"` returns every
+   *   command, including those the other surfaces filter out — `surfaces` is
+   *   set on every row either way, and is what tells them apart here.
+   *
+   * The default surface is not sent as a query parameter. The server already
+   * defaults to `web`, so omitting it keeps the request byte-identical to
+   * what clients that call the raw path send today — same reasoning as
+   * {@link getConversationEvents}'s `toolOutputs`.
+   */
+  async listSkillCommands(surface) {
+    const query = surface && surface !== "web" ? `?surface=${surface}` : "";
+    const raw = await this.get(
+      `/v1/skills/commands${query}`
+    );
+    return raw.map((c) => {
+      const command = camelizeKeys(c);
+      return {
+        ...command,
+        displayName: command.displayName ?? "",
+        description: command.description ?? "",
+        argsHint: command.argsHint ?? "",
+        surfaces: command.surfaces ?? []
+      };
+    });
+  }
   async getConversationEvents(conversationId, jobId, options) {
     const params = new URLSearchParams();
     if (jobId) params.set("job_id", jobId);