@pstdio/sdk 0.5.0 → 0.6.0

package/dist/client/extensions.d.ts

@@ -1,8 +1,9 @@
-import type { CommandExecuteRequest, CommandExecuteResponse, EnableInstalledExtensionRequest, EnableInstalledExtensionResponse, ListExtensionCommandsResponse, UpdateInstalledExtensionTemplateInput, UpdateInstalledExtensionTemplateResponse } from "pstdio-api-contracts";
+import type { CommandExecuteRequest, CommandExecuteResponse, EnableInstalledExtensionRequest, EnableInstalledExtensionResponse, ListExtensionAppearanceResponse, ListExtensionCommandsResponse, UpdateInstalledExtensionTemplateInput, UpdateInstalledExtensionTemplateResponse } from "pstdio-api-contracts";
 import type { RequestFn } from "./request";
 export type ExtensionClient = {
     enableInstalled(projectId: string, installName: string, request: EnableInstalledExtensionRequest): Promise<EnableInstalledExtensionResponse>;
     updateInstalledTemplate(installName: string, templateKey: string, input: UpdateInstalledExtensionTemplateInput): Promise<UpdateInstalledExtensionTemplateResponse>;
+    listAppearance(projectId: string): Promise<ListExtensionAppearanceResponse>;
     listCommands(projectId: string): Promise<ListExtensionCommandsResponse>;
     execute(commandId: string, request: CommandExecuteRequest): Promise<CommandExecuteResponse>;
 };

package/dist/client/index.js

@@ -28,6 +28,7 @@ var createExtensionClient = (request) => ({
     method: "PUT",
     body
   }),
+  listAppearance: (projectId) => request(`/v1/projects/${projectId}/extensions/appearance`),
   listCommands: (projectId) => request(`/v1/projects/${projectId}/extensions/commands`),
   execute: (commandId, input) => {
     const { projectId, ...body } = input;

package/dist/extensions/define-extension.d.ts

@@ -1,16 +1,15 @@
 import type { ExtensionDefinition } from "./types/extension";
+type ExactExtensionDefinition<TExtension extends ExtensionDefinition> = TExtension & Record<Exclude<keyof TExtension, keyof ExtensionDefinition>, never>;
 /**
- * Identity helper that preserves the literal type of the passed extension. Authors get
- * full autocomplete on contributions, and `commandsOf(ext)` can derive typed refs from
- * the returned definition.
+ * Identity helper that preserves the literal type of the passed contributions. Authors
+ * get full autocomplete on contributions, and `commandsOf(packageName, ext)` can derive typed refs
+ * from the returned definition. Extension identity (id, name, version, description,
+ * publisher, engines.pstdio) lives in package.json.
  *
  * @example
  *   export default defineExtension({
- *     id: "pstdio.example",
- *     namespace: "example",
- *     name: "Example",
- *     apiVersion: "1",
  *     commands: { ... },
  *   });
  */
-export declare const defineExtension: <const TExtension extends ExtensionDefinition>(extension: TExtension) => TExtension;
+export declare const defineExtension: <const TExtension extends ExtensionDefinition>(extension: ExactExtensionDefinition<TExtension>) => TExtension;
+export {};

package/dist/extensions/index.d.ts

@@ -7,3 +7,5 @@ export { params } from "./params";
 export { commandEvent, commandRef, commandsOf, eventRef } from "./refs";
 export { defineSlot } from "./slots";
 export type * from "./types";
+export { EXTENSION_API_VERSION } from "./types/extension";
+export { ALWAYS_AVAILABLE_WEBVIEW_CAPABILITIES, WEBVIEW_DECLARABLE_CAPABILITIES, WEBVIEW_HOST_CAPABILITIES, WEBVIEW_HOST_CAPABILITY_VERSION, } from "./types/webview-capabilities";

package/dist/extensions/index.js

@@ -17,11 +17,11 @@ var eventRef = (id) => ({ id });
 var commandEvent = (command, phase) => ({
   id: `command.${phase}:${command.id}`
 });
-var commandsOf = (extension) => {
+var commandsOf = (packageName, extension) => {
   const refs = {};
   const commands = extension.commands ?? {};
   for (const key of Object.keys(commands)) {
-    refs[key] = { id: `${extension.namespace}.${key}` };
+    refs[key] = { id: `${packageName}.${key}` };
   }
   return refs;
 };
@@ -98,6 +98,22 @@ var params = {
   resource: (options) => ({ type: "resource", ...options }),
   json: (options = {}) => ({ type: "json", ...options })
 };
+// src/extensions/types/extension.ts
+var EXTENSION_API_VERSION = "1.0.0";
+// src/extensions/types/webview-capabilities.ts
+var WEBVIEW_HOST_CAPABILITY_VERSION = 1;
+var WEBVIEW_DECLARABLE_CAPABILITIES = [
+  "commands.execute",
+  "resource.open",
+  "notification.show",
+  "preferences.get",
+  "preferences.set"
+];
+var ALWAYS_AVAILABLE_WEBVIEW_CAPABILITIES = ["host.dispatchKeyboardEvent"];
+var WEBVIEW_HOST_CAPABILITIES = [
+  ...WEBVIEW_DECLARABLE_CAPABILITIES,
+  ...ALWAYS_AVAILABLE_WEBVIEW_CAPABILITIES
+];
 export {
   workspaceSlots,
   workspaceEvents,
@@ -116,5 +132,10 @@ export {
   defineCommand,
   commandsOf,
   commandRef,
-  commandEvent
+  commandEvent,
+  WEBVIEW_HOST_CAPABILITY_VERSION,
+  WEBVIEW_HOST_CAPABILITIES,
+  WEBVIEW_DECLARABLE_CAPABILITIES,
+  EXTENSION_API_VERSION,
+  ALWAYS_AVAILABLE_WEBVIEW_CAPABILITIES
 };

package/dist/extensions/package-asset.d.ts

@@ -5,6 +5,6 @@ import type { PackageAssetDescriptor } from "./types/resources";
  * so the runtime can locate the file no matter where the extension is installed.
  *
  * @example
- *   webview: { entry: packageAsset("./dist/page.html", import.meta.url) }
+ *   webview: { entry: packageAsset("./src/page.tsx", import.meta.url) }
  */
 export declare const packageAsset: (path: string, baseUrl: string) => PackageAssetDescriptor;

package/dist/extensions/refs.d.ts

@@ -4,9 +4,9 @@ import type { CommandDefinition } from "./types/extension";
 import type { Struct } from "./types/json";
 import type { ParamObjectSchema, ParamsOf } from "./types/params";
 /**
- * Build a typed reference to a command by id. Authors generally prefer `commandsOf(ext)`,
- * which derives refs from the extension definition so a renamed command becomes a type
- * error at every call site.
+ * Build a typed reference to a command by id. Authors generally prefer
+ * `commandsOf(packageName, ext)`, which derives refs from the extension definition
+ * so a renamed command becomes a type error at every call site.
  */
 export declare const commandRef: <TParams extends Struct = Struct, TResult = unknown>(id: string) => CommandRef<TParams, TResult>;
 /** Build a typed reference to an event by id. */
@@ -23,16 +23,18 @@ type CommandsRefMap<TCommands extends CommandsRecord> = {
     [K in keyof TCommands]: CommandRefFromDefinition<TCommands[K]>;
 };
 /**
- * Derive typed `CommandRef`s from an extension. Renaming a command in the definition
- * surfaces as a type error wherever the ref is used.
+ * Derive typed `CommandRef`s from an extension contribution object. Renaming a
+ * command in the definition surfaces as a type error wherever the ref is used.
+ *
+ * The package name is explicit because identity now lives in package.json, not in
+ * `defineExtension()`.
  *
  * @example
- *   const ext = defineExtension({ id: "lab", namespace: "lab", commands: { ... } });
- *   const labCommands = commandsOf(ext);
+ *   const ext = defineExtension({ commands: { ... } });
+ *   const labCommands = commandsOf("extension-lab", ext);
  *   labCommands.awaken; // CommandRef<{ title: string }, ...>
  */
 export declare const commandsOf: <TExtension extends {
-    namespace: string;
     commands?: CommandsRecord;
-}>(extension: TExtension) => CommandsRefMap<NonNullable<TExtension["commands"]>>;
+}>(packageName: string, extension: TExtension) => CommandsRefMap<NonNullable<TExtension["commands"]>>;
 export {};

package/dist/extensions/types/context.d.ts

@@ -151,7 +151,8 @@ export interface ExtensionSettingsApi<TSettings extends Struct = Struct> {
 export interface ExtensionContextBase {
     projectId: string;
     extensionId: string;
-    namespace: string;
+    /** Extension package name. Used for grouping/prefixing user-facing references. */
+    name: string;
     repo?: RepoContext;
     source?: CommandSource;
     storage: ExtensionStorageApi;

package/dist/extensions/types/contributions.d.ts

@@ -2,6 +2,7 @@ import type { CommandRef, CommandSource } from "./commands";
 import type { JsonObject, Struct } from "./json";
 import type { PackageAssetDescriptor } from "./resources";
 import type { SlotRef } from "./slots";
+import type { WebviewCapabilityDeclaration } from "./webview-capabilities";
 export interface CliContribution {
     path?: string[];
     globalAliases?: string[][];
@@ -40,7 +41,7 @@ export interface NavigationContribution<TSlotContext extends Struct = Struct, TP
 export interface WebviewContribution {
     entry: PackageAssetDescriptor;
     title?: string;
-    sandbox?: "default" | "strict";
+    capabilities?: WebviewCapabilityDeclaration[];
 }
 export interface ViewContribution<TSlotContext extends Struct = Struct> {
     title: string;
@@ -65,7 +66,7 @@ export interface RendererContribution<TSlotContext extends Struct = Struct> {
     webview: WebviewContribution;
 }
 export interface ArtifactMountContribution {
-    /** Relative path under .pstdio/<extension.namespace>/. */
+    /** Relative path under .pstdio/<extension.name>/. */
     path: string;
     label: string;
     repoRole?: "default" | "selected" | "workspace";
@@ -85,3 +86,17 @@ export interface SkillContribution {
     source: PackageAssetDescriptor;
     description?: string;
 }
+export type ThemeMode = "light" | "dark";
+export interface ThemeContribution {
+    title: string;
+    source: PackageAssetDescriptor;
+    format: "vscode-color-theme";
+    mode?: ThemeMode;
+    description?: string;
+}
+export interface FileIconThemeContribution {
+    title: string;
+    source: PackageAssetDescriptor;
+    format: "vscode-file-icon-theme";
+    description?: string;
+}

package/dist/extensions/types/extension.d.ts

@@ -1,12 +1,12 @@
 import type { CommandRef } from "./commands";
 import type { CommandMiddlewareHandler, CommandRunHandler, EventContext, ExtensionContextBase, MigrationContext, SetupContext } from "./context";
-import type { ArtifactMountContribution, CliContribution, MenuContribution, NavigationContribution, RendererContribution, RouteContribution, SettingsPanelContribution, SkillContribution, TemplateContribution, TemplateTypeContribution, ViewContribution } from "./contributions";
+import type { ArtifactMountContribution, CliContribution, FileIconThemeContribution, MenuContribution, NavigationContribution, RendererContribution, RouteContribution, SettingsPanelContribution, SkillContribution, TemplateContribution, TemplateTypeContribution, ThemeContribution, ViewContribution } from "./contributions";
 import type { EventRef } from "./events";
 import type { JsonObject, MaybePromise, Struct } from "./json";
 import type { ParamObjectSchema, ParamsOf } from "./params";
 import type { SlotRef } from "./slots";
-/** API version of an extension's manifest. The runtime uses this to detect old extensions. */
-export type ExtensionApiVersion = "1";
+/** Current host extension API version. `engines.pstdio` in package.json is a semver range checked against this. */
+export declare const EXTENSION_API_VERSION = "1.0.0";
 type SchemaParams<TSchema extends ParamObjectSchema | undefined> = TSchema extends ParamObjectSchema ? ParamsOf<TSchema> : Struct;
 /**
  * A command exposed by an extension. The `params` schema (typed via `params.*`) drives
@@ -96,21 +96,29 @@ export interface LocalExtensionSource {
 export interface ProjectExtensionInstance {
     projectId: string;
     extensionId: string;
-    namespace: string;
+    name: string;
     sourceName: string;
     enabled: boolean;
     config: JsonObject;
 }
-/** Identifying metadata for an extension. */
-export interface ExtensionMetadata {
-    id: string;
-    namespace: string;
+/** Validated view of an extension's package.json identity fields. */
+export interface PackageManifest {
+    /** Extension package name. Matches `^[a-z][a-z0-9-]*$`. */
     name: string;
-    version?: string;
+    /** Package version (semver). */
+    version: string;
+    /** Optional human-friendly name. Falls back to `name`. */
+    displayName?: string;
+    /** Optional package description. */
     description?: string;
-    /** Manifest API version. The runtime uses this to detect incompatible extensions. */
-    apiVersion: ExtensionApiVersion;
-    settings?: ParamObjectSchema;
+    /** Publisher segment of the extension id. Matches `^[a-z][a-z0-9-]*$`. */
+    publisher: string;
+    /** Relative path to the contributions entry module. */
+    main: string;
+    /** Semver range checked against the host extension API version. */
+    enginesPstdio: string;
+    /** Derived `${publisher}.${name}`. */
+    id: string;
 }
 /** UI surface contributions: slots, routes, panels, renderers. */
 export interface UiContributions {
@@ -135,6 +143,8 @@ export interface AssetContributions {
     templateTypes?: Record<string, TemplateTypeContribution>;
     templates?: Record<string, TemplateContribution>;
     skills?: Record<string, SkillContribution>;
+    themes?: Record<string, ThemeContribution>;
+    fileIconThemes?: Record<string, FileIconThemeContribution>;
 }
 /** Provider contributions: harnesses, workspace types. */
 export interface ProviderContributions {
@@ -147,10 +157,12 @@ export interface ExtensionLifecycle {
     migrate?: (ctx: MigrationContext, fromVersion: string | null) => MaybePromise<void>;
 }
 /**
- * The full shape of an extension manifest. Composed from focused capability mixins so
- * each surface is independently discoverable.
+ * The full shape of an extension's contributions module. Identity (id, name, version,
+ * description, etc.) lives in `package.json`; `defineExtension` only accepts
+ * contribution surfaces.
  */
-export interface ExtensionDefinition extends ExtensionMetadata, UiContributions, BehaviourContributions, AssetContributions, ProviderContributions, ExtensionLifecycle {
+export interface ExtensionDefinition extends UiContributions, BehaviourContributions, AssetContributions, ProviderContributions, ExtensionLifecycle {
+    settings?: ParamObjectSchema;
 }
 export type ExtensionSourceKind = "local" | "package" | "builtin";
 export {};

package/dist/extensions/types/index.d.ts

@@ -7,3 +7,4 @@ export type * from "./json";
 export type * from "./params";
 export type * from "./resources";
 export type * from "./slots";
+export * from "./webview-capabilities";

package/dist/extensions/types/webview-capabilities.d.ts

@@ -0,0 +1,55 @@
+import type { JsonObject } from "./json";
+import type { RepoContext, ResourceRef } from "./resources";
+export declare const WEBVIEW_HOST_CAPABILITY_VERSION = 1;
+export declare const WEBVIEW_DECLARABLE_CAPABILITIES: readonly ["commands.execute", "resource.open", "notification.show", "preferences.get", "preferences.set"];
+export declare const ALWAYS_AVAILABLE_WEBVIEW_CAPABILITIES: readonly ["host.dispatchKeyboardEvent"];
+export declare const WEBVIEW_HOST_CAPABILITIES: readonly ["commands.execute", "resource.open", "notification.show", "preferences.get", "preferences.set", "host.dispatchKeyboardEvent"];
+export type WebviewHostCapability = (typeof WEBVIEW_HOST_CAPABILITIES)[number];
+export type WebviewDeclarableCapability = (typeof WEBVIEW_DECLARABLE_CAPABILITIES)[number];
+export type WebviewCapabilityDeclaration = WebviewDeclarableCapability | `${WebviewDeclarableCapability}@${typeof WEBVIEW_HOST_CAPABILITY_VERSION}`;
+export interface WebviewCommandsExecuteParams {
+    commandId: string;
+    params?: JsonObject;
+    resource?: ResourceRef;
+    repo?: RepoContext;
+    metadata?: JsonObject;
+}
+export interface WebviewResourceOpenParams {
+    href?: string;
+    resource?: ResourceRef;
+    input?: {
+        replaceActive?: boolean;
+    };
+}
+export interface WebviewNotificationShowParams {
+    level: "info" | "success" | "warning" | "error";
+    title: string;
+    message?: string;
+}
+export interface WebviewPreferencesGetParams {
+    name: string;
+    scope?: {
+        scope: "default" | "user" | "project" | "repo" | "workspace" | "extension" | "session";
+        scopeId?: string;
+    };
+}
+export interface WebviewPreferencesSetParams extends WebviewPreferencesGetParams {
+    value: boolean | number | string | string[] | number[] | boolean[] | Record<string, unknown>;
+}
+export interface WebviewKeyboardEventParams {
+    key?: string;
+    code?: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+    repeat?: boolean;
+}
+export interface WebviewHostCapabilityParams {
+    "commands.execute": WebviewCommandsExecuteParams;
+    "resource.open": WebviewResourceOpenParams;
+    "notification.show": WebviewNotificationShowParams;
+    "preferences.get": WebviewPreferencesGetParams;
+    "preferences.set": WebviewPreferencesSetParams;
+    "host.dispatchKeyboardEvent": WebviewKeyboardEventParams;
+}

package/dist/hooks/session.d.ts

@@ -2,7 +2,7 @@ import type { BaseHookContext } from "./base";
 import type { HookTicket, HookWorkspace } from "./entities";
 export type SessionHookContext = BaseHookContext & {
     sessionId: string;
-    sessionStatus: "in_progress" | "awaiting_input" | "completed" | "failed" | "cancelled" | "disconnected";
+    sessionStatus: "in_progress" | "awaiting_input" | "queued" | "completed" | "failed" | "cancelled" | "disconnected";
     originalSessionId?: string;
     workspace?: HookWorkspace;
     workspaceId?: string;

package/dist/plugins/helpers/create-session.d.ts

@@ -5,7 +5,7 @@ export declare const createSession: (ctx: PluginHelperContext, input: CreateSess
     id: string;
     project_id: string | null;
     title: string;
-    status: "in_progress" | "awaiting_input" | "completed" | "failed" | "cancelled" | "disconnected";
+    status: "in_progress" | "awaiting_input" | "queued" | "completed" | "failed" | "cancelled" | "disconnected";
     archived: boolean;
     last_request_started: string | null;
     last_request_ended: string | null;

package/dist/plugins/helpers/followup-session.d.ts

@@ -7,7 +7,7 @@ export declare const followupSession: (ctx: PluginHelperContext, input: Followup
     id: string;
     project_id: string | null;
     title: string;
-    status: "in_progress" | "awaiting_input" | "completed" | "failed" | "cancelled" | "disconnected";
+    status: "in_progress" | "awaiting_input" | "queued" | "completed" | "failed" | "cancelled" | "disconnected";
     archived: boolean;
     last_request_started: string | null;
     last_request_ended: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pstdio/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/pufflyai/prompt-studio"